Freeze baseline event, command, state, projection, and USD ledger contracts
Open
Nobody has claimed this yet.
contract
testing
workstream:core
- Dominant language
- No language data
- Stars
- 0
- Forks
- 0
- Avg merge
- 8h 21m
- Merged PRs (30d)
- 2
Description
Outcome
Core and dependent workstreams share one complete, versioned, importable, and testable domain contract.
Scope
- Define recursively checked payload schemas and actor/principal/aggregate policies for every registered event.
- Complete the command → event → aggregate/state → projection matrix, including internal producers and pre-order commands.
- Resolve legal order, recovery, service, mandate, review, refund-attempt, run, clock, and trip-completion transitions. Both initial and recovery
PaymentActionCompletedreturn to their originating pending state without asserting provider success. - Add
TripRequestUpdatedfor explicitly reconfirmed typed request versions andCandidateSelectedfor non-authorizing exact selection evidence; prior graph facts remain immutable. - Specify command receipts, contiguous aggregate versions, replay/run isolation, and atomic projection responsibilities.
- Key reservations and consumption by immutable action/payment/refund-attempt IDs so one order can have initial and recovery commitments plus retries; preserve one
refund_obligation_idacross attempt/effect IDs. - Define refund-only relational
trip_exceptionsrows and the stable orderedexceptions[]trip response shape, including deterministic open/update/resolve rules and rejection of unregistered exception types. - Define
search_resultskeyed by run/traveler/search ID so asynchronous provider outcomes and candidate policy snapshots are replayable and do not overwrite prior searches.
Acceptance
- Every event has a schema version, recursively closed payload, legal actor, aggregate, named producer, and projection/replay responsibility.
- Every mutation names intent-key, attribution, its full aggregate consistency set, each entry's
append|guardrole and registry-owned policy (create_zero,caller_exact, orderived_locked), and emitted-event or durable-record behavior; no-dependency operations use an empty set, while eventless guarded commands may have guard entries but no append entry. - Mixed multi-aggregate commands accept exactly the zero/exact
expected_versionsentries and reject missing, extra, stale, or caller-supplied derived entries. - Typed dynamic aggregates discovered in a trusted provider result expand only after deduplication, use
derived_locked, and are validated before append. - Every allowed command/producer-surface pair has one stable namespaced intent-key source: caller UUID, durable OAuth authorization-transaction ID, stored browser-handoff record ID, Stripe account/event ID, persisted effect observation ID, or durable scheduled-job ID; authenticated producer class selects the rule and retry never invents a new key.
- Dispatcher attribution uses
actor_type=farewrightwith component-specificactor_id; the closed actor registry and every producer agree. -
verify_mandateworks before an order exists; no schema invents a required order ID. -
TripRequestUpdatedstales rather than overwrites prior searches/selections;CandidateSelectedbinds exact material facts and attempt order without reservation, approval, effect, or authority. - Success, approval, refusal, outage, required-action, compensation, failed-refund/retry, and trip-exception paths terminate unambiguously.
-
PaymentActionCompletedis legal from both required-action states and returns to the exact initial/recovery pending state; provider success/failure may race from either state without requiring a stale browser event. - Contract tests reject unknown nested fields, unregistered emissions, producerless events, and incompatible transitions.
- Payment setup request/consent/outcome, initial
DemoRunStarted,FixtureSeedAppliedmaterialization, andDemoClockAdvancedmap to named commands and safe payloads. - Only authenticated
demo_admincan start a new attempt afterRefundFailed; reconciliation of an existing attempt grants no retry authority. - Partial refund state distinguishes a satisfied partial target from an incomplete obligation and defines
partially_refunded → refund_pendingguards. -
headroom = cap - consumed - reservedis preserved across multiple commitments and refunds; settled refunds plus remaining obligation targets never exceed capture and one obligation has at most one nonterminal attempt. - Setup/payment provider outcomes may beat browser callbacks without requiring stale browser events; zero-cost recovery and bounded service-refund transitions terminate unambiguously.
- A no-compliant-option recovery can terminate only through explicit traveler
RecoveryDeclined; it is completion-eligible but never represented as recovery or cancellation, and a fresh choice may reopen it before trip completion. - Dependent work imports/version the contract without copying chat context.
- OAuth/session/CSRF/handoff-exchange/webhook-ingress records are explicitly transport-security state, not pseudo business commands; they cannot append domain events and hand off only to a named authenticated core command.
Dependencies
- #6 resolved spec rulings.
Review
Mandatory independent contract-gate review in #10.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the resolved spec rulings in #6, then inspect the contract tests and the registered event, command, producer, actor, and projection surfaces mentioned in the issue. Done means every acceptance item is covered, including legal transitions, version and intent-key policies, replay-safe records, and the independent contract-gate review required in #10.
Written by the indexing model from the issue text.
Assessment
- Domain
- backend-api-design, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100