Delivery requires atomic protected compensation and exact historical resource rules before ADR-0053 approval
Assignment ADR-0053/delivery/001, coordinator 01a0e095-f279-7fd0-a8ef-92ce8f9547fc, host local, participant 01a0ff07-cd25-7490-9008-a734cad7147e. Reviewed Proposed ADR-0053 and approval request at 3225646710eb3073a4e8e5e5f8a6fb9f07eeb1cf, Platform/Sales positions at 74904433fe7c873288697a87aebd8ff0024232de, and Revenue position at e43e3e8ddd2032f902dcb4a79070d974a174db86. Delivery supports the bounded direction, the dedicated fresh compensation evidence read and the atomic protection-transfer approach. Delivery withholds formal acknowledgment until the exact assembled schemas, financial effects, history rules and writer amendments are reviewed. This memo intentionally has no acknowledges field and approves no runtime implementation or activation.
ADR-0052 implementation is paused at local Delivery b53b08832582dea43fba0832be5eea2a480133d3; its worktree and isolated fixtures are preserved. Its 45-case local proof is evidence for its original protocol only, not the proposed compensation operation. This is the only active assignment in this chat.
Source facts that constrain the design
Delivery's modules/scheduling-command/repo.ts:135-174 binds an exact SoftHeld Lesson to one held lock, changes the Lesson to Scheduled, and atomically retains original command/response bytes, ReceiptRef, lifecycle outbox and continuation booking. The ReceiptRef includes original lock version, bind key digest, request fingerprint and original event identity. The continuation stores original Person, Organization, Lesson, lock, reservation and booking associations. Its generation starts at zero.
repo.ts:207-227 allows ordinary retirement only after fresh Revenue bound evidence with settled/abandoned continuation and exact original receipt, followed by local generation CAS. The migration's scheduling_continuation_guard permits only protected-to-retired, increment-by-one, exact-intent updates with all other identity unchanged. Its scheduling_booking_guard rejects every matching invalidating Lesson/lock/indirect-resource change while protected. There is currently no compensation exception. A new handler cannot merely call ordinary retirement and then cancel, nor set a transaction variable and assume the existing guard authorizes it.
Legacy modules/lesson-hold/repo.ts:1169-1385 uses the expiring v1 idempotency cache, can initiate a refund on confirmed locks, and updates Lesson to the exact stored value Canceled and lock to released. The refund branch executes within its local transaction. This is unsuitable as the new recovery implementation: its identity, financial authority, cache lifetime, protection semantics and HTTP-lock boundary differ. Do not forward the new service token to that cancellation route or invoke this helper after clearing protection.
modules/scheduling-command/resources.ts, repo.ts:124-130 and ownedLesson currently compose current local site/type/Participant reach and an active public geography read before historical bind/settlement handling. Production Person/tenancy still fails closed. These are implementation facts to amend under explicit history rules, not proof that all current predicates should gate immutable history forever. operational-fact.ts and the source/application journals preserve genuine incoming observations before protected progression; compensation must not discard those observations or make them disappear through a state change.
Minimal resource verdict and immutable history
Support Platform's proposed GET /api/identity/v1/person/{person_id}/scheduling-resource-verdict?organization_id={organization_id} and sole platform.identity.scheduling-resource.read scope. Delivery correlates the exact authenticated tenant/Organization, requested Person and returned canonical Person/status/tenancy. Use Platform's closed minimal fields and coherent snapshot, fresh read per business attempt, no-store, bounded HTTP, fixed approved origin and no redirects, cookies, direct Platform table reads or invented Organization-enabled/funded-Market verdict. A second tenant requires a separate isolation decision. Public geography remains the independently implemented existing read.
New soft/create and new bind require the original exact Person to be active, non-merged and actively tenanted in the authorized Organization, with new_write_eligible=true; canonical/requested IDs must agree. No alias substitution, local role inference, target-tenancy inheritance or positive-verdict cache. Observation time is not a lease or cross-domain commit fence. If the accepted semantics require active identity at the exact Delivery commit instant, Platform must specify a real fence and invalidating-writer participation; holding Delivery's transaction across HTTP cannot achieve it.
Separate three cases in the contract. New booking/financial admission requires active eligibility. Authenticated disclosure/replay of a retained immutable original command/receipt requires current service/tenant/Organization reach and exact original association; it does not re-run coach eligibility or require current site/type/geography activation as if making a new booking. Exact failed-close unwind is recovery of that admitted obligation, not admission of a replacement booking or collection: recommend allowing archived Person or paused/inactive exact tenancy when Platform still verifies the original pair/lineage and the retained owner records correlate. This last classification needs explicit owner approval, not inference from a negative active flag.
Merged Person may be reported through verified original lineage, but original Person, actor, hash and response bytes remain unchanged. Attach lineage separately. Missing original tenancy, missing/unverifiable lineage, or an unavailable verdict remains pending without new effect or disclosure until an approved retained-association mechanism/reconciliation establishes it. Do not use a merged target's current tenancy to manufacture the original pair. Platform's proposed verdict has no independent historical-admission field; Delivery supplies its immutable admitted provenance, not an assertion that Platform stored it. Amend Identity 9.5 to explicitly exempt immutable protocol bytes from historical re-keying, or declare the compatibility break and migration.
Exact compensation routes, identity and proposed schemas
Support proposed POST /api/v1/delivery/v1/lesson-holds/bind-compensations, called only by Revenue system:revenue, audience Delivery, sole delivery.scheduling.reservation.bind.compensate. Require current exact singleton tenant/Organization reach before lookup or cached disclosure. No query members; bounded strict duplicate-safe JSON; wrong method 405, malformed body/header 400, invalid authentication 401, insufficient scope/reach 403, uniform nondisclosing absent association 404, exact identity/generation/state conflict 409, authority uncertainty 503 with retained protection. Codes/envelopes remain subject to schema approval. A conflict is not financial noncommit or a successful cancellation.
Recommend a new closed compensation command v1.0, permanently journaled under (tenant, Organization, subject, operation, compensation idempotency key), operation reservation.bind.compensate, distinct from existing bind/settlement and legacy cancel namespaces. Required non-secret fields: protocol_version, UUID compensation_intent_id, UUID bind_intent_id, Organization, original Person, reservation, Lesson, lock, original bind_key_digest, request_fingerprint, full original ReceiptRef, expected_protection_revision, expected_lock_version, expected_lesson_outcome_version and immutable financial_authority_id/financial_authority_revision. Bound keys to the existing 128 ASCII-character convention, hashes to lowercase SHA-256, revisions to nonnegative safe integers and identifiers to approved canonical schemas. Correlate redundant fields with the receipt and retained command. Derive the allowed target transition in the protocol; accept no caller-selected status, reason, replacement resources, refund parameters or financial credentials.
Recommend the fourth new policy: Delivery system:delivery to Revenue, sole revenue.reservations.bind-compensation-evidence.read, exact GET /api/v1/reservations/{reservation_id}/scheduling-bind-compensation-evidence, with exactly one each of organization_id, lesson_id, bind_intent_id, compensation_intent_id. Acquire a fresh independently audited workload exchange for every attempt, validate issuer/signature/closed claims and exact scope/reach, require no-store and a strict bounded response, and complete HTTP before local locks. Do not widen existing bind-evidence or treat caller authentication as proof of quiescence. This supports three business capabilities with four new policies; existing ADR-0052 policies are unchanged.
Evidence v1.0 should echo tenant/Organization, original close identity/digest, Order/account/Person/Market, reservation/Lesson/lock, original booking window, bind key/fingerprint/ReceiptRef, compensation intent/key digest/command fingerprint, expected protection generation and lock version, irreversible authority identity/revision, original reservation/intent revisions, evaluation time and a closed authority decision. An authorized variant requires financial_quiescence_authorized, exact permitted unfunded unwind and original continuation still protected. A pending/denied variant must never contain executable authority. Specify retained terminal attempt/fact references or their integrity digest, no-new-collection enforcement and a later owner-writeback-completed variant carrying the exact Delivery compensation receipt. No money amount/funding/continuation claim may be fabricated from local lock state. Authority time is not an expiry lease. Revenue must freeze the exact predicate and schema; Delivery cannot sign its financial guarantees.
Precise proposed state transition and remaining financial objection
Recommend one deliberately narrow automatic source state. It must satisfy every predicate below; broader sources require an independently reviewed extension.
| Resource | Valid source | Proposed atomic target |
|---|---|---|
| Original admission | Exact committed v2 bind and intact original response/ReceiptRef; no noncommit tombstone or different bind identity | Original bind journal and receipt remain immutable and continue to report the original committed outcome |
| Lesson | Scheduled, exact original protected Person/Participant/site/config/type/coach/area/Market/window and linked original lock; outcomeVersion=expected_lesson_outcome_version=0; no cancellation, outcome, attendance/settlement/correction effect |
Canceled, one retained cancellation time, owner-approved failed-close reason, outcomeVersion+1; retain original associations and linked lock, no deletion/re-key/soft-hold revival |
| Local lock | held, exact original reservation/account/Market/lesson pointers; lockVersion equals command/evidence/original receipt version; fundingSubState=pending_funding; no lock debit or conflicting financial fact |
released, lockVersion+1, retained release time and compensation association; do not invent funded/refunded states or a debit/refund/forfeit |
| Local continuation | Exact intent/receipt/booking, protected generation g, no prior competing compensation or closure/financial admission |
Proposed compensating generation g+1, bound to the exact command and compensation receipt, still covering all original protected resources |
The Lesson spelling is Canceled, not Cancelled. Explicitly set/retain the appropriate lock mirror status/timestamps/reason under the approved Delivery state vocabulary; do not copy the legacy helper's financial branch. Lock association and original financial fields remain retained. Revenue's subsequent exact unfunded reservation/Order void/release and owner-produced financial events are separate writeback under Revenue serialization. Delivery emits no credit.* event or financial ledger entry. The temporary local released mirror before Revenue writeback must be approved as this exact compensated operational state, with the compensating protection retained and audits identifying pending owner writeback; otherwise choose a separately specified delayed mirror transition. This timing is an unresolved joint financial/state-machine approval item, not declared accepted here.
Source SoftHeld/missing lock is not committed-bind compensation. confirmed, consumed, released, forfeited, any funded/refunding/refunded lock, performed/No-Show/completed/canceled or changed booking, stale generation/version, or missing original receipt conflicts. An already canceled/released row without this exact compensation receipt is not idempotent success. A retained exact same completed compensation returns its original receipt even after subsequent legitimate terminal changes. Inspect retained unapplied attendance/outcome/Airtable and financial facts, as well as current rows: a genuine contradictory observation cannot be bypassed merely because projection was staged. Such evidence keeps recovery pending for owner reconciliation, not discarded or automatically replayed as permission to cancel.
Atomic protection transfer, concurrency and recovery
Under Delivery's common schema advisory lock before row locks, lock/recheck command, continuation, Lesson and lock in one prescribed order. Check current service/resource authorization already acquired outside the transaction, original identities/receipt bytes/digests, local current booking/content/version and absence of competing closure/admission, conflicting compensation and contradictory retained source. Require exact g and authority correlation. Record immutable command/evidence digest, consume only that generation into compensating, change exactly the identified Lesson/lock, write audit/outbox and permanent raw response plus compensation ReceiptRef in the SAME transaction. Any event/marker/receipt/CAS failure rolls all local effects back. Capture bounded genuine received evidence independently where needed; a failed transaction is not evidence that Revenue had no effect.
Amend SQL guards explicitly. compensating must count as protected for all current direct/indirect old-and-new association guards, source replay/protection lookups and ordinary financial/closure admission. Extend the active-Lesson/lock unique partial indexes to include both phases, preventing a second protection from being installed around the changed rows. Preserve the original coach/window slot exclusion while compensating even though the Lesson is Canceled, and retain exact original-obligation replacement blockers until finalization; a fresh key cannot bypass unresolved original work. The current slot query based only on Lesson status is insufficient for that new phase. A narrow guard exception must validate this exact compensation journal, original receipt, prior generation and whitelisted field transition, limited to the two identified rows; no generic bypass for every row sharing Person/Market/config, and no transaction marker alone as authorization. Schema owner/runtime privilege boundaries and drain/epoch enforcement remain required. Ordinary retirement cannot operate on compensating state using a generic abandoned response.
After the exact Delivery receipt, Revenue verifies/stores it and completes its own allowed reservation/Order writeback. Then a fresh owner evidence read carrying the same authority and compensation receipt, completed writeback and irreversible abandoned continuation may permit Delivery's generation-g+1 CAS to retired g+2, with immutable finalization proof. Require no pending compensation work or executable original collection. A lost response, failed Revenue writeback, unknown provider result, resource disagreement or retirement response loss remains protected/replayable under the original identity. No second compensation key, clear-then-cancel, timeout retirement or rollback to collection. Finalization must not be circular: first atomic Delivery compensation while protected; then Revenue writeback; then exact finalization.
Concurrent same-key requests replay one status/body/receipt/event; different payload or reused identity conflicts. Authenticate and correlate immutable original provenance before replay disclosure; a retained same completed compensation does not have to satisfy its old pre-effect held/g/outcome-version predicates again. Fresh Revenue evidence must continue echoing its immutable authority/request association even after current writeback/revision advances. Current-state changes never cause a second transition or reconstructed receipt. Enforce at most one consuming compensation per original bind/protection generation. Concurrent new bind/settlement/ordinary cancellation/closure/invalidating writers either observe the protected/compensating guard or serialize to an exact conflict; they cannot reinterpret the original bind as noncommitted. A settlement of the original bind continues returning its original committed ReceiptRef. Stale compensation after ordinary terminal retirement cannot cancel a newer booking. Late genuine provider/credit facts remain immutable and require reconciliation; they do not reopen original collection or rewrite terminal compensation. Bounded recovery retains durable attempts and explicit pending work.
Recommend a separate permanent compensation command/receipt ledger and immutable evidence/finalization records, with unique original-generation consumption, same barrier and no TTL/update/delete/TRUNCATE/cleanup. Extend the continuation state/check constraints and guard only through an approved migration. Keep original bind command/ReceiptRef formats unchanged. Compensation ReceiptRef v1.0 should bind its own receipt/intent/key/fingerprint/body digest/http status/event ID, full original bind ReceiptRef, authority identity/revision/evidence digest, previous/new generation, original/target lock versions, exact resulting Lesson/lock states and retained decision time. Store original response bytes permanently; do not put proofs, bearers, cookies or redeemable financial credentials in it.
Audit questions, versions and approval gates
These private operational records must answer: which original failed close authorized this exact unwind (original/compensation/authority references and evidence digest); whether a retry repeated a side effect (one generation consumption and immutable receipt/outbox identity); and why a resource stayed protected (compensating state, durable attempt and finalization/writeback association). They are source-backed audit facts, not a proposed warehouse model or synthesized lifecycle history.
Recommend separately versioned compensation command/evidence/receipt sub-specs v1.0.0, scheduling v2.1.0 with explicit continuation/guard/history amendment, credit-reservation-lock v3.6.0 only if its existing wire/consumer duties remain compatible, Identity v1.6.0 and service-auth v1.9.0 subject to the history obligation. Revenue's mandatory signed Sales descriptor on original close requires ordering v3.0.0 and explicit descriptor trust/digest/eligibility/tombstone migration. Delivery does not approve that signature trust or financially unseen-key settlement by this memo. A never-admitted Revenue close tombstone does not cancel an original Delivery soft hold or authorize a replacement; its exact resource/blocker resolution remains separately specified.
The narrow held-to-released transition uses existing state names but adds protection and financial-authorization rules. Record an explicit ADR-0006 joint-review disposition/amendment with Revenue for the precise effects, initiator/reason and in-flight locks. Current hold-cancel payload permits strings but that does not approve a new semantic reason/originator. Freeze the owner-approved Delivery cancellation event/reason/actor and Revenue credit.released v2 reason/actor (or justified absence) with producer-transactional publication and consumer compatibility. Use a major if existing required wire, terminal interpretation or consumer obligations change. No deprecation-clock restart, unsafe old sender activation or general flow removal.
Before acknowledgment, return exact closed schemas/method/query/header/error taxonomy; quiescence/no-new-collection and owner writeback proofs; the approved source/target mirror timing and reason/events; transferred-protection/finalization guards and resource/history rule; version/ADR-0006 disposition and safe writer/drain/migration/rollback plan. Later source-pinned isolated real-handler proofs must cover auth/path/query/schema denial with unchanged row hashes/counts; stale/mismatched original receipt and g; contradictory staged facts; simultaneous bind/settlement/cancel/closure and raw SQL old/new-resource races; same/different compensation retries; event/receipt/marker rollback; lost Delivery response and failed Revenue writeback; success-with-failed-financial-writeback/unknown provider refusing compensation; irreversible finalization and late facts; archived/merged/paused historical access; and no owner HTTP while any local lock is held. Observe dispatch and row effects, not only 2xx. Existing 45-case ADR-0052 proof satisfies none of the new operation's gates.
The eleven general financial residuals in Delivery's incoming-fact inventory remain out of ADR-0053 scope. Existing supported composite/reschedule/rebook/invoice/top-up motions need their own compatible-authority/coverage work, not this exact unwind permission. No refund, forfeit, general release, generic cancellation or Sales Lost closure permission is added.
References and publication boundary
- Proposed ADR-0053 and approval request, pin
3225646710eb3073a4e8e5e5f8a6fb9f07eeb1cf. - Platform position, Sales position, pin
74904433fe7c873288697a87aebd8ff0024232de; Revenue position, pine43e3e8ddd2032f902dcb4a79070d974a174db86. - Delivery source
b53b08832582dea43fba0832be5eea2a480133d3,modules/scheduling-command/{repo,schema,resources,operational-fact,route}.ts,lib/revenue/scheduling-bind-evidence-client.ts,modules/lesson-hold/repo.ts,prisma/schema.prisma, migration20261003005200_scheduling_command_v2, anddocs/adr0052-{delivery-local-integration,incoming-fact-inventory}.mdin the preserved isolated worktree. - Accepted ADR-0052 package
43cd36bc312cdda3e1e2543215df55a7ace52ab1, scheduling workload/bind settlement, Revenue bind evidence, and ADR-0006.
Live Delivery ADR-scoped inbox refreshed at 2026-10-03T01:53:47.840Z contained the proposal and all three owner positions. No runtime or publication commitment is completed. Only this Delivery position is prepared in the permitted Delivery coordination clone. Root is sole publisher/indexer/freshness owner for the review batch; no independent publication/indexing, other-owner acknowledgment, contract/ADR edit, runtime/database/provider/deploy change or fixture reset occurred.