Enforce exact optional source boundaries

[HardlyDifficult]

Summary

• enable exactOptionalPropertyTypes as a permanent production-source gate and eliminate every source diagnostic
• project Canton submit inputs from plain own data descriptors only, rejecting proxies, accessors, symbols, custom prototypes, and explicit undefined without invoking traps
• return a frozen, readonly AppliedCommandContext containing only canonical submit fields with detached immutable trace context
• omit absent read scope, telemetry, template identity, and converter fields instead of materializing undefined
• make template identity comparison a true success/failure discriminated union
• validate unknown stock issuance wire values without casts
• use the shared any-resistant exactness harness across source, built, and public declaration checks

Validation

Exact head afb3b58344a696e89212efcee84a9db6df1fc1c2:

• npm run lint
• npm run format
• npm run build
• npm run typecheck
• npm run test:declarations
• full npm run test:ci: 74 suites / 4,082 tests
• git diff --check
• two independent boundary audits, including adversarial proxy/accessor/revoked-proxy and declaration/runtime-parity probes

Stack

Depends on #417.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6b3f1328-bb46-4f1e-bc4a-c169aecb3e82

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/exact-optional-boundaries

---

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

[HardlyDifficult]

CI is green on the latest head, including the full OCP QuickStart integration suite.

@copilot review
@coderabbitai review

[coderabbitai]

@HardlyDifficult Thanks for the update — glad CI is green on the full suite. I'll review the latest changes now.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Copilot]

Pull request overview

This PR tightens TypeScript “exact optional” object-shape boundaries across production src by omitting absent optional fields (instead of materializing undefined), and introduces a permanent exactOptionalPropertyTypes compile gate for production source.

Changes:

• Add tsconfig.exact-source.json and wire test:exact-source into npm run typecheck to enforce zero exactOptionalPropertyTypes diagnostics in src.
• Refactor multiple boundary objects (read scope, telemetry/template identity, OCF converters) to conditionally omit optional keys rather than assigning undefined.
• Make template identity comparison a success/failure discriminated union and strengthen unknown wire-value validation for stock issuance type.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsconfig.exact-source.json	Adds a dedicated exact-optional compile gate for src/**/*.ts.
package.json	Wires the new exact-source gate into typecheck.
src/observability.ts	Adjusts command context application typing/shape to avoid undefined optional assignments.
test/observability/observability.test.ts	Removes an unsafe cast and exercises the updated observability helper typing.
src/utils/templateIdentity.ts	Introduces a discriminated union for template identity comparison and omits absent optional fields in error context.
src/utils/cantonOcfExtractor.ts	Routes read scope through ledgerReadScope without materializing undefined and threads read scope through extraction.
src/functions/OpenCapTable/shared/singleContractRead.ts	Omits absent template identity fields in read results and in template identity validation inputs.
src/functions/OpenCapTable/capTable/getCapTableState.ts	Omits absent readAs instead of passing undefined.
src/functions/OpenCapTable/capTable/CapTableBatch.ts	Avoids passing undefined telemetry/templateId fields and adjusts context construction.
src/functions/OpenCapTable/capTable/archiveCapTable.ts	Omits absent optional command fields in command construction/telemetry.
src/functions/OpenCapTable/vestingTerms/getVestingTermsAsOcf.ts	Omits absent optional OCF vesting period fields rather than emitting undefined.
src/functions/OpenCapTable/stockPlan/getStockPlanAsOcf.ts	Omits absent optional OCF stock plan fields; normalizes optional cancellation behavior handling.
src/functions/OpenCapTable/stockIssuance/getStockIssuanceAsOcf.ts	Validates unknown issuance type wire values and omits absent optional issuance type.
src/functions/OpenCapTable/issuer/getIssuerAsOcf.ts	Tightens helper return types for optional issuer contact fields.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[HardlyDifficult]

Current head a9da845 is green and merge-clean; it preserves complete caller parameter subtypes through applyCommandContext and reuses a single read-scope value. All prior review threads are addressed and resolved.

@copilot review
@coderabbitai review

[HardlyDifficult]

cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a9da845. Configure here.}

[HardlyDifficult]

cursor review

[HardlyDifficult]

@copilot review

[HardlyDifficult]

CodeRabbit exact-head review is intentionally deferred until the current organization-wide rate-limit window expires; this PR remains unassigned Stage 2.

[HardlyDifficult]

Material parent integration and command-context soundness fix are complete at exact head ac8df1f. Final #417 head 0aa47b1 was merged normally with no history rewrite.

AppliedCommandContext now exposes the canonical plain ledger-submit shape with omission-only, readonly command-context fields. Runtime merging normalizes and snapshots params context through #417 immutable machinery, preserves params < default < per-call precedence, adds context fields to the public result, and no longer promises arbitrary prototype or non-enumerable members through an object spread. Source, built declaration, exact-optional, and runtime regressions cover the contract.

Validation is green: focused observability/OcpClient/authorization 3 suites / 248 tests; full 73 suites / 3,737 tests; build; declarations; exact-source and exact-public-config compilers; regular typecheck; ESLint with zero warnings; Prettier; and diff checks. This PR remains draft and unassigned; no automated reviews or downstream propagation were requested.

[HardlyDifficult]

Independent exact-head audit follow-up is pushed at e7501f6eea943967420936f009ad5b5a598b1b49.

The audit found and fixed two soundness gaps before automated review:

• A structurally valid submit-params class could provide required commands via a prototype getter or non-enumerable own property; object spread dropped it while AppliedCommandContext still promised the field. Required submit fields are now projected explicitly through a compile-time-exhaustive key set, so future Canton dependency additions fail compilation until handled.
• ReadonlyTraceContext inherited explicit undefined unions for trace identifiers, contradicting the omission-only exact-optional contract. traceId, spanId, parentSpanId, and metadata are now omission-only.

Regressions cover source and built declarations plus prototype-getter/non-enumerable runtime inputs. Precedence and immutability remain params < default < per-call, explicit undefined skips rather than clears, snapshots are detached/frozen, and custom prototype helpers are not promised.

Validation on this exact revision: focused observability 8/8; full 73 suites / 3,738 tests; build; typecheck and exact source; declarations and exact built; lint; format; diff check; and a manual built-package adversarial runtime check. The PR remains draft and unassigned while exact-head CI and QuickStart run.

[HardlyDifficult]

Fresh exact-projection audit hardening is pushed at exact head bd768200a37d3ec385e4dc37d7608ba11fd30894.

The audit reproduced one projection root cause: spread-based copying silently dropped valid optional Canton fields supplied through prototype getters/non-enumerable properties, while leaking unrelated enumerable helper/caller fields into the supposedly canonical ledger submit object.

The result is now built from a compile-time-exhaustive list of every required and optional SubmitTransactionTreeParams key. Each present canonical field is snapshotted exactly once, inherited/non-enumerable structural inputs are preserved, absent/undefined optionals are omitted, context precedence applies only to context keys, and unknown/callable extras are excluded. Future Canton submit-field additions fail compilation until explicitly projected. Trace/context snapshots remain detached, frozen, readonly, and source/built exact.

Validation on this exact revision: focused observability/type gates; full 73 suites / 3,738 tests; build; typecheck; declarations; exact source+built checks; lint; format; and a built adversarial projection probe. The PR remains draft and unassigned. Its base #417 subsequently advanced, so this head is intentionally awaiting a conflict-aware parent merge; no reviews were requested.

[HardlyDifficult]

Corrected stack propagation complete at exact head c33911048a3102c1755d4a77505042d6987f9131.

Merged corrected #417 (9846a798c2db5c206e9b67daaae25427712b093e) with a normal merge commit. Five conflicts were resolved across observability, command-context snapshots, and the source/built exact-type harnesses. The result keeps #417 exact plain-object validation for context and options plus trap-safe rejection diagnostics, while limiting #418 structural support to ledger submit params. The exhaustive canonical projection still materializes prototype and non-enumerable fields, reads canonical fields once, strips caller-specific keys and methods, and freezes detached trace snapshots. Both source and built exact-optional assertions are retained.

Validation:

• focused regression: 6 suites / 581 tests
• full unit suite: 73 suites / 4,033 tests
• build and typecheck
• declaration and source/built exact-public-config harnesses
• lint, formatting, and diff checks

All local checks pass. PR remains draft and unassigned while CI and downstream propagation run.

[HardlyDifficult]

Re-propagated corrected PR #417 head 0971a4e74c2d7edf1150c913a2c3c165333096df with a normal merge commit. The new exact head is 199d2b94ac797a220e1d3dc17515baa0fed391ee.

Preserved #418 exact optional boundaries and plain applied-command-context semantics together with the corrected full-payload PlanSecurity pricing delegation and six-variant Monetary parity.

Validation is green locally: 5 focused suites / 183 tests; full coverage run 73 suites / 4,047 tests; clean build; typecheck; declaration, exact source, and exact public-config tests; lint; Prettier; and diff checks. This PR remains draft and unassigned pending downstream propagation and fresh exact-head reviews.

[HardlyDifficult]

@copilot review

Please review exact current head 199d2b94ac797a220e1d3dc17515baa0fed391ee. Pre-review gate: both required checks are successful, GitHub is CLEAN/MERGEABLE, the PR is unassigned, and zero review threads are unresolved. Focus on exact optional-property semantics, hostile descriptor/proxy boundaries, public declaration/runtime parity, and regression coverage. Report every actionable current-head issue before the other reviewers.

[Copilot]

@copilot review

Please review exact current head 199d2b94ac797a220e1d3dc17515baa0fed391ee. Pre-review gate: both required checks are successful, GitHub is CLEAN/MERGEABLE, the PR is unassigned, and...

Reviewed exact head 199d2b94ac797a220e1d3dc17515baa0fed391ee against codex/exact-public-config-state with focus on exact optional semantics, hostile descriptor/proxy boundaries, declaration/runtime parity, and regression coverage; I don’t see any remaining high-confidence actionable issues in the current diff.

[HardlyDifficult]

@cursor review

Please review exact current head 199d2b94ac797a220e1d3dc17515baa0fed391ee. Copilot completed its required exact-head pass with no actionable findings: #418 (comment). Both required checks are green, GitHub is CLEAN/MERGEABLE, and zero review threads are unresolved. Focus on exact optional-property semantics, hostile descriptor/proxy boundaries, declaration/runtime parity, and regression coverage.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 199d2b9. Configure here.}

[HardlyDifficult]

Returned to draft because upstream #417 received a material exact-head corrective revision after full CodeRabbit review. This stacked PR will remain held until the audited #417 head and each intervening parent are propagated normally; fresh CI and Copilot-first reviewer gates are required afterward.

[HardlyDifficult]

Updated this draft to exact upstream #417 head e4338804bafa169f9ed0f9e2829b193ba95de4de; current exact head is ab6bb2146d3b439a408f2890a8ea193def676744.

The integration preserves omission-only optional fields while retaining #417’s exact command snapshots, field-wise trace-context precedence, and disclosed-contract handling. It also adds an exhaustive nested submit TraceContext projection and replaces the standalone weak exactness oracle with the shared any-resistant helper.

A clean-checkout audit exposed and I fixed two additional blockers before pushing: an impossible context === undefined lint branch and a whole-ledger-type equality assertion that exceeded TypeScript’s instantiation depth. Local validation now passes: build; exact source and normal typecheck; lint; Prettier; declaration/public-config gates; focused CapTableBatch/observability tests; full 74 suites / 4,074 tests; git diff --check. The PR remains draft and unassigned while fresh CI, QuickStart, and the independent audit complete; Copilot will be requested first after those gates are clean.

[HardlyDifficult]

Follow-up hardening is now on exact head f9bdc196090a7c79aa2054f32748793eeb5806a8.

The applied submit boundary now rejects Proxy, accessor, custom-prototype, and symbol-key carriers without invoking traps; reads canonical values only from captured own data descriptors; rejects explicit undefined rather than silently materializing it; validates and detaches nested trace context; freezes the top-level applied result; and exposes all top-level applied submit properties as readonly. Unknown own data members remain safely omitted. Runtime and source/built/public declaration tests cover those invariants.

Local validation on this exact revision: build; typecheck/exact-source; declaration/public-config gates; lint; Prettier; 74 suites / 4,076 tests; git diff --check. The PR stays draft and unassigned while fresh CI/QuickStart and a second independent audit run. Copilot will still be the first requested reviewer after those gates are clean.

[HardlyDifficult]

Restacked this draft onto corrected #417 head 5d872712b75264a8d20b940564e7ccdf21918745; current #418 head is 7fd62381ddbf4e0b300267b262b505321610d144.

The independent audit’s final parity finding is also fixed: source and built declaration fixtures now use valid plain own-data submit carriers, and applyCommandContext documents its runtime requirement that proxies, accessors, symbols, and custom prototypes are rejected without trap invocation. The previous stale prototype-getter claim will be removed from the PR description before review.

Local exact-head validation after propagation passes: lint, Prettier, build, typecheck/exact-source, declarations/exact-public-config, 74 suites / 4,080 tests, and git diff --check. The PR remains draft/unassigned while fresh CI and full QuickStart run; exact-head Copilot remains the first review gate after #417 is final and these checks pass.

[HardlyDifficult]

Restacked this draft onto corrected #417 exact head 84048b04c0b2aed9ed5fd382cf08979cc5a146fd; #418 is now afb3b58344a696e89212efcee84a9db6df1fc1c2. Full validation passes: 74 suites / 4,082 tests, declarations, build, typecheck, lint, formatting, and diff checks. Hosted CI and OCP QuickStart are running; reviewer requests remain deferred until #417 regains its exact-head final gate.