Guarded acceptance

Prepare a durable, immutable intent with current Ablo evidence, then reconcile its application in an external system.

This application pattern composes existing SDK operations. It is not a new transaction spanning Ablo and Git. Start with one project, one repository, and exact-base Git admission. The accepting service owns policy and authorization; Ablo validates declared row dependencies and commits the preparation atomically.

Copy the operation

The typed acceptance example implements this lifecycle on existing SDK APIs. Copy its directory into the accepting service, connect candidate verification and your protected Git broker, and use:

const acceptance = createAcceptance({ client, accountId, verify, broker });
const prepared = await acceptance.prepare({ candidate, workerId });
if (!prepared.ok) return prepared; // error.code and error.recovery
return acceptance.reconcile({ proposalId: prepared.value.proposalId });

pending({ repositoryId, limit, cursor }) supplies bounded restart recovery. The module owns fresh evidence, generation/revision checks, proposal identity, atomic preparation and acknowledgement, receipt binding, and structured recovery results. Its README defines the two application integrations and model setup. No new Ablo server primitive is required. See that README for the source’s distribution status; an installed older package will not contain the example.

Trust and evidence

Workers submit a proposal identity, immutable candidate reference, expected base, declared premise IDs and application revisions, ownership generation, and verification reference. Authenticate the submitting worker independently of that payload. The service must validate that the declared dependencies are complete for its policy; Ablo cannot discover an omitted dependency.

Create the authorized writing client before reading. Through that same instance, read the task, assignment, policy, and every declared premise. Compare the returned application revisions or content hashes with those bound to the candidate. Reject a mismatch: merely rereading does not make work based on an older premise valid. Then pass those exact returned rows in reads to commits.create. A change between this validation and preparation rejects the whole commit with stale_context.

Never pass a worker’s captured rows, a different server client’s captured rows, serialized rows, or fabricated read watermarks as the service’s evidence. read_evidence_client_mismatch rejects foreign captured rows locally, even when the two clients have identical credentials. See Switching clients.

Keep two identities distinct. The credential determines the actual committing actor in Ablo’s audit trail. Store the authenticated proposing worker and run on the immutable proposal as application provenance. Do not grant the worker acceptance access just to make it appear as the committing actor. If the service uses a separately issued attributed credential, that client must have the required model/group permissions and must perform its own reads. Worker credentials must not write assignments, prepared intents, or acceptance acknowledgements. A secret key is not a bypass for model/group access policy.

Durable records

These are application-owned records and fields, not SDK resources:

The copyable example combines task, assignment and slot in acceptanceTasks, and proposal plus application intent in acceptanceProposals. Its immutable payload stays unchanged when status/outcome changes; acceptancePremises owns the declared dependency revisions. Separate models are needed only when the application’s existing ownership boundaries require them.

Retain proposal IDs (or immutable tombstones) for the required deduplication lifetime. Use strict create with caller-selected IDs, not an upsert. Ablo’s transport idempotency is scoped to the participant and has a retention window; it cannot by itself enforce permanent business identity across service replacement. See Idempotency.

Prepare, apply, acknowledge

1. Read an existing proposal by its tenant-scoped identity. If it exists, compare the complete canonical payload or its verified digest. An identical proposal resumes its existing intent; different content under that ID is an application conflict. Check caller access before returning either result.
2. If it is new, read and validate all current premises through the accepting client. Missing required rows reject. An absent read does not guard absence; strict creation and a guarded existing acceptance slot arbitrate races.
3. In one commits.create({ operations, reads, idempotencyKey, wait: 'confirmed' }), create the immutable proposal, create its prepared intent, and reserve the slot. The reads include assignment, task, policy, slot, and premises. Do not use partial/notify conflict handling. Preparation must be confirmed before the service permits external application.
4. The protected Git broker loads that prepared identity and checks the exact base, immutable candidate, verification and policy binding. It atomically applies the accepted ref update and writes its durable receipt using the proposal ID. Workers cannot invoke an unguarded application path.
5. After verifying the Git receipt against proposal ID, digest, repository, base and accepted SHA, the service reads the intent and slot afresh. In a second guarded atomic commit, acknowledge the receipt, publish the accepted SHA in application state, and release the matching slot. Keep the proposal immutable. Duplicate acknowledgements with the same receipt return the stored result; a different receipt is a conflict.

Use distinct stable preparation and acknowledgement request keys. Persist the canonical proposal and request identity before submission. Retry an uncertain write with its original key and identical intent. Do not silently rebuild a different request under that key. On entity_already_exists, read the durable proposal and compare its payload; a racing create is not automatically success. When a definitive stale rejection requires replanning, create a new proposal identity. A fresh attempt to prepare the same unchanged candidate still needs full validation; reconcile any uncertain prior attempt first.

The first commit is the admission point. It records that the premises were valid at preparation, not that they stay frozen until Git application. If policy requires validity at the exact Git update, Lobby must serialize or fence the relevant changes through the broker. An Ablo reread immediately before Git still leaves a cross-system race.

Ownership and revocation

Assignment, execution claims, and prepared authorization have separate lives:

The accepting service checks durable assignment authority, not the liveness of the worker’s execution lease. If lease loss must revoke submission rights, the application must connect takeover to a guarded assignment-generation change and fence the old worker at its execution boundary. Revoking only a worker session does not revoke a separate service credential. Record access revocation in the guarded assignment/policy as well as revoking credentials.

Bounded recovery

Persist application intents as ordinary model rows. Use the existing paginated model list with a project/repository filter, status: 'prepared', and a fixed limit (for example, 100). Process a bounded number of pages per run, preserve nextCursor with the same filter/order, and periodically restart the scan so concurrent changes or inserts are not stranded. Lists are observational, not snapshot transactions: reread each intent before changing it. Avoid listAll for an unbounded recovery worker.

For each intent, look up the Git receipt by proposal identity first:

Keep failed or canceled intents as durable terminal records too; do not delete their proposal identities to make retries appear new. The two-state successful path above does not prescribe Lobby’s terminal failure names.

commits.list and commits.get expose Ablo commit outcomes; they do not replace the application outbox. Commit records redact mutation data, and a confirmed preparation says nothing about Git application. Git receipts prove application; Ablo acknowledgement records that the service reconciled it.

Rejections callers can act on

Branch on structured code, not message text. Preserve request/proposal correlation and permitted conflict details; never leak inaccessible premises.

Distinguishing premise_changed, ownership_changed, access_revoked, proposal_conflict, and outcome_unknown is the accepting application’s result contract, not a new set of Ablo error codes. A stale_context error can name an assignment or a content premise; the service knows which role that row plays.

Conformance boundary

Test actual event order and persisted rows, not only returned success values:

• Two real SDK clients must reject foreign evidence before transport and allow a freshly validated writer-owned read. See the SDK httpClient.test.ts suite.
• Database-backed executeCommit.guardedAcceptance.test.ts checks atomic preparation, stale premises/assignment, duplicate and conflicting preparation, and durable state across acknowledgement interruption. Its external receipt is a test fixture, not a Git implementation.
• guarded-acceptance.journey.test.ts runs the copyable module through the real local SDK/server, subject-scoped credentials, PostgreSQL, and actual Git ref transactions. It injects response/application interruptions and uses a test verification callback; it does not certify sandbox verification or process death.
• Existing database suites cover read-set serialization, idempotency, strict creation, claim enforcement and tenant isolation. Session revocation and hosted claim takeover require their real authorization/lease tests.
• Lobby must additionally run its protected service with restricted worker credentials, real Git receipts, process termination at both boundaries, assignment takeover, session revocation and cross-tenant requests. The SDK and database tests do not certify that production integration.

Use hosted coordination conformance for real participant identity, heartbeat, release and expiry. Report separately which local, hosted and customer integration checks actually ran.