Enforce OCF terminal transaction completeness

[HardlyDifficult]

Summary

• rebuild this change directly on current main, with no dependency on the discarded validation stack
• enforce OCF terminal completeness only where the current OCF schema exposes the information needed to prove it
• require partial cancellations, transfers, stock repurchases, and stock conversions to materialize the exact remainder under balance_security_id
• validate an explicit convertible-conversion balance_security_id resolves, without treating quantity_converted as convertible principal
• reject multiple terminal transactions for one source, duplicate balance-successor claims, and balance successors that were already inactive
• compute warrant and equity-compensation live balances after earlier exercises/releases
• retain the existing running-balance behavior for exercises/releases because the current exercise schemas do not expose balance_security_id
• replace the single undeployed 0.0.3 DAR candidate; no version stack is added

Detailed successor economic-term continuity remains separate in #276; this PR does not duplicate that category.

OCF basis

OCF defines terminal transactions as retiring the source security_id. When a balance-capable transaction affects only part of the position, the remainder is reissued under balance_security_id.

• Terminal transactions
• Transactions in part are still terminal
• Partial transfer example

The explainer calls exercises terminal, but the current exercise primitive has no balance_security_id. This PR therefore does not invent an unreported successor or retire a known partial exercise prematurely.

Validation

Exact head: 5a24256b06d03ff9f4559d54543eb7254c9bc794

• full local DAML suite passes
• focused regressions cover partial-exercise running balances, split-adjusted equity-compensation balances, fully exercised warrant sources/successors, missing/duplicate/inactive balance successors, and multiple terminal transactions
• npm run build
• npm run format
• npm run lint: 0 errors, 2 pre-existing warnings
• npm run lint:daml: no hints
• current OCF schema-gap audit: 56 clean, 1 intentional helper skip
• npm run verify-package
• npm run verify-dars
• DAR version policy: OpenCapTable-v34 v0.0.3
• upgrade compatibility: 0.0.2 -> 0.0.3

DAR SHA-256: de46f26a1225fdcf798b1f17fa71eca57b2105b0df22bb70344233c8fb2dda6d

Exact-head replay status

• Dev replay tested 5a24256b06d03ff9f4559d54543eb7254c9bc794: failed only in batch after 755.3s of data replay (20m23s job). Current main passes the same dev snapshot, so this PR exposes remaining strict-balance data defects.
• Production replay tested the same head: failed in batch, conversion, and schema after 298.6s of data replay (13m46s job), the same public phase set as the current-main baseline.
• The prior read-only rule audit isolated the PR-specific findings: two Vortex dev security histories and eight production partial equity-compensation cancellation histories (one Omnia, seven BitSafe). The exercise-only false positives were removed by this PR's simplification.
• Both runs completed cross-participant traffic accounting: dev 8.148 MB / $135.827860 equivalent; production 3.614 MB / $60.253248 equivalent.
• No database writes are part of this validation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change centralizes terminal-event indexing and validation in the cap-table template. DAML tests now model explicit remainder securities for partial lifecycle operations and assert failures for missing or invalid balance-security references across security types.

Changes

Terminal Event Validation and Balance-Linked Tests

Layer / File(s)	Summary
Unified terminal event validation scripts/codegen/templates/CapTable.daml.template, dars/.../OpenCapTable-v34.dar	Terminal events are indexed across security families, references and balance claims are validated, successor consumption rules are enforced, and active-target checks use the computed indexes.
Balance-linked lifecycle scenarios Test/daml/OpenCapTable/TestConvertible*.daml, Test/daml/OpenCapTable/TestEquityCompensation*.daml, Test/daml/OpenCapTable/TestStock*.daml, Test/daml/OpenCapTable/TestWarrant*.daml	Partial lifecycle tests create explicit remainder securities, target their updated cap tables, and derive issuance transaction IDs from security IDs.
Invalid terminal and edge-case tests Test/daml/OpenCapTable/Test*Cancellation.daml, Test/daml/OpenCapTable/TestWarrantExercise.daml, Test/daml/OpenCapTable/TestSecurityIdValidation.daml	Tests cover missing balance securities, repeated partial warrant exercises, updated cancellation quantities, and valid full-quantity transfer cases.

Estimated code review effort: 5 (Critical) | ~120 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the core change: enforcing OCF terminal transaction completeness.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ocf-terminal-transaction-completeness

---

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

[HardlyDifficult]

@copilot review exact head a2487c47c4889fbbb44b605fa6f106787922e42c. Please review OCF terminal transaction completeness across stock, warrant, equity-compensation, and convertible reductions, including exact remainder checks, source retirement for unknown-quantity warrants, same-day event ordering, and final-state edit behavior. Exact-head CI and all 782 local DAML scripts are green.

[HardlyDifficult]

@codex review exact head a2487c47c4889fbbb44b605fa6f106787922e42c. Focus on whether every directly measurable balance_security_id family rejects omitted partial remainders, whether terminal event ordering prevents source reuse, and whether the successor-chain fixture updates preserve aggregate and vesting semantics. Copilot was requested first; CI and 782 scripts are green.

[HardlyDifficult]

@cursor review exact head a2487c47c4889fbbb44b605fa6f106787922e42c. Please inspect terminal source retirement, exact remainder calculations after splits or prior reductions, convertible principal handling, and the new negative/edit-path tests. Copilot was requested first; exact-head CI and all 782 DAML scripts are green.

[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 a2487c4. Configure here.}

[Copilot]

@copilot review exact head a2487c47c4889fbbb44b605fa6f106787922e42c. Please review OCF terminal transaction completeness across stock, warrant, equity-compensation, and convertible reductions, inclu...

Reviewed exact head a2487c4 across the requested areas. The implementation already enforces terminal source retirement and exact remainder handling for stock, warrant, equity-comp, and convertible reductions, including unknown-quantity warrant retirement without a balance successor. The updated lifecycle/final-reference tests also cover same-day successor chains and edit-time final-state behavior. No additional code changes are needed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a2487c47c4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HardlyDifficult]

@copilot review exact head 84716e5efc19bf8da68c53c2d35fa3dc2b5798d4. Please review the terminal-transaction completeness category after the same-day vesting-predecessor ordering fix. In particular, verify that every source reduction now uses terminal priority (eventDate, 2, 1), same-day priority-1 release/exercise events are folded before successor vesting state is seeded, and the new 60-release/40-transfer regression proves the corrected behavior. Exact-head CI, the full local DAML suite, DAR integrity, schema parity, and upgrade compatibility are green.

[HardlyDifficult]

@codex review exact head 84716e5efc19bf8da68c53c2d35fa3dc2b5798d4. Re-review the terminal-transaction category after the addressed finding. Focus on terminal sort-key consistency, same-day release/exercise ordering, vesting predecessor fractions, and the refreshed 0.0.19 DAR. Copilot was requested first; exact-head CI and the full suite are green.

[HardlyDifficult]

@cursor review exact head 84716e5efc19bf8da68c53c2d35fa3dc2b5798d4. Please inspect the addressed same-day terminal ordering issue, the vesting predecessor regression, and the refreshed versioned DAR. Copilot was requested first; exact-head CI and the full local validation set are green.

[Copilot]

@copilot review exact head 84716e5efc19bf8da68c53c2d35fa3dc2b5798d4. Please review the terminal-transaction completeness category after the same-day vesting-predecessor ordering fix. In particular, ...

Reviewed exact head 84716e5. The ordering fix is consistent with the requested behavior: source reductions now resolve with terminal sort key (eventDate, 2, 1), same-day priority-1 release/exercise events are included before successor predecessor seeding, and the new testVestingQuantityIntegrity_SameDayReleaseBeforeNoBalanceTransferUsesLiveSource regression exercises the 60-release/40-transfer path and passes under this ordering. No additional code changes are needed from my side.

[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 84716e5. Configure here.}

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 84716e5efc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HardlyDifficult]

Preliminary OCF validation-policy audit

Policy: OCF Validation Policy

Strong OCF basis

• OCF explicitly defines the covered operations as terminal transactions.
• A partial terminal transaction retires the original security_id; the remaining position is represented by a new balance_security_id.
• Requiring a known partial remainder to be materialized is consistent with the official transaction-traversal documentation.

Needs verification

• Do not infer an unreported convertible principal or other quantity that OCF does not expose.
• Confirm each transaction family included here is classified as terminal by the official documentation.

Proposed next step
This category appears worth preserving, but it must be reviewed on a clean accepted base and validated against dev and prod on the exact final SHA. No merge recommendation yet.

[Copilot]

Pull request overview

Enforces OCF terminal transaction semantics by retiring source security IDs and requiring explicit successor securities for partial transactions.

Changes:

• Makes stock, warrant, equity-compensation, and convertible reductions terminal.
• Validates full consumption when no balance security is provided.
• Updates fixtures, tests, package version, and DAR artifacts.

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Test/daml/OpenCapTable/TestWarrantTransfer.daml	Tests partial-transfer rejection.
Test/daml/OpenCapTable/TestWarrantCancellation.daml	Tests completeness and unknown quantities.
Test/daml/OpenCapTable/TestVestingQuantityIntegrity.daml	Updates successor-chain vesting tests.
Test/daml/OpenCapTable/TestStockTransfer.daml	Tests partial-transfer rejection.
Test/daml/OpenCapTable/TestStockSecurityBalances.daml	Materializes stock balance successors.
Test/daml/OpenCapTable/TestStockRepurchase.daml	Tests partial-repurchase rejection.
Test/daml/OpenCapTable/TestStockPlanReservedShares.daml	Updates stock-plan successor fixtures.
Test/daml/OpenCapTable/TestStockConversion.daml	Tests partial-conversion rejection.
Test/daml/OpenCapTable/TestStockClassAuthorizedShares.daml	Updates ceiling fixtures.
Test/daml/OpenCapTable/TestStockCancellation.daml	Tests partial-cancellation rejection.
Test/daml/OpenCapTable/TestNonStockSecurityBalances.daml	Adds explicit non-stock successor chains.
Test/daml/OpenCapTable/TestLifecycleInvariants.daml	Updates lifecycle chains.
Test/daml/OpenCapTable/TestFinalReferenceValidation.daml	Adds transfer balance reference.
Test/daml/OpenCapTable/TestEquityCompensationTransfer.daml	Tests partial-transfer rejection.
Test/daml/OpenCapTable/TestEquityCompensationCancellation.daml	Tests partial-cancellation rejection.
Test/daml/OpenCapTable/TestConvertibleTransfer.daml	Tests partial-transfer rejection.
Test/daml/OpenCapTable/TestConvertibleConversion.daml	Targets reduced convertible successors.
Test/daml/OpenCapTable/TestConvertibleCancellation.daml	Tests partial-cancellation rejection.
Test/daml/OpenCapTable/TestBalanceSecurityReferences.daml	Covers terminal transaction edits.
Test/daml.yaml	Uses version 0.0.19 DAR.
scripts/codegen/templates/CapTable.daml.template	Implements terminal-balance validation.
OpenCapTable-v34/daml.yaml	Bumps package to 0.0.19.
dars/OpenCapTable-v34/0.0.19/OpenCapTable-v34.dar	Adds versioned DAR artifact.
dars/dars.lock	Records DAR metadata and checksum.

[HardlyDifficult]

@copilot review exact head bcc0707f9ceab7ff7872aab82725c27d2871245e. This is the standalone main-based rebuild. Please verify OCF terminal classification, exact remainder and balance_security_id enforcement, single-terminal-source semantics, exercise/release retirement, and use of the shared terminal index. Full DAML, DAR, package, schema-gap, and upgrade checks are green; exact-head dev/prod replays are running.

[HardlyDifficult]

@copilot review

[HardlyDifficult]

@codex review

[HardlyDifficult]

@cursor review

[Copilot]

@copilot review

Reviewed current head 10cec02 in the terminal-completeness scope after the split-adjusted equity-compensation update. The terminal-index/remainder checks and successor enforcement remain consistent, and I do not have an additional code-change request from this review pass.

[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 10cec02. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 10cec0210c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HardlyDifficult]

@copilot review

[HardlyDifficult]

@codex review

[HardlyDifficult]

@cursor review

[Copilot]

@copilot review

Reviewed current head 10657ab in the terminal-completeness scope after the warrant live-balance update. The exercised-warrant handling, remainder enforcement, and successor checks are consistent with the intended behavior, and I don’t have an additional code-change request from this review pass.

[HardlyDifficult]

@copilot review

[HardlyDifficult]

@codex review

[HardlyDifficult]

@cursor review

[Copilot]

@copilot review

Reviewed current head 5a24256 in the terminal-completeness scope. The warrant exercise ordering adjustment is consistent with the intended behavior, and I don’t have an additional code-change request from this review pass.

[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 5a24256. Configure here.}

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: 5a24256b06

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[HardlyDifficult]

Final exact-head replay result

Tested 5a24256b06d03ff9f4559d54543eb7254c9bc794 after exact-head CI and automated reviews were clean.

• Dev failed only in batch: 755.3s of data replay (20m23s total job). Current main passed the same dev snapshot, so this is a PR-specific strict-balance result. The prior read-only audit isolated two Vortex security histories: sec_419bcee405a2 and sec_de69632d3142.
• Production failed in batch, conversion, and schema: 298.6s of data replay (13m46s total job), matching the public phase set of the current-main baseline. The prior read-only audit identified eight additional Enforce OCF terminal transaction completeness #281 balance defects inside the existing batch bucket: one Omnia partial equity-compensation cancellation and seven BitSafe partial cancellations.
• The exercise-only false positives were removed by the simplification; the earlier Hospitable case is no longer rejected by this rule.
• Cross-participant traffic accounting completed: dev 8.148 MB / $135.827860 equivalent; production 3.614 MB / $60.253248 equivalent.

No database writes were performed. The implementation, CI, and exact-head reviews are clean, but the PR does not yet meet the required zero-issue dev/production replay gate because these ten data histories require correction.

[HardlyDifficult]

Exact-head data findings and safe repair boundary (2026-07-22)

A fresh repeatable-read, read-only audit confirms this PR exposes 10 equity-compensation cancellation histories that current main accepts:

• Development / Vortex Systems:
  • Deterministic: source security sec_419bcee405a2 issued 300,000; cancellation tx-equity-compensation-cancellation_59b4d3ce6ba2 cancels 225,000 but self-references the source as balance_security_id. The canonical repair is a new 75,000 successor issuance plus a corrected cancellation version pointing to it.
  • Ambiguous: source security sec_de69632d3142 has two same-day 25,000 cancellations, tx-equity-compensation-cancellation_f8fd9a725e1e and tx-equity-compensation-cancellation_d1695604c5bf. They have different reason text, comments, and supporting documents. Do not deduplicate automatically; the authoritative event needs document/business review.
• Production / Omnia Systems: security 078700d4-8a94-44d9-b0b6-b452c1f0d863 has 16,182 issued, 12,137 cancelled, and a 4,045 remainder with no successor.
• Production / DLC-Link: seven partial-cancellation histories lack balance successors: 010dbb1b-4b17-4553-8e3d-729e40a74ca1, 131efde1-ee1e-440e-b550-145694ce2b1e, 1dcd8321-b13c-42a6-b685-9e85817ae686, 39d3673b-9fdc-416a-94c1-978ca9fb0334, 97c278a5-9be6-4495-b028-8ea21976e0f1, b6277839-fa66-4030-b352-f9f83e03e6d1, and bdb16aa0-1d44-4087-864e-5ff1a982043e. Three later exercises consume the exact calculated remainder and must be retargeted to the new successor security.

For the nine deterministic histories, the proposed repair appends 9 successor issuances, 9 corrected cancellation versions, and 3 corrected exercise versions. It changes no existing quantity, date, economic term, or prior version. The live dry run found zero ID/custom-ID collisions, zero unreviewed post-cancellation references, exact conservation (787,638 issued = 566,842 cancelled + 220,796 remainder), and all 21 proposed latest payloads pass the official OCF schemas. No database writes were made.

Code prerequisites before any data update

The correct OCF data shape currently exposes two application bugs:

1. Both api and apiv2 sort same-day issuances before cancellations, but their equity-compensation issuance handler does not use the existing allTransactions look-ahead to recognize a future balance_security_id. A focused test computes 1,200 for a 1,000 issuance partially cancelled by 400 with a 600 successor; the correct result is 600. Fix and regression-test this first.
2. All nine source rows have equity_grant_id = NULL. The current apiv2 portal_grants_view emits one row per equity-compensation issuance, so every canonical balance successor would appear as a second OCP-only grant. Make the unified grant list lineage-aware first.

Status: the contract requirement remains well-supported, but this PR is not data-ready until the two code prerequisites are fixed, the nine deterministic histories are repaired with explicit approval, and the ambiguous Vortex history is resolved.

[HardlyDifficult]

Standalone OCF/data audit — 2026-07-23

Audited exact head 5a24256b06d03ff9f4559d54543eb7254c9bc794 against current main (a724e3ddd01f98f72e285b1a5ebc0765acec30c4). The PR targets main directly, is merge-clean, and changes 17 files (+1,058/-224): the cap-table validator, focused DAML tests, and the single mutable 0.0.3 DAR candidate.

Supported by official OCF

• OCF explicitly defines cancellation, conversion, repurchase, reissuance, transfer, release, retraction, and exercise as terminal operations: the original security_id is retired. A partial balance-capable operation must reissue the remainder under a new balance_security_id; the original ID is no longer active (terminal semantics and families, partial-transfer graph).
• Therefore these PR rules are justified semantic validation even though JSON Schema cannot perform cross-object resolution: one terminal event per source; no later use of a retired source; a partial cancellation/transfer/stock repurchase/stock conversion needs a distinct existing balance issuance; the successor must represent the same holder/security family and exact remainder; and one balance security cannot be claimed by multiple terminal events.
• The convertible-conversion treatment is appropriately narrower: OCF quantity_converted is security units, not convertible principal, so the PR validates an explicit balance reference without inventing a principal calculation (schema).

Deliberate limitation / open spec inconsistency

• The OCF explainer calls every exercise terminal and describes balance_security_id, but the official exercise primitive does not define that field (explainer, schema). This PR correctly avoids inventing an unrepresentable successor and retains running-balance handling for exercises/releases. That means the PR enforces terminal completeness only for families the formal data shape can express; it does not fully implement the explainer's exercise model.
• OCF dates have day precision only. The PR conservatively allows non-terminal activity on the same day as retirement and rejects it only on a later date. That is a reasonable ambiguity policy, not an explicit OCF ordering rule.

Current data impact (fresh repeatable-read, read-only audit; rolled back)

• Dev: 2 histories, both Vortex Systems. sec_419bcee405a2 has a deterministic 75,000 remainder but self-references as its balance. sec_de69632d3142 has two same-day 25,000 cancellations with different reasons/documents, so deciding which event is authoritative requires document/business review.
• Production: 8 histories. Omnia Systems has 1 partial cancellation with a 4,045 remainder; DLC-Link has 7 partial cancellations with nonzero remainders. Three DLC-Link remainders are later consumed by exercises and those exercise references must move to the new successor IDs. The deterministic repair dry run remains collision-free and schema-valid: 8 successor issuances, 8 corrected cancellation versions, and 3 corrected exercise versions in prod; plus 1 successor issuance and 1 cancellation version for the deterministic dev history. No data was changed.

Code/view blockers verified on current branches

Before writing the nine deterministic repairs:

1. api master 7f9ce85 and apiv2 main 555a879 still let equity-compensation balance issuances process before their same-day cancellation without using allTransactions for initial non-minting detection (api, apiv2). The canonical successor can therefore be double-counted.
2. portal_grants_view still emits one row per equity-compensation issuance with no balance-successor lineage collapse (view). All nine deterministic source rows have equity_grant_id = NULL, so a canonical successor would appear as a second OCP-only grant.

Recommendation

Keep the contract requirement; do not weaken it or merge yet. First fix and regression-test the engine look-ahead and lineage-aware grant view, then apply the nine deterministic data repairs with explicit approval, resolve the ambiguous Vortex history, and require fresh exact-head dev and production replays with zero PR-specific issues. The latest exact-head runs remain dev and production.