cgreene / cgreene/farewright

Freeze baseline event, command, state, projection, and USD ledger contracts

Open
#7 1 comment 0 reactions 0 assignees View on GitHub

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 PaymentActionCompleted return to their originating pending state without asserting provider success.
  • Add TripRequestUpdated for explicitly reconfirmed typed request versions and CandidateSelected for 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_id across attempt/effect IDs.
  • Define refund-only relational trip_exceptions rows and the stable ordered exceptions[] trip response shape, including deterministic open/update/resolve rules and rejection of unregistered exception types.
  • Define search_results keyed 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|guard role and registry-owned policy (create_zero, caller_exact, or derived_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_versions entries 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=farewright with component-specific actor_id; the closed actor registry and every producer agree.
  • verify_mandate works before an order exists; no schema invents a required order ID.
  • TripRequestUpdated stales rather than overwrites prior searches/selections; CandidateSelected binds 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.
  • PaymentActionCompleted is 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, FixtureSeedApplied materialization, and DemoClockAdvanced map to named commands and safe payloads.
  • Only authenticated demo_admin can start a new attempt after RefundFailed; 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_pending guards.
  • headroom = cap - consumed - reserved is 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.