Table of Contents

Interface IErasureRetentionDeclarationLedger

Namespace
Excalibur.Compliance
Assembly
Excalibur.Compliance.Abstractions.dll

The durable record of which retention declarations some process in this deployment has witnessed — so an instance whose own view is demonstrably behind the deployment's refuses to destroy a key rather than destroying one the deployment is obliged to keep.

public interface IErasureRetentionDeclarationLedger

Remarks

The guarantee, and it is deliberately narrower than the one a reader will expect. No erasure proceeds on a view that is KNOWN-STALE. Not "on a current view" — that stronger sentence quantifies over a deployment-wide instant at which a declaration is "in force", and no such instant exists for a declaration written in code and deployed as code. This ledger never asks for one. It asks a question that durable state can answer on its own: has any process ever witnessed more than I witness. No clock, no ordering, no coordination.

The failure it removes, in the consumer's terms. Retention declarations live in CODE; the data they govern lives in a store. So a rolling deploy that ADDS a retention has a window in which two instances disagree about the law. An instance predating the declaration enumerates the subject's already-widened key handle from the mint ledger, holds no local declaration that would spare it, and irreversibly destroys the key — for an aggregate type that deploy declares retained, under a completion certificate attesting a lawful erasure. Nothing downstream ever learns: the ciphertext is simply unrecoverable, and an unrecoverable field is exactly what this framework reports as a discharged erasure.

Why this subsystem needs a durable record at all, stated as the asymmetry rather than as a preference. Everything else here that governs destruction is already durable — the erasure store, the legal holds, the key mint ledger, the token-function fingerprint. The retention declaration was the only input to an irreversible act that existed solely as a local snapshot. That asymmetry is the defect; this contract removes it.

IT IS NOT WRITE-ONCE, and copying the fingerprint ledger's shape here would be the error. A token-function fingerprint must never change: a change orphans every record, so write-once is its invariant. A retention declaration set is different in kind — it legitimately GROWS, because adding retentions over time is the supported workflow. The primitive is therefore insert-if-absent, enforced by a unique key alone, with no trigger and no immutability claim.

THE TENANT GOES IN THE PRIMARY KEY AND NOWHERE ELSE. The pair is the identity of a row, so the key addresses it completely — and a tenant predicate added to a statement the key already addresses can only ever turn the correct row into zero rows. That is not a hypothetical: a framework-wide sweep that added tenant terms uniformly is what stopped the outbox marking messages it had claimed. The acceptance criterion for tenancy here is "a new provider that omits the tenant from the key fails", never "every statement carries a predicate".

Cost, stated rather than assumed. Both operations are cold. The advance runs once per process at startup, over a set the registry's own reasoning describes as small, known at startup and fully enumerable. The read runs once per erasure, which is a rare, already-durable, already-multi-round-trip operation. Nothing here executes on a per-message, per-event or per-dispatch path, so no benchmark is owed — and if a later change puts either call on such a path, that change owes one.

A volatile store does not implement this. An in-memory deployment is one process, so no other process can hold a view it is behind, and there is nothing for a comparison to be against. Supplying a satisfiable record there would report a passing staleness check that could never fail, which is worse than having none — so the contract is simply absent, and a comparison with nothing to read is correct rather than blind.

Methods

ListDeclaredRetentionsAsync(string, CancellationToken)

Lists every declaration this deployment has recorded for tenantId, live and withdrawn alike, each carrying which it is.

Task<IReadOnlyCollection<RecordedRetentionDeclaration>> ListDeclaredRetentionsAsync(string tenantId, CancellationToken cancellationToken)

Parameters

tenantId string

The tenant partition the erasure request itself recorded.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<IReadOnlyCollection<RecordedRetentionDeclaration>>

Every declaration recorded for that tenant, with its withdrawn state. Empty means this deployment has recorded none for it, which is a real and common answer — it never means the question could not be answered.

Remarks

CALLED ON THE ERASURE PATH, AND IT IS READ-ONLY. The caller compares this against its own registry and refuses THIS erasure when the record holds a declaration it does not hold. That takes the write off the irreversible path entirely: advances happen at startup, never concurrently with a destruction.

FILTERED TO THE REQUESTING TENANT, deliberately, and the unfiltered version over-refuses. It is tempting to refuse on any declaration this instance is missing, whoever declared it, on the reasoning that mis-widening is cross-tenant by construction. The MECHANISM is cross-tenant; the HARM is not. Only the requesting tenant's declarations ever decide whether a handle is spared, so a declaration belonging to another tenant cannot change this erasure's outcome — and refusing over it would withhold an erasure that would have been performed correctly. An over-refused erasure is a subject not erased, which has its own regulator: fail-closed is not a free move on a path whose job is destruction, because both directions do harm.

A WITHDRAWN DECLARATION IS RETURNED, FLAGGED, AND IS NOT THE SAME AS AN ABSENT ONE. The row survives as a tombstone so the two facts stay distinguishable to an auditor, and so the advance path cannot re-create it — and the caller needs to SEE it. An instance whose own code still declares a withdrawn retention is the stale instance mirrored, and it will spare rows whose key another actor is entitled to destroy; a read that hid the tombstone would make that case undetectable. (This paragraph previously said a withdrawn declaration is NOT returned, and that the read collapses the distinction "in the direction the caller needs". That was wrong: it made the mirror case inexpressible, which an adversarial review caught before any provider implemented it.)

FAIL CLOSED: THROW. NEVER RETURN EMPTY BECAUSE THE READ FAILED. This is the obligation most likely to be dropped, and dropping it inverts the whole contract. An enumeration that could not be completed is indistinguishable from a deployment that has declared nothing — and "nothing declared" is precisely the answer that lets the destruction proceed. A swallowed failure certifies over a key it should have spared.

BUT A THROW IS NOT BY ITSELF A DELAY, AND THE CALLER MUST NOT ASSUME IT IS. Whether the erasure is retried afterwards is a property of the EXECUTING SCHEDULER, not of this contract: a scheduler that counts a throw against a bounded retry budget turns a sequence of honest refusals into a permanently failed erasure, which is a subject never erased. So a caller on a destruction path must give a refusal its own non-terminal disposition rather than letting it surface as a generic failure. (An earlier revision of this paragraph asserted that "a throw leaves the erasure non-terminal and retryable". That is false of the shipped scheduler and is corrected here rather than quietly deleted, because it is the reassuring reading and it was committed.)

Exceptions

ArgumentException

tenantId is null, empty or whitespace.

ErasureStoreNotProvisionedException

The backing table is absent and this store is not configured to provision it. An erasure that cannot read the deployment's declarations must not proceed — the alternative is to assume it is current, which is the assumption this ledger exists to stop anyone making.

RecordDeclaredRetentionsAsync(IReadOnlyCollection<DeclaredRetentionKey>, CancellationToken)

Records every declaration in declarations that this deployment has not recorded before, leaving the rest exactly as they are.

Task RecordDeclaredRetentionsAsync(IReadOnlyCollection<DeclaredRetentionKey> declarations, CancellationToken cancellationToken)

Parameters

declarations IReadOnlyCollection<DeclaredRetentionKey>

This process's own declared retentions, as its registry holds them.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task

Remarks

IT NEVER REFUSES ANYTHING. An advance is a WRITE, not a gate — that separation is what makes this safe to deploy rather than hostile to deploy. A refusal here would mean the first updated instance to boot halts every instance that predates it, which is an outage; the comparison that CAN refuse lives on the erasure path, where it withholds only the irreversible act and only from the instances that cannot perform it correctly.

CALLED BEHIND A PER-PROCESS LATCH, BEFORE THIS PROCESS EXECUTES ITS FIRST ERASURE — NOT AS A PRECONDITION OF SERVING. The weaker precondition buys the same invariant: what the comparison needs is that an updated instance has advanced before any erasure runs anywhere, and an instance that never erases has nothing to contribute. Binding this to startup instead would make the application's readiness depend on the compliance store's availability, so a store outage would stop new instances serving and could stall a rollout — a liveness cost for no safety gain. The precedent contract this one follows says the same thing of itself: callers invoke it once per process behind their own initialisation latch.

ONE ROW PER PAIR, and N independent insert-if-absent operations — never one set-valued row. A set-valued row makes advancing a read-modify-write, and therefore a lost update: two processes starting together each read the set, each write their own union, and the first one's additions are gone. Per-pair rows make the union form BY CONSTRUCTION — for each pair exactly one insert wins and every other is a no-op — so there is no read in the write path at all, no compare-and-set and no version column. Two processes starting together is the case the primitive is specified for, not an edge case to survive.

The test and the write are ONE indivisible operation, and a lost race is a SUCCESS. An implementation whose insert-if-absent is not atomic in the substrate MUST catch the duplicate-key violation and continue rather than surfacing it: surfacing it turns a specified no-op into a startup failure on a correctly configured deployment. It must catch only that violation, identified precisely — a blanket catch would turn a transient fault into a silent pass, and a silently skipped advance is a declaration this deployment never records.

THIS PATH CONTAINS NO UPDATE. Insert-if-absent, never upsert. Load-bearing, and it is the whole mechanism that stops a withdrawal being resurrected: a withdrawal tombstones the row rather than deleting it, so the tombstone OCCUPIES the key, and an instance whose code still declares a withdrawn retention conflicts and does nothing. Change this to an update and a stale deploy silently re-declares an obligation an administrator deliberately withdrew. One token, and it owes its own arm.

Partial application is SAFE here, and that is why this returns nothing. Each pair is independent, so a failure part-way leaves a prefix recorded and the remainder not — and since the operation is idempotent, the next process to start, or the next restart of this one, records the rest. There is no partially-applied state a caller could act on differently, so there is no outcome to report. It throws on failure, because a startup that cannot record its own declarations has not established the premise the erasure path will rely on.

Exceptions

ArgumentNullException

declarations is null.

ArgumentException

A declaration carries a null, empty or whitespace tenant or aggregate type. A blank term would be a row every misconfigured deployment agreed on.

ErasureStoreNotProvisionedException

The backing table is absent and this store is not configured to provision it.