TCIS.Pluggable.Abstractions 1.1.3

TCIS.Pluggable.Abstractions

The contract package of the TCIS Pluggable architecture. It defines pipeline steps, business rules, site modules, and connection-level tenant isolation.

Zero infrastructure dependencies. No ASP.NET Core, no EF Core, no database provider. A plugin only needs a reference to this package plus the Platform Core it extends.

Table of contents

1. Pipeline contracts

IPipelineContext — the bag that travels through a run

IPipelineContext<TResponse> adds TResponse? Result { get; set; } for pipelines that return data.

Status is derived from the errors and the halt signal, not a flag — so a context can never end up "holding errors but reporting success". Errors are stored in a ConcurrentQueue, which keeps it safe when a step fans out internally.

Halt — stopping early without an error

Some outcomes are neither success nor failure: the item is not ready yet and must be retried later, or a newer item has superseded it. Halt is that third outcome:

if (!await vesselList.ContainsAsync(context.ContainerNo, ct))
{
    context.Halt("EDO.PENDING", $"Container {context.ContainerNo} is not on the discharge list yet.");
    return;
}

• The first terminal signal wins. Halt after Fail (or Fail after Halt) is dropped and listed in IgnoredSignals. Further Fail calls on an already-failed context still accumulate, as batch processing needs. So Halt cannot close a group of rules that has already collected errors — use StopIfFailed(), see Collecting errors in groups.
• The code is the domain's, and must come from a finite set (EDO.PENDING, EDO.SUPERSEDED). It becomes a metric label; a code carrying a container number would explode the series count. Per-item detail goes into Reason.
• Halted gives IsSuccess == false on purpose (fail-closed): code that only checks IsSuccess will not record a result for an item that is still waiting.
• An infrastructure fault is still an exception. Halt is for valid business outcomes, not for swallowing errors.

Background jobs should branch on Status, not on ToResult(). ToResult() is for the HTTP/gRPC boundary; there, Halted and Failed differ only by their code.

IPipelineStep<TContext> — one business step

[PlatformStep("Gate.ValidateContainer", executionOrder: 10)]
public sealed class CoreValidateContainerStep(IContainerRepository repo)
    : IPipelineStep<IGateInContext>
{
    public async Task ProcessAsync(IGateInContext context, CancellationToken ct = default)
    {
        var container = await repo.FindAsync(context.ContainerNo, ct);   // exception -> 503
        if (container is null)
        {
            context.Fail($"Container {context.ContainerNo} does not exist.");   // business -> 4xx
            return;
        }

        context.SetFeature(container);      // hand it to later steps
    }
}

Step attributes

Reusing a StepKey overrides: the step with the higher priority wins, so a [PluginStep] replaces the [PlatformStep] carrying the same key. A new StepKey inserts: pick an executionOrder between two existing ones.

Priority is the assembly's role, not a choice (RFC-0009, 11/2026). PipelineStepAttribute cannot be used directly and Priority cannot be set. Discovery checks each attribute against the site code of its assembly and fails at startup when they disagree:

Before overriding, weigh it up: if you find yourself copying most of the Core step's logic, the real problem is the granularity of the Core step. Ask the Platform team to split it instead of copying — copying is precisely the mechanism that produces drift between a port and Core.

Passing data between steps

context.SetFeature(container);                       // producer step
var container = context.GetRequiredFeature<Container>();   // consumer step
var maybe     = context.GetFeature<Container>();           // null when absent

Prefer this over State when the value is typed — GetRequiredFeature<T> fails loudly with the type name instead of returning a silent null.

2. Business rules

Use IBusinessRule<TContext> when a step needs to be split into independently switchable checks.

public sealed class ContainerWeightRule(IOptions<GateSettings> settings) : IBusinessRule<IGateInContext>
{
    public string RuleKey => "Rule.Gate.ContainerWeight";

    public Task ExecuteAsync(IGateInContext context, CancellationToken ct = default)
    {
        if (context.WeightKg > settings.Value.MaxContainerWeightKg)
        {
            context.Fail($"Container {context.ContainerNo} exceeds the weight limit.");
        }

        return Task.CompletedTask;
    }
}

A rule reports a violation exactly like a step does — through context.Fail(...). It returns no verdict and throws nothing; an exception here means infrastructure, same as invariant 5 in section 6.

Rule order — [RuleOrder(n)]

When rules can fail, the first failing rule decides the message — and with Halt, whether the item waits or is rejected. Without an explicit order, rules run in DI registration order, i.e. whatever Assembly.GetTypes() returns: renaming a file or splitting a class silently changes behaviour.

[RuleOrder(210)] public sealed class CategoryEmptyRule      : IBusinessRule<IEdoContext> { … }   // -> Halt "pending"
[RuleOrder(220)] public sealed class CategoryNotAcceptedRule : IBusinessRule<IEdoContext> { … }   // -> Fail

Step by 10 so sites have room to slot in. The order is read from the attribute at discovery time, not from the instance, so AOP proxies do not hide it.

Rule key — [RuleOrder(n, Key = …)]

A rule has DI dependencies, so nothing can create it at startup to read its RuleKey. Declare the key on the attribute instead — discovery reads it from the type, and IBusinessRule.RuleKey returns it by default, so the key is written once. This lets a host check a "disabled rules" setting at startup (R9 typed instead of R09 must fail, not pass silently):

[RuleOrder(210, Key = EdoRuleKeys.R21)]
public sealed class CategoryEmptyRule : IBusinessRule<IEdoContext>
{
    // no RuleKey here: the default reads Key above
    …
}

A default interface member is not inherited by the class: inside the rule's body, RuleKey does not compile unless the class implements it. When rules need their key in their body (context.Reject(RuleKey, …)), implement it once, on their base class, from the attribute:

public abstract class EdoRule : IBusinessRule<IEdoContext>
{
    public string RuleKey => RuleKeys.Of(GetType());   // [RuleOrder(Key)] of the concrete rule
    …
}

RuleKeys.Of(type) / RuleKeys.Find(type) read the attribute of the type itself (Inherited = false: a subclass that declares nothing does not borrow its parent's key), skipping only AOP proxy classes generated at runtime. Closed generic rules read their generic definition. Of throws PipelineDiscoveryException when there is no key; Find returns null.

The host reads the valid keys for a site from IBusinessRuleRegistry (package TCIS.Pluggable.Engine):

IReadOnlySet<string> valid = registry.GetRuleKeys(typeof(IBusinessRule<IEdoContext>), "CTL");
// the keys GetRules("CTL") runs: DEFAULT rules minus those CTL replaces, plus CTL's own; generic included; case-insensitive

Replacing a platform rule — [RuleOrder(n, Key = …, Replaces = …)]

A site rule that replaces a platform rule says so on itself. At that site the platform rule leaves the run set — no setting to switch it off, no key naming convention:

[RuleOrder(1221, Key = CoreorRuleKeys.R16, Replaces = CoreorRuleKeys.R16)]   // reusing the core key is allowed
public sealed class HictEportNoEirChangeRule(...) : EportBranchRule(...) { … }

IBusinessRuleRegistry.GetReplacements(contract, site) returns each replaced key with the replacing rule's metadata — log it at startup so operators see which site runs differently.

Mandatory rules — [RuleOrder(n, Key = …, Mandatory = true)]

Some rules are prerequisites of the rules after them — typically a rule that enriches the context instead of only checking it. Switching it off makes later rules compare against missing data and reject items wholesale, with no error. Mark it mandatory and the policy can no longer switch it off:

[RuleOrder(110, Key = EdoRuleKeys.R63, Mandatory = true)]   // copies the existing secure code into the context
public sealed class ReuseSecureCodeRule : IBusinessRule<IEdoContext> { … }

Reject such a setting at startup rather than relying on the warning:

var mandatory = registry.GetMandatoryRuleKeys(typeof(IBusinessRule<IEdoContext>), "CTL");
// fail ValidateOnStart if site.DisabledRules overlaps `mandatory`

The threshold above comes from the application's own configuration. The framework has no per-site settings mechanism yet — ISiteModule.RegisterServices receives the global IConfiguration only, so a value that differs per port has to be resolved by the site's own module for now (md/27 §2.2).

A site can switch a Platform rule off without touching Platform code:

public sealed class CatLaiRulePolicy : IBusinessRulePolicy   // the "Policy" suffix auto-registers it
{
    private static readonly HashSet<string> Disabled = ["Rule.Gate.ContainerWeight"];

    public bool IsRuleEnabled(string ruleKey) => !Disabled.Contains(ruleKey);
}

That is the whole job. Nothing else to wire up:

• AddPluggablePipeline already registers DefaultBusinessRulePolicy under the DEFAULT key, so a site that supplies no policy of its own still runs every rule.
• A site may have more than one policy (for example one built from configuration and one in its plugin). They are combined: a rule is off when any of them switches it off. Lookup goes by tier — the site's policies, else the DEFAULT policies, else a plain registration — and the first tier that has any wins; a site with its own policy does not also get the DEFAULT ones. Mandatory rules still run. Before RFC-0008 (11/2026) only the last-registered policy of a tier was used and the others were dropped silently. Pinned by S4_PolicyCompositionTests.
• IBusinessRuleProvider applies the policy itself, so the coordinating step just hands over:

[PlatformStep("Gate.CheckRules", executionOrder: 200)]
public sealed class CoreCheckRulesStep(IBusinessRuleProvider<IGateInContext> rules) : IPipelineStep<IGateInContext>
{
    public Task ProcessAsync(IGateInContext context, CancellationToken ct = default)
        => rules.RunAsync(context, ct);
}

RunAsync orders the rules by [RuleOrder], applies the site's policy, checks cancellation before each rule, and stops on context.ShouldStop — always on Halt, and on a failure unless ContinueOnError. A rule that halts becomes HaltInfo.Source. It does nothing if the context has already stopped. A rule whose terminal signal was dropped (see IgnoredSignals) is logged as a warning with its RuleKey — also when RunAsync is called directly, outside the engine.

Collecting errors in groups

Some rulebooks mix behaviours: stop at once on one check, collect every error of a group, then stop before the next group if that group failed. Turn on ContinueOnError and close each group with a gate rule that calls StopIfFailed():

// context.ContinueOnError = true before RunAsync
[RuleOrder(45)]
public sealed class Group1GateRule : IBusinessRule<ExportBookingContext>
{
    public string RuleKey => "GATE1";

    public Task ExecuteAsync(ExportBookingContext context, CancellationToken ct = default)
    {
        context.StopIfFailed();   // errors from rules 20..40 ⇒ stop here, still Failed, errors kept
        return Task.CompletedTask;
    }
}

StopIfFailed() turns ContinueOnError off only when the context already has an error, so ShouldStop becomes true and both RunAsync and the engine stop after the current rule or step. With no error yet it does nothing. A rule that must stop the run on its own error calls Fail(...) then StopIfFailed().

Do not close a group with Halt. On a context that already failed, Halt is dropped — the run carries on into the next group and only a warning is left behind. Pinned by U1_RuleRunnerTests.RunAsync_HaltAfterFail_IsIgnored_AndLoggedAsAWarning.

Prefer RunAsync over a hand-written loop. A loop has to remember the stop condition itself; one that only checks !IsSuccess && !ContinueOnError keeps running after a Halt whenever ContinueOnError is on — no error, no log. GetRules(siteCode) is still there when you genuinely need the list (diagnostics, a custom fan-out).

3. Site modules

ISiteModule — the entry point of a module

public sealed class CatLaiModule : ISiteModule
{
    public string SiteCode => "CATLAI";        // MUST NOT be "DEFAULT" for a plugin

    public void RegisterServices(IServiceCollection services, IConfiguration configuration)
    {
        services.AddScoped<ICustomsGateway, CatLaiCustomsGateway>();
    }
}

Platform modules declare SiteCode = "DEFAULT" and load for every site. Plugin modules declare their own site code and load only for that site.

[MultiTenantService] — per-site service implementations

Mark only the contracts a site may replace — the Platform default and each site's version alike:

[MultiTenantService(typeof(IFeeCalculator))]
public sealed class FeeCalculator : IFeeCalculator { … }          // Platform

[MultiTenantService(typeof(IFeeCalculator))]
public sealed class CatLaiFeeCalculator : IFeeCalculator { … }    // plugin CATLAI

In ServiceRegistrationMode.Explicit (recommended, set on AddPluggablePipeline) the attribute is the only way in and typeof(...) is mandatory. In the default Convention mode, classes whose names end with Service, Provider, Mapper, Factory, Manager, Repository or Policy are registered automatically as well. See the Engine README, Multi-tenant service registration.

IBusinessRulePolicy implementations need no attribute and no particular name — they are recognised by type in every mode.

IPluggableDiscoveryHook — joining discovery from your own library

Implement it when a library of yours needs to inspect or contribute during the discovery sweep, rather than requiring every host to wire it manually.

4. Returning a pipeline result to the caller

A pipeline ends with a context, but every TCIS business flow is expected to hand the transport layer a TResult so a controller can just call ProcessResult. ToResult bridges the two:

The failure code and message are declared on the context, not at the call site:

public sealed class GateInContext : TPipelineContextBase<GateInResult>
{
    public override string FailureCode => "GATE_IN_REJECTED";   // no taxonomy prefix -> HTTP 409
    public override string FailureMessage => $"Container {ContainerNo} cannot enter.";

    public string ContainerNo { get; set; } = string.Empty;
}

await pipelineEngine.ExecuteAsync(context, ct);

return ProcessResult(context.ToResult());

A halted pipeline maps to Fail(halt.Code, halt.Reason) with no error data. The HTTP status follows the code's taxonomy prefix, exactly as for any failure — so the domain picks the status by picking the prefix. | ToValidationErrors() | Just the grouped errors, when you build the TResult yourself |

Both FailureCode and FailureMessage are abstract on TPipelineContextBase, so the compiler points at any context that has not decided yet. A virtual default would let a context silently ship a generic code the client cannot act on.

Why they live on the context. FailureCode is a constant of the use case — a given pipeline always rejects under the same code — so it belongs to the context type, not to a single call. Put it there and every entry point running that pipeline (REST, gRPC, a background job) reports the same code, instead of each caller repeating a literal that nothing keeps in sync. FailureMessage can interpolate the context's own fields, because the context already carries the request data.

Why this exists. The Pluggable architecture has two ways into business logic — CQRS handlers and the pipeline engine — but the response standard was written for handlers only. Without a shared bridge every controller hand-rolls its own JSON from context.Errors, so a client ends up parsing two different error shapes on the same API, and pipeline endpoints lose the TraceId that ties a report back to its logs.

Why the conversion is lossless. A PipelineError carries Key + Message, which is exactly a TValidationError once grouped by key. Errors sharing a key collapse into one entry, keys keep first-appearance order, and an error with no key lands in "GLOBAL" — the same convention context.Fail(message) already uses:

"data": [
  { "key": "TCIU1000001", "errors": ["Overweight.", "Seal number missing."] },
  { "key": "TCIU2000002", "errors": ["Booking not found."] }
]

That shape matters most for batch endpoints running with ContinueOnError — one row failing must not collapse the whole report into a single message.

Only business failures reach ToResult. An infrastructure fault was thrown by the step and never got here — that boundary is preserved by the engine, see section 6.

5. Connection-level tenant isolation

This is the layer that makes a single process safely serve several tenants.

ITenantConnectionInitializer

void Initialize(DbConnection connection, string? tenantId);
Task InitializeAsync(DbConnection connection, string? tenantId, CancellationToken ct = default);
void Cleanup(DbConnection connection);
Task CleanupAsync(DbConnection connection);

Initialize runs immediately after the connection opens; Cleanup runs before it returns to the pool.

TenantConnectionInitializerBase — write only the SQL

A template-method base: derived classes describe the command, the orchestration is written once.

public sealed class MyRlsInitializer : TenantConnectionInitializerBase
{
    protected override void ConfigureInitializeCommand(DbCommand command, string? tenantId) { … }
    protected override void ConfigureCleanupCommand(DbCommand command) { … }
}

Every initializer used to hand-write all four methods, with the sync and async bodies about 84% identical. That duplication produced two serious defects — a fix applied to the async branch but not the sync one, and Tier 1 failing closed while Tier 2 failed open because the branches were written separately.

Throwing from ConfigureInitializeCommand means the framework executes no command at all — fail-closed by construction.

TenantAwareDbConnection — the decorator trio

public sealed class TenantAwareDbConnection(
    DbConnection innerConnection, string? tenantId, ITenantConnectionInitializer initializer) : DbConnection

Transparent to both EF Core and Dapper.

Why "discard". ADO.NET's Close() returns a connection to the pool; it does not throw it away. A session whose isolation setup or reset failed may still carry the previous tenant's schema or context, and the next borrower would run on it. The wrapper calls the driver's static ClearPool(connection) (SqlClient, Npgsql and ODP.NET all have one): the session is destroyed instead of pooled, and that pool's idle sessions are closed — a cost paid only on failure. A driver without ClearPool cannot be protected this way. ODP.NET is the one that matters: it does not reset sessions taken from the pool. Pinned on Oracle by Tier2_A_Failed_Cleanup_Discards_The_Session_Instead_Of_Pooling_It (changed 27/10/2026 — cleanup errors were swallowed and the session pooled).

Four safety details worth knowing:

1. Initialize fails → Close() at once. A connection that never got its isolation applied must not reach the pool; it would carry poisoned state into another tenant's request.

2. _isInitialized is reset in a finally — including when State == Broken (dropped network, database restart) causes the cleanup branch to be skipped. Leaving the flag set would make the next Open() skip Initialize, giving a session with no tenant isolation at all.

3. A connection decorator must decorate all four types, because the invariant only holds if every path that opens a transaction, creates a command or closes the connection goes through the wrapper:

   Type	Why it is needed
   TenantAwareDbConnection	The entry point — applies and clears tenant isolation
   TenantAwareDbTransaction	EF Core validates connection.DbConnection != transaction.Connection inside the RelationalTransaction constructor
   TenantAwareDbCommand	Providers downcast (SqlCommand.DbTransaction → SqlTransaction), so the wrapper must be unwrapped before reaching the inner command
   TenantAwareDbDataReader	CommandBehavior.CloseConnection makes the reader close the connection. Letting it close the inner connection skips Cleanup and leaves the initialised flag set — the next Open() then runs with no tenant isolation

4. DisposeAsync needs a double-release guard. DbTransaction.DisposeAsync() and DbCommand.DisposeAsync() fall back to calling Dispose(), so an async branch that releases the inner object and lets base run releases it twice. It does not crash on SQL Server or SQLite because their Dispose is idempotent — exactly the kind of defect a green test suite does not catch.

Why the command and the transaction are wrapped too

EF Core validates identity inside the RelationalTransaction constructor — connection.DbConnection != transaction.Connection throws "The specified transaction is not associated with the current connection." Returning the inner connection's transaction directly fails that check, because EF holds the decorator while the transaction reports the inner connection.

That broke every transaction in the Pluggable stack — not only explicit BeginTransactionAsync, but also the transaction EF opens by itself when SaveChanges has to send more than one batch. Saving many rows at once was enough to hit it.

Wrapping the transaction then forces wrapping the command: providers downcast (SqlCommand.DbTransaction casts to SqlTransaction), so the wrapper has to be unwrapped before it is handed to the inner command. TenantAwareDbCommand exists for exactly that one job and delegates everything else untouched.

Verified against real SQL Server and PostgreSQL containers.

TenantConnectionIdentifier — which identifier each tier needs

public static string? Resolve(IsolationTier tier, string? tenantId, string? tenantIdentifier);

The rule lives in one place because there are six connection-building sites (3 providers × EF Core and Dapper). All six once passed Id straight through, which made Tier 2 impossible to run.

NoOpConnectionInitializer does nothing and serves Tier 3, where a dedicated connection string already provides isolation.

6. ⚠️ Invariants you must not break

Full reasoning: md/29 Part 6.

7. Pitfalls