Enforce successor security identity

[HardlyDifficult]

Summary

Adds the smallest contract-level validation for structural successor security identity, independently of quantities, economics, dates, or reference resolution.

• A result or balance security ID cannot reuse its transaction's source security ID.
• A balance security ID cannot also appear in the same transaction's result list.
• A successor security ID cannot be claimed by more than one lifecycle transaction.
• Source-to-successor relationships must be acyclic.
• Security IDs are unique across stock, warrant, convertible, and equity-compensation issuance families.

The validation covers stock transfers, cancellations, repurchases, conversions, reissuances, and consolidations; warrant transfers, cancellations, and exercises; convertible transfers, cancellations, and conversions; and equity-compensation transfers, cancellations, exercises, and releases.

Deliberate exclusions

This PR does not validate successor reference existence/type, quantities, economic terms, dates, running balances, or lifecycle terminality. Those concerns belong to separate, individually testable changes.

OCF basis

• security_id is created by an issuance and identifies the security in future transactions
• Transfers identify new result securities and an optional remaining balance security
• A cancellation balance security represents the remainder after a partial cancellation
• Reissuance replaces one security with result securities
• Consolidation replaces source securities with one result security

Package

• Standalone on main; no stacked PR dependency.
• Replaces the single undeployed OpenCapTable-v34 0.0.3 candidate DAR.

Validation

Exact head: e0d5a442c8092ff6f965438a28f44eaf3d2ce2c1

• npm run clean && npm run build
• npm run verify-dars
• npm run check:dar-version-policy
• npm run lint:daml
• git diff --check
• Seven focused success/failure scripts compile as part of the Test DAR. Local script execution is blocked by the workstation's missing Java runtime; CI runs the executable suite.

Replay status

Dev and production database replays have not yet been run against this exact standalone head.

[HardlyDifficult]

Restacked onto #274 exact head 4d90aa722a7209eaabf0d9d3d74a309e276a16c8, including the Codex-requested exact convertible successor-date fix. Current exact head is 5f2444ca74e8a860e927e0d250c12c3e4bd2784b.

Fresh local validation is green: all 695 DAML scripts (693 behavioral + 2 setup), the 108-script focused balance/continuity suite, codegen/package verification, formatting, ESLint (0 errors; 2 pre-existing warnings), DAML lint, pinned OCF schema parity (55/55), 15-DAR integrity, and 0.0.14 -> 0.0.15 upgrade compatibility. The refreshed 0.0.15 DAR is 5854ec5447d44f64607eb487837bf0f990ffe62415ac308ebf2412bbb8c99ff1 (3,296,344 bytes). Keeping this PR in draft pending exact-head CI.

[HardlyDifficult]

@copilot review exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b. Please review the successor-security balance and economic continuity category after its final #274 restack, including convertible principal reconciliation, quantity/class outputs, retirement, successor uniqueness/cycles, and exact-date propagation. CI is green, merge state is clean, all 695 DAML scripts pass locally, and no review threads remain.

[Copilot]

@copilot review exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b. Please review the successor-security balance and economic continuity category after its final #274 restack, including convertible...

Reviewed exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b with focus on successor-security balance/economic continuity, convertible principal reconciliation, output quantity/class checks, retirement, successor uniqueness/cycles, and exact-date propagation. I did not find additional actionable issues requiring code changes.

[HardlyDifficult]

@codex review exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b. Copilot completed this exact revision with no findings. Please focus on balance/result continuity, successor identity and retirement, fixed conversion economics, and cycle handling.

@coderabbitai review exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b. Copilot completed this revision with no findings; please perform the canonical exact-head review.

[HardlyDifficult]

@cursor review Please review exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b, focusing on successor balance/result continuity, retirement, exact dates, and conversion quantity/class reconciliation after the final parent restack. Copilot completed this exact revision with no findings.

[coderabbitai]

@HardlyDifficult I'll kick off the review of exact head 5f2444ca74e8a860e927e0d250c12c3e4bd2784b now, focusing on successor balance/result continuity, successor identity and retirement, fixed conversion economics, and cycle handling.

✅ 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.

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5f2444ca74

ℹ️ 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

[Copilot]

@copilot review

Reviewed the current exact head for successor continuity, retirement/cycle handling, and conversion output reconciliation. I did not find additional actionable issues requiring code changes.

[HardlyDifficult]

@codex review exact head 6925fe65aaee448a1844dd87cc9c9a879447a9f3. Copilot completed this material revision with no findings. Please focus on empty-result reissuance source retirement versus aggregate-share accounting and the broader successor-security continuity invariants.

@coderabbitai review exact head 6925fe65aaee448a1844dd87cc9c9a879447a9f3. Copilot completed this revision with no findings; please perform the canonical exact-head review.

[HardlyDifficult]

@cursor review Please review exact head 6925fe65aaee448a1844dd87cc9c9a879447a9f3, focusing on empty-result reissuance source retirement, aggregate-share accounting, and regressions in successor balance continuity. Copilot completed this exact revision with no findings.

[coderabbitai]

@HardlyDifficult I'll kick off the review of exact head 6925fe65aaee448a1844dd87cc9c9a879447a9f3 now, focusing on empty-result reissuance source retirement versus aggregate-share accounting and the broader successor-security continuity invariants.

✅ 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.

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

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: 6925fe65aa

ℹ️ 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]

Feature/test follow-up is complete at exact commit 3b08593c1731752de1ce1df55646c395f03cc57a.

The PR already contained the convertible principal/currency integrity implementation. This follow-up closes the remaining transfer edge-case coverage: a transfer cannot exceed the source investment amount, transfer currency must match the issuance currency, and an exact full transfer with one result and no residual balance succeeds.

Local validation on this feature commit passed: npm run build, the full npm test Daml script suite, npm run lint:daml, and git diff --check.

No package version, DAR backup, dependency, workflow-policy, or release-policy files changed in this follow-up. The PR intentionally remains draft and unassigned until stack normalization is complete and the resulting exact head passes CI and refreshed automated review gates.

[HardlyDifficult]

Preliminary OCF validation-policy audit

Policy: OCF Validation Policy

Appears supported

• Result and balance IDs resolve to the documented issuance type.
• Transfer ownership and balance-holder relationships described by OCF.
• Terminal-source behavior and quantity reconciliation where OCF makes the quantity relationship explicit.
• Schema-declared cardinality and uniqueness.

Needs line-by-line evidence or narrowing

• Reconstructed convertible/warrant economics, exact inheritance of all terms, inferred conversion outputs, and cycle rules not directly required by the OCF lifecycle model.
• Requirements imposed when OCF permits an empty or unmaterialized result.

Proposed next step
Separate reference/ownership continuity from reconstructed economics and review each economic rule independently. No merge recommendation yet.

[HardlyDifficult]

Standalone-restack note (no replay or database write performed):

This PR cannot be safely retargeted to main by mechanically replaying its unique commits. Its continuity implementation patches running-balance/event-index functions and test modules supplied by unmerged predecessor work, including TestStockSecurityBalances, TestNonStockSecurityBalances, and lifecycle-date helpers that do not exist on current main. Pulling those implementations in would silently reintroduce predecessor validators; omitting them does not compile.

Known data impact also makes this a poor “merge with no data changes” candidate: the read-only audit found nine deterministic partial equity-compensation histories whose balance_security_id has no materialized successor issuance (1 dev, 8 production), plus one separate dev history with two distinct same-day cancellation records/documents that is not safe to deduplicate automatically. The proposed nine-row repair remains review-only because current api/apiv2 same-day ordering double-counts a successor issuance, and apiv2's grants view would expose derived successors as duplicate grants.

Recommended next step: first define a standalone continuity implementation against current-main state (or merge an independently approved balance foundation), then rerun the exact dev/prod replay before considering this PR mergeable. Current PR head remains 3b08593c1731752de1ce1df55646c395f03cc57a; its stacked base is intentionally unchanged until that design is resolved.

[HardlyDifficult]

Standalone reset and data status

This PR has been rebuilt on current main at exact head e0d5a442c8092ff6f965438a28f44eaf3d2ce2c1. The previous broad/stacked implementation is no longer in the PR diff, so earlier review and replay conclusions about quantity, economics, dates, reference existence/type, running balances, or terminality do not describe the current code.

The current four-file diff validates structural successor identity only. Local clean build, DAR integrity/version policy, DAML lint, and diff checks pass. GitHub CI is running.

Data status: no dev or production replay has yet been run for this exact standalone head. Treat data compatibility as unconfirmed until those exact-head replays complete; no database update is proposed by this reset.

[HardlyDifficult]

Standalone exact-rule data audit (read-only)

Exact head e0d5a442c8092ff6f965438a28f44eaf3d2ce2c1 is standalone on main, merge-clean, and CI-green. I reproduced its narrowed structural rules against both databases using repeatable-read, read-only transactions; no data was changed.

Production: 1,621 relevant objects / 66 portals; 0 findings for every rule. This PR introduces no production successor-identity data conflict.

Development: 2,477 relevant objects / 178 portals; findings across 9 portals.

• Cross-family duplicate issuance security_id: 0.
• balance_security_id also present in the same transaction's result array: 0.
• Source reused as its own successor / cycle: 2 Vortex Systems cancellations in portal b83c52b6-3018-490b-8e8e-bb33b7d9e864:
  • tx-equity-compensation-cancellation_59b4d3ce6ba2, source/balance sec_419bcee405a2: deterministic 300,000 - 225,000 = 75,000 remainder. A lossless repair can create a copied 75,000 successor issuance with fresh IDs and point balance_security_id to it.
  • tx-equity-compensation-cancellation_f8fd9a725e1e, source/balance sec_de69632d3142: not deterministic because same-day cancellation tx-equity-compensation-cancellation_d1695604c5bf also removes 25,000 from the same 100,000 source and already points to 75,000 successor sec_a40a2c1a0131. We must decide whether the first transaction is a duplicate or represents a second reduction requiring a 50,000 chained successor.
• Successor claimed by multiple lifecycle transactions: 45 successor IDs across 8 portals.
  • 44 are in seven Protelicious/Proteclicious development fixture portals. These require a fixture/product decision—distinct result issuance per exercise or disable obsolete fixture portals—not an automatic rewrite.
  • 1 is Quine portal 40f53d6d-b26b-4c14-8279-17071379a928: exercises 3e49230e-e071-43b0-9432-e45c391828a6 and 3e49230e-e071-43b0-9432-e45c391828a8 both claim stock result bc46950a-cd22-4e1d-a219-7d4964bdb96a, issuance 9755a1e4-fd92-4afa-8545-743bd6715937 quantity 24,073. Each exercise is 24,073 from a separate grant, so either one exercise is a duplicate or a second result issuance is missing; source/business review is required.

Assessment: the narrowed structural rules are appropriate and production-clean, but this is not an early merge candidate because development contains both deterministic and ambiguous lineage conflicts. Keep it behind #269/#253/#278 while those cleaner PRs are resolved.

[HardlyDifficult]

Individual OCF and data audit

Exact scope reviewed: base main, head e0d5a442c8092ff6f965438a28f44eaf3d2ce2c1, merge-clean. The effective diff is 4 files (+527/-6): one contract-template implementation, one focused test module, and the regenerated DAR/lock. CI is green. I found no LocalNet replay run targeting this exact head; the counts below come from the existing repeatable-read, read-only exact-rule audit, not a replay.

OCF support

Source of truth reviewed at Open-Cap-Format-OCF 095182023cd620cc55d49777b5c8f75a3376120b:

• Supported at the OCF data-model level: a terminal transaction either creates a new security_id or extinguishes the original, and the original becomes inactive (transaction traversal, lines 42-49 and 112-132). This supports rejecting a source reused as its own successor and rejecting cycles.
• Supported at the OCF data-model level: partial transfers require a new balance identity, while the result identities represent new transferee issuances (lines 92-100); the transfer schema also calls results new securities (Transfer schema, lines 12-24). This supports keeping balance and result IDs disjoint.
• Supported as graph integrity, though not expressible in JSON Schema: one successor issuance cannot have two different producing lifecycle transactions without making the immutable event trail ambiguous. The same reasoning supports acyclicity. These are appropriate contract-level cross-object checks.
• Questionable / stronger than the official text: global security_id uniqueness across different issuance families. OCF says every issuance has a security_id used by later typed transactions (lines 21-32), but it does not explicitly declare one cross-family namespace. Keep this only as an intentional Fairmint policy, or narrow uniqueness to each issuance family. Current data has zero collisions, so either decision is data-neutral today.

Data impact

• Production: 1,621 relevant objects across 66 sync-enabled portals; 0 findings for all current rules.
• Development: 2,477 relevant objects across 178 portals; findings in 9 portals.
  • Vortex Systems (b83c52b6-3018-490b-8e8e-bb33b7d9e864): two self-successor cancellations. tx-equity-compensation-cancellation_59b4d3ce6ba2 has a deterministic 75,000-unit successor repair; tx-equity-compensation-cancellation_f8fd9a725e1e conflicts with another same-day cancellation and needs a duplicate-vs-chained-reduction decision.
  • Seven Protelicious/Proteclicious fixture portals: 44 successor IDs are claimed by multiple exercises. This needs a fixture/product decision: materialize distinct results or disable obsolete fixtures.
  • Quine (40f53d6d-b26b-4c14-8279-17071379a928): exercises 3e49230e-e071-43b0-9432-e45c391828a6 and 3e49230e-e071-43b0-9432-e45c391828a8 both claim result bc46950a-cd22-4e1d-a219-7d4964bdb96a; business/source review must decide whether one exercise is duplicate or a second issuance is missing.

Recommendation

Needs policy confirmation plus business/fixture input; not an early merge candidate. Keep the structural successor rules, decide whether cross-family uniqueness is intentional, resolve the ambiguous Vortex/Quine and fixture lineage, then run exact-head dev and production replays. No database change is proposed by this audit.