symfonic.capabilities.human.contracts

contracts

The ports this capability is wired through, and nothing else.

Every one of these is satisfied by something that already ships. The envelope signer is T2.3.6's EnvelopeSigner; the conditional-write backend is the adopter's persistence backend; the checkpoint commands are the saver the conversation services already own. They are declared here as protocols rather than imported because the T1.2.1 matrix puts capability → runtime-service at no — a capability that imported a service would be a capability you cannot compose without that service.

The suites bind the real implementations to these ports, so "consume, do not redefine" is asserted against shipped code rather than against a fake that happens to agree.

CheckpointCommandPort

Bases: Protocol

The four checkpoint verbs a pause needs, separated from any saver.

The legacy engine reached into a LangGraph saver from three call sites with four differently-shaped config dicts. This is that surface, named.

ConditionalWritePort

Bases: Protocol

The adopter persistence backend's atomic conditional insert (LIB-TL-2).

INSERT ... ON CONFLICT DO NOTHING RETURNING jti in SQL, a unique-_id insert in Mongo, a single-lock section in the in-memory reference. One method on purpose: a port that also offered a read would invite the read-then-write sequence the contract forbids.

ConsumptionPort

Bases: Protocol

Single-winner redemption of one jti (SEC-PTK-3).

One method, and its contract is the whole of the acceptance criterion: concurrent callers competing for one jti see exactly one True, and the decision is reached by a single atomic operation rather than by a read followed by a write.

EnvelopeSignerPort

Bases: Protocol

T2.3.6's EnvelopeSigner: mint an authenticated envelope, verify one.

verify returns the invocation pin and raises on tampering, on an unsupported layout, and on an unavailable keyset. This package never inspects a signature, holds key material, or decides what "authentic" means; it only decides what a token binds.

InteractionSchema

Bases: Protocol

A payload or response schema: anything that validates and returns.

IssuanceLedgerPort

Bases: ConsumptionPort, Protocol

The operated platform's authoritative record, which is also the winner.

A ledger is a consumption port: making issuance and consumption the same object is what gives operated mode one linearization point rather than two places that each believe they decide. The extra verbs — issuance, drain proof, retirement horizon — are the operated-only purposes (LIB-TL-4), and a library deployment reaches them by not having this object at all.

IssuanceRecordBackendPort

Bases: ConditionalWritePort, Protocol

Where an operated platform keeps its issuance table (SEC-PTK-7, SCP-FRZ-2).

Wider than :class:ConditionalWritePort, and for a reason that does not apply there: redemption must never read before it writes, but the issuance record and the retirement horizon exist precisely to be read back — by the next worker, and by this one after a restart. A ledger given only the conditional write keeps them in memory, and says so rather than reporting a reach it does not have.