Enforce OCF reference integrity

[HardlyDifficult]

Summary

Standalone OCF reference-integrity enforcement on main. This supersedes the narrower reference PRs #251, #255, and #256.

UpdateCapTable validates references against the batch's final state after deletes, edits, issuer edits, and creates, including:

• document related_objects, including issuer and plan-security aliases
• stock-class, stock-plan, valuation, legend, stakeholder, and vesting references
• convertible, warrant, and stock-class conversion targets and trigger references
• lifecycle source, balance, resulting-security, and split references configured for each OCF transaction
• VestingStart/VestingEvent condition IDs and trigger compatibility

Same-batch creation or repair remains supported. Lifecycle validation is deliberately limited to final-state existence and the correct issuance family: transfers remain within their family, while convertible conversions and warrant/equity-compensation exercises or releases resolve to stock issuances. It does not enforce quantities, amounts, dates, event ordering, or economic continuity.

This branch intentionally excludes the predecessor authorized-share, pool-ceiling, quantity-balance, and successor-continuity validators.

OCF basis

The referenced fields are defined by the pinned OCF schemas at commit dd84bdb6bafb63681c77166f315cea5a2078a4c8, including Document.related_objects, StockIssuance references, EquityCompensationIssuance references, and the lifecycle primitives under schema/primitives/objects/transactions.

Standalone state

• Base: main
• Exact head: 63736cac1530b1d643939b52d2c84194a76cafee
• Mutable DAR candidate: OpenCapTable-v34 0.0.3 only
• Diff: 51 files; reference validators, focused tests/fixtures, and the single refreshed candidate DAR

Local validation

• npm run build ✅
• npm run check:dar-version-policy -- --base origin/main ✅
• npm run verify-dars ✅
• git diff --check ✅
• npm test could not start locally because this Mac has no Java runtime; CI rerun and database replays remain pending.

[HardlyDifficult]

@copilot review exact head f4788cc61d34949a2d597df77aade295161afa39

[Copilot]

Pull request overview

Copilot reviewed 53 out of 54 changed files in this pull request and generated 1 comment.

[HardlyDifficult]

@codex review current head 88ae4aa82427f3f1359d497434fa333420912111

[HardlyDifficult]

cursor review current head 88ae4aa82427f3f1359d497434fa333420912111

[HardlyDifficult]

@coderabbitai resume

@coderabbitai review current head 88ae4aa82427f3f1359d497434fa333420912111

[coderabbitai]

@HardlyDifficult Resuming automatic reviews and kicking off a review of the current head 88ae4aa8.

✅ Action performed

Reviews resumed.

---

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 88ae4aa. Configure here.}

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 88ae4aa824

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

Exact head 88ae4aa82427f3f1359d497434fa333420912111 has green CI, a clean merge state, and all 26 review threads resolved. This revision addresses the prior Copilot finding, so the mandatory exact-head gate needs a fresh response. @copilot review

[Copilot]

Exact head 88ae4aa82427f3f1359d497434fa333420912111 has green CI, a clean merge state, and all 26 review threads resolved. This revision addresses the prior Copilot finding, so the mandatory exact-h...

Reviewed exact head 88ae4aa82427f3f1359d497434fa333420912111. I don’t see any new high-confidence correctness issues to address.

[HardlyDifficult]

Preliminary OCF validation-policy audit

Policy: OCF Validation Policy

Important correction from the current audit: internal-reference validity is part of the OCF data model even though the official JSON Schema validator does not currently check it.

Appears supported

• Stakeholder, stock-class, stock-legend, stock-plan, vesting-terms, valuation, conversion-target, lifecycle-security, document-object, and vesting-condition references when the official OCF sources define those relationships.
• In particular, every non-empty StockIssuance.stock_legend_ids entry should resolve to a STOCK_LEGEND_TEMPLATE. An empty array remains valid.
• Final-state validation after edits/deletes is appropriate when otherwise the package would retain a dangling documented reference.

Needs verification

• Confirm every target-type or membership restriction is exactly the relationship OCF documents; do not add a stronger relationship merely because an ID field exists.
• Tests should distinguish schema validation from complete-package reference validation and must not fabricate placeholder legal text.

Proposed next step
Audit the checks one reference family at a time. This PR should not be closed merely because these relationships are not expressible in JSON Schema.

[HardlyDifficult]

Standalone exact-head data audit (read-only)

Exact head ab1fa4f2553495753566cf920d6bf95353c5f24b is standalone on main, merge-clean, and CI-green. I audited its normalized reference rules against both databases in repeatable-read, read-only transactions; no data was changed.

Production: 86 invalid references across 3 portals:

1. DLC-Link 527587bf-b411-4d08-8927-ec9337f722a9: cancellation 181b8026-6ea2-49e6-8bcc-1a5d58c34fcc references missing equity security stk_a4bff9f1. Not deterministic; source grant/history is needed.
2. mezzanine.xyz 2280ef88-ea8d-4fe3-9e97-5d36e9694f66: 25 convertible issuances target missing stock class 79013c7a-9a3e-4b5d-9b3b-85d820468352; example 038ab0c1-9b0c-1d2e-3f4a-5b6c7d8e9f0b.
3. Protelicious d5cffdf6-790c-477b-bce9-67831e5d834e: 60 convertible issuances target missing class 1d43da9b-c30f-4a22-a80b-570beddcbabb; example 155c0c9c-7ae9-4175-8402-1c377521115e.

The intended legal target class for the 85 convertibles cannot be inferred from OCF alone. No other production reference category failed.

Development: 383 invalid references across 20 portals:

• convertible target stock class: 361 / 7 portals
• vesting relative condition: 4 / 2
• equity stock plan: 3 / 2
• stock plan class: 3 / 3
• equity exercise result security: 2 / 2
• equity vesting terms: 2 / 1
• stock legend: 2 / 1
• one each: conversion trigger, equity class, equity plan membership, stock vesting terms, vesting transaction condition, warrant conversion target

Representative issues requiring source/business input include missing exercise results bd1f064f-39fd-455f-9692-c9a0e902aa6d and 49b40b14-8f2f-4cda-8aa1-36fb7a80180a; missing legends cf133171-7d6d-4733-902e-66676ccf157d and 6e605c48-33cc-4d97-996a-16073098001c; and the two known dangling vesting-start terms 5f79f615-ecb1-4dac-a403-04dc98343e52 and 3583e335-c1f9-4412-9ce0-58fd196b29fd.

Three development corrections have strong lossless evidence:

• portal 2de06405-76b0-4129-aaf5-2509a56313e8: warrant tx-warrant-issuance_7bb77a24bca4 target alias common_stock -> sole class stock-class_e9b2c825a67d (Common Stock).
• portal 683d572d-d1aa-4145-b0ff-d8644cb6213d: vesting start tx-vesting-start_c36529339470, immediate_vesting -> source terms' sole start condition imm_es12.
• portal 709ce92b-2d4b-44d5-a240-20aae0e7db4: plan 39117b24-6421-46f8-9d53-887d529c3946 missing class -> sole class f8ae8023-f7c3-4888-ac76-e9c88c4f3bce (Common Stock), corroborated by its issuance.

Assessment: the reference rules are OCF-supported, but #268 is not an early merge candidate. It exposes substantial real reference debt in both environments, including ambiguous production legal targets. Resolve or deliberately scope those data issues before exact-head replay/merge consideration.