Define witnessed admission and settlement contracts

[flyingrobots]

Summary

• define the closed derived | plural | conflict | obstruction admission algebra as runtime-backed classes
• require a distinct typed witness and residual posture for every admission variant
• keep runtime execution failures outside the causal outcome union
• add a non-authoritative SettlementPlan bound to exact lanes, frontiers, proposal, law, and policy
• correct the README and architecture doctrine so CRDT join is a domain settlement law, not a universal merge claim

Scope

This is the contract checkpoint for #765. It does not expose the new types from package root or classify live writes/imports yet; #765 remains open for the semantic-matrix classifier and runtime integration.

Refs #765
Refs #712

Verification

• npm run lint
• npm run lint:semgrep
• npm run typecheck
• npm run lint:md:code
• npm run lint:docs-topology
• focused admission/settlement tests: 11 passed
• focused coverage: 100% statements, branches, functions, and lines
• pre-push stable unit shards: 577 files passed, 1 skipped; 7,115 tests passed, 2 skipped

Review posture

Self-review found one anti-sludge false positive for the semantic retry value unknown; the two exact lines now carry narrow inline suppressions explaining that they are value vocabulary, not the TypeScript unknown type. No unresolved self-review findings remain.

[flyingrobots]

Self-code review

Severity	Open	Resolved in branch
Critical	0	0
High	0	0
Medium	0	0
Low	0	1

Resolved finding:

File	Infraction	Severity	Resolution
src/domain/admission/AdmissionRetryDisposition.ts	The broad anti-sludge regex treated the semantic string/method name unknown as the TypeScript unknown type.	Low	Added narrow, justified inline suppressions on only the two false-positive lines; npm run lint:semgrep now passes with zero quarantined hits.

No open findings remain after reviewing origin/main...HEAD for phase semantics, illegal state construction, witness completeness, settlement-plan authority, CRDT doctrine, and test coverage. Graft reports no breaking changes.

@codex please confirm the closed-union, witness-binding, and admission-versus-settlement phase boundaries.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7716a100-2db1-4354-8318-ba493da0101a

📥 Commits

Reviewing files that changed from the base of the PR and between 621e60b and 02da63b.

📒 Files selected for processing (6)

• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/admissionValidation.ts
• test/unit/domain/admission/AdmissionOutcome.test.ts

📝 Walkthrough

Walkthrough

The PR documents admission-versus-settlement semantics and adds immutable TypeScript domain objects for four admission outcomes, witnesses, residual postures, execution results, retry dispositions, and bound settlement plans, with comprehensive validation tests.

Changes

Admission and settlement model

Layer / File(s)	Summary
Admission and settlement semantics ARCHITECTURE.md, README.md, docs/topics/api/README.md	Documentation defines deterministic admission classification, four admission variants, witness requirements, residual states, and revalidated settlement plans.
Admission domain model src/domain/admission/*	Adds validated immutable evaluations, witnesses, outcomes, postures, execution wrappers, retry dispositions, obstruction reasons, reference normalization, and exhaustive matching.
Settlement plan contract src/domain/settlement/SettlementPlan.ts	Adds an immutable settlement plan bound to distinct lanes, frontiers, digests, law, and policy inputs.
Admission and settlement validation test/unit/domain/admission/AdmissionOutcome.test.ts, test/unit/domain/settlement/SettlementPlan.test.ts	Tests outcome wiring, immutability, exhaustive matching, runtime validation, reference normalization, execution wrappers, and settlement-plan constraints.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• #765 — The PR implements the issue’s admission-classification and settlement separation with typed outcomes, witnesses, and revalidated settlement plans.

Poem

I’m a rabbit with plans in a lane,
Four outcomes hop through the domain.
Witnesses freeze, refs sort bright,
Stale plans vanish out of sight.
Fold, classify, settle true—
Carrots of certainty for you!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.25% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: witnessed admission and settlement contracts.
Description check	✅ Passed	The description covers summary, issue refs, verification, and review notes, with only template-specific headings and ADR checklist items omitted.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/domain/admission/AdmissionObstructionReason.ts`:
- Around line 50-56: Add static factory methods to AdmissionObstructionReason
for capability-denied, unsupported-evidence, law-violation, budget-exceeded, and
unsupported-contract, matching invalidDerivation and staleBasis. Each factory
should accept the code string and construct the reason using its corresponding
named constant, so callers no longer need raw obstruction-family literals.

In `@src/domain/admission/DerivationWitness.ts`:
- Around line 21-27: Extract the shared null/undefined fields and
AdmissionEvaluation instance checks into a requireAdmissionEvaluation-style
helper in src/domain/admission/admissionValidation.ts. Update DerivationWitness
to call it, replace PluralityWitness.requireFields with it while retaining the
distinct-coordinate validation, and replace
ObstructionWitness.requirePresentFields/requireEvaluation with it; preserve the
existing validation errors and codes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 2b17f606-f05c-4c8f-b5e4-501b8d8abb27

📥 Commits

Reviewing files that changed from the base of the PR and between 4ebf810 and 621e60b.

📒 Files selected for processing (29)

• ARCHITECTURE.md
• README.md
• docs/topics/api/README.md
• src/domain/admission/AdmissionEvaluation.ts
• src/domain/admission/AdmissionExecution.ts
• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/AdmissionOutcome.ts
• src/domain/admission/AdmissionResidualPosture.ts
• src/domain/admission/AdmissionRetryDisposition.ts
• src/domain/admission/AdmissionRuntimeFailure.ts
• src/domain/admission/AdvancedAdmissionPosture.ts
• src/domain/admission/CompletedAdmissionExecution.ts
• src/domain/admission/ConflictAdmission.ts
• src/domain/admission/ConflictWitness.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/DerivedAdmission.ts
• src/domain/admission/FailedAdmissionExecution.ts
• src/domain/admission/ObstructedAdmission.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/admission/PluralAdmission.ts
• src/domain/admission/PluralAdmissionPosture.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/UnchangedAdmissionPosture.ts
• src/domain/admission/UnsettledConflictAdmissionPosture.ts
• src/domain/admission/admissionValidation.ts
• src/domain/admission/matchAdmission.ts
• src/domain/settlement/SettlementPlan.ts
• test/unit/domain/admission/AdmissionOutcome.test.ts
• test/unit/domain/settlement/SettlementPlan.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: coverage-threshold
• GitHub Check: test-node (22)
• GitHub Check: preflight

🧰 Additional context used

📓 Path-based instructions (4)

src/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.{ts,tsx,js,jsx}: Do not introduce any, as any, as unknown as, unknown (outside adapters), Record<string, unknown> (outside adapters), *Like placeholder types, JSON.parse/JSON.stringify (outside adapters), fetch (outside adapters), process.env (outside adapters), @ts-ignore, or z.any() in core code; use validated boundary models and ports instead.
Use constructor-injected ports for external capabilities; do not rely on ambient dependencies for I/O, clocks, persistence, or entropy.
Do not create utils.ts, helpers.ts, misc.ts, or common.ts; name files after the actual concept they model.
Prefer one file per class, type, or object; if a file accumulates peer concepts, split it.
Keep helper corridors, fake shape trust, transitional duplication, and compile-time theater out of the codebase; runtime-honest TypeScript must reflect actual behavior.
No enum usage; prefer runtime-backed domain forms and unions.
Do not use boolean trap parameters; prefer named option objects or separate methods.
Avoid magic strings or numbers when a named constant should exist.
Keep domain bytes as Uint8Array; Buffer belongs in infrastructure adapters.

Files:

• src/domain/admission/AdmissionOutcome.ts
• src/domain/admission/AdvancedAdmissionPosture.ts
• src/domain/admission/FailedAdmissionExecution.ts
• src/domain/admission/UnsettledConflictAdmissionPosture.ts
• src/domain/admission/PluralAdmissionPosture.ts
• src/domain/admission/DerivedAdmission.ts
• src/domain/admission/AdmissionEvaluation.ts
• src/domain/admission/AdmissionRuntimeFailure.ts
• src/domain/admission/ConflictWitness.ts
• src/domain/admission/UnchangedAdmissionPosture.ts
• src/domain/admission/ObstructedAdmission.ts
• src/domain/admission/AdmissionExecution.ts
• src/domain/admission/PluralAdmission.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/CompletedAdmissionExecution.ts
• src/domain/admission/matchAdmission.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/AdmissionResidualPosture.ts
• src/domain/admission/admissionValidation.ts
• src/domain/admission/AdmissionRetryDisposition.ts
• src/domain/admission/ConflictAdmission.ts
• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/settlement/SettlementPlan.ts

src/domain/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

src/domain/**/*.{ts,tsx,js,jsx}: In src/domain/**, do not use Date.now(), new Date(), Date(), performance.now(), Math.random(), crypto.randomUUID(), crypto.getRandomValues(), setTimeout, setInterval, raw new Error(...)/new TypeError(...), or direct imports from Node built-ins; time, entropy, and external capabilities must enter through ports or parameters, and domain errors should extend WarpError.
Construct domain objects only in core when doing so establishes validated runtime truth; do not build infrastructure adapters, host APIs, persistence implementations, wall clocks, or entropy sources inside core.
Prefer discriminated unions and explicit result types instead of boolean-flag bags, and model expected failures as return values rather than exceptions.
src/domain/ must not import host APIs or Node-specific globals; hexagonal architecture boundaries are mandatory.
Domain code must not use the wall clock directly; time must enter through a port or parameter.

Files:

• src/domain/admission/AdmissionOutcome.ts
• src/domain/admission/AdvancedAdmissionPosture.ts
• src/domain/admission/FailedAdmissionExecution.ts
• src/domain/admission/UnsettledConflictAdmissionPosture.ts
• src/domain/admission/PluralAdmissionPosture.ts
• src/domain/admission/DerivedAdmission.ts
• src/domain/admission/AdmissionEvaluation.ts
• src/domain/admission/AdmissionRuntimeFailure.ts
• src/domain/admission/ConflictWitness.ts
• src/domain/admission/UnchangedAdmissionPosture.ts
• src/domain/admission/ObstructedAdmission.ts
• src/domain/admission/AdmissionExecution.ts
• src/domain/admission/PluralAdmission.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/CompletedAdmissionExecution.ts
• src/domain/admission/matchAdmission.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/AdmissionResidualPosture.ts
• src/domain/admission/admissionValidation.ts
• src/domain/admission/AdmissionRetryDisposition.ts
• src/domain/admission/ConflictAdmission.ts
• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/settlement/SettlementPlan.ts

src/domain/**/!(*.test).{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use explicit domain concepts with validated constructors, Object.freeze, and instanceof dispatch; domain objects should be runtime-backed nouns, not ad hoc shape bags.

Files:

• src/domain/admission/AdmissionOutcome.ts
• src/domain/admission/AdvancedAdmissionPosture.ts
• src/domain/admission/FailedAdmissionExecution.ts
• src/domain/admission/UnsettledConflictAdmissionPosture.ts
• src/domain/admission/PluralAdmissionPosture.ts
• src/domain/admission/DerivedAdmission.ts
• src/domain/admission/AdmissionEvaluation.ts
• src/domain/admission/AdmissionRuntimeFailure.ts
• src/domain/admission/ConflictWitness.ts
• src/domain/admission/UnchangedAdmissionPosture.ts
• src/domain/admission/ObstructedAdmission.ts
• src/domain/admission/AdmissionExecution.ts
• src/domain/admission/PluralAdmission.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/CompletedAdmissionExecution.ts
• src/domain/admission/matchAdmission.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/AdmissionResidualPosture.ts
• src/domain/admission/admissionValidation.ts
• src/domain/admission/AdmissionRetryDisposition.ts
• src/domain/admission/ConflictAdmission.ts
• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/settlement/SettlementPlan.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx,js,jsx}: Do not use direct imports from src/infrastructure/** in src/domain/** or src/ports/**; depend on a port instead.
Do not use direct Node built-ins in src/domain/** or src/ports/**; use a port instead.

Files:

• src/domain/admission/AdmissionOutcome.ts
• src/domain/admission/AdvancedAdmissionPosture.ts
• src/domain/admission/FailedAdmissionExecution.ts
• src/domain/admission/UnsettledConflictAdmissionPosture.ts
• src/domain/admission/PluralAdmissionPosture.ts
• src/domain/admission/DerivedAdmission.ts
• test/unit/domain/settlement/SettlementPlan.test.ts
• src/domain/admission/AdmissionEvaluation.ts
• src/domain/admission/AdmissionRuntimeFailure.ts
• src/domain/admission/ConflictWitness.ts
• src/domain/admission/UnchangedAdmissionPosture.ts
• src/domain/admission/ObstructedAdmission.ts
• src/domain/admission/AdmissionExecution.ts
• src/domain/admission/PluralAdmission.ts
• src/domain/admission/DerivationWitness.ts
• src/domain/admission/CompletedAdmissionExecution.ts
• src/domain/admission/matchAdmission.ts
• src/domain/admission/PluralityWitness.ts
• src/domain/admission/AdmissionResidualPosture.ts
• src/domain/admission/admissionValidation.ts
• src/domain/admission/AdmissionRetryDisposition.ts
• src/domain/admission/ConflictAdmission.ts
• src/domain/admission/AdmissionObstructionReason.ts
• src/domain/admission/ObstructionWitness.ts
• src/domain/settlement/SettlementPlan.ts
• test/unit/domain/admission/AdmissionOutcome.test.ts

🔇 Additional comments (26)

ARCHITECTURE.md (1)

160-160: LGTM!

Also applies to: 193-193, 250-265

README.md (1)

28-28: LGTM!

Also applies to: 239-264, 337-337, 360-369, 405-422

docs/topics/api/README.md (1)

319-323: LGTM!

Also applies to: 332-378, 389-393, 409-409, 426-448, 462-488

src/domain/admission/admissionValidation.ts (1)

1-30: LGTM!

src/domain/admission/AdvancedAdmissionPosture.ts (1)

1-13: LGTM!

src/domain/admission/UnsettledConflictAdmissionPosture.ts (1)

1-13: LGTM!

src/domain/admission/AdmissionResidualPosture.ts (1)

1-10: LGTM!

src/domain/admission/ConflictWitness.ts (1)

1-56: LGTM!

src/domain/admission/PluralAdmissionPosture.ts (1)

1-12: LGTM!

src/domain/admission/AdmissionEvaluation.ts (1)

1-49: LGTM!

src/domain/admission/AdmissionObstructionReason.ts (1)

59-65: LGTM!

src/domain/admission/AdmissionRetryDisposition.ts (1)

1-52: LGTM!

src/domain/admission/AdmissionRuntimeFailure.ts (1)

1-16: LGTM!

src/domain/admission/UnchangedAdmissionPosture.ts (1)

1-14: LGTM!

src/domain/admission/ObstructedAdmission.ts (1)

1-19: LGTM!

src/domain/admission/FailedAdmissionExecution.ts (1)

1-16: LGTM!

test/unit/domain/admission/AdmissionOutcome.test.ts (1)

1-535: LGTM!

src/domain/admission/AdmissionOutcome.ts (1)

1-12: LGTM!

src/domain/admission/ConflictAdmission.ts (1)

1-20: LGTM!

src/domain/admission/DerivedAdmission.ts (1)

1-20: LGTM!

src/domain/admission/PluralAdmission.ts (1)

1-20: LGTM!

src/domain/admission/matchAdmission.ts (1)

1-34: LGTM!

src/domain/admission/CompletedAdmissionExecution.ts (1)

1-26: LGTM!

src/domain/admission/AdmissionExecution.ts (1)

1-5: LGTM!

src/domain/settlement/SettlementPlan.ts (1)

1-56: LGTM!

test/unit/domain/settlement/SettlementPlan.test.ts (1)

1-78: LGTM!

[github-actions]

Release Preflight

• package version: 18.2.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Main Push Release Branch Check will run final preflight and create v18.2.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[github-actions]

Release Preflight

• package version: 18.2.1
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Main Push Release Branch Check will run final preflight and create v18.2.1. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.