Enforce security quantity balance invariants by HardlyDifficult · Pull Request #253 · Fairmint/open-captable-protocol-daml

HardlyDifficult · 2026-07-09T02:37:28Z

Summary

Enforce source-security lifecycle invariants on current main: known issuance quantities cannot be reduced below zero, terminal events retire their source, and lifecycle events cannot predate issuance.

Covered reductions:

stock cancellations, repurchases, transfers, conversions, reissuances, consolidations, and retractions
warrant cancellations, transfers, exercises, and retractions; unknown issuance quantities still preserve terminal-event semantics
equity-compensation cancellations, transfers, exercises, releases, and retractions

Direct stock-class splits are applied chronologically to stock issuances and equity-compensation issuances with an explicit stock_class_id. Because OCF records calendar dates without intra-day ordering, same-day events use the lowest-balance valid ordering: a same-day reverse split is included when it may reduce the issuance balance, while a same-day forward split is excluded when the issuance may already be post-split.

Deliberate exclusions

This PR does not validate successor identity, balance_security_id materialization, resulting-security continuity, predecessor graphs, terminal completeness, or inferred stock-plan class lineage. Those remain separate rules.

Warrant issuances with no quantity cannot be numerically balance-checked. A warrant exercise with omitted quantity is treated as a full retirement of the source security.

Version and branch

Base: main, including merged Enforce conversion-ratio adjustment references #280
Exact head: bec4cfd5f85059c099acb579d6b58aba7f9896bb
Contract package: OpenCapTable-v34 0.0.3
The single undeployed mutable 0.0.3 DAR and lock entry were rebuilt from the combined source.

Validation

multi-package DAML build: passed
full DAML script suite: passed, including same-day and later-date split regressions
DAML lint: no hints
DAR integrity and version policy: passed
ESLint: 0 errors, 2 pre-existing warnings
Prettier: passed
git diff --check: passed
read-only same-day issuance/split audit: 0 matches in dev, 0 matches in production
exact-head dev replay: passed (run); every source object passed strict OCF schema validation and the cap table converged on LocalNet
exact-head production replay: baseline-equivalent failure (run); failure phases are unchanged from current main: batch, conversion, and schema

Dev data correction

Four old Protelicious equity-compensation issuances recorded quantity: "4" while their vestings totaled 7.9998 and their sole exercise consumed 8. With approval, dev-only version 3 rows were appended changing only quantity to "8"; version 2 remains preserved. Independent read-only verification passed, and the definitive exact-head dev replay subsequently converged without any failure.

Exact-head replay artifacts (2026-07-23)

Contract SHA: bec4cfd5f85059c099acb579d6b58aba7f9896bb
Dev: passed with zero failure phases; every source object passed strict OCF schema validation and converged; replay duration 12m32s
Production: failed in the same batch, conversion, and schema phases as the current-main baseline; replay duration 4m48s
Traffic: dev 8.244 MB / $137.43 equivalent; production 3.663 MB / $61.07 equivalent
Review: exact-head CI, DAR integrity, Copilot, Codex, and Cursor are clean; no unresolved review threads

Note

High Risk
Changes core cap-table acceptance logic for all stock, warrant, and equity-comp lifecycle batches; incorrect split or retirement ordering could reject valid production data or miss invalid states.

Overview
Adds post-batch validation on UpdateCapTable so a known issuance quantity cannot be driven below zero by recorded lifecycle events on that security_id.

The contract introduces SecurityBalanceEvent (reductions, retirements, class splits as multipliers), aggregates events for stock, warrant, and equity compensation issuances, and runs validateSourceSecurityBalances after each batch. It rejects cumulative overdraws, pre-issuance reductions, further reductions after retraction / reissuance / consolidation / full warrant exercise, and ambiguous same-day split vs reduction ordering (OCF has calendar dates only). Splits on a later date scale balances; same-day forward splits on issuance are not assumed to inflate pre-recorded quantities.

DAML script coverage is expanded across cancellations, transfers, exercises, releases, repurchases, conversions, and split edge cases, with small test-helper tweaks (e.g. configurable EC grant size). OpenCapTable-v34 0.0.3 DAR and lock metadata are updated to ship the new rules.

^{Reviewed by Cursor Bugbot for commit bec4cfd. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

Bug Fixes
- Added balance validation for stock, warrant, and equity compensation transactions.
- Prevented overdraws across cancellations, exercises, transfers, releases, repurchases, conversions, and reductions.
- Ensured retracted, consolidated, reissued, or fully exercised source balances cannot be reduced.
- Improved handling of stock splits, reverse splits, and ambiguous same-day events.
Tests
- Expanded coverage for cumulative overdraws, split ordering, source-balance retirement, and balance edits.

coderabbitai · 2026-07-09T02:37:38Z

📝 Walkthrough

Walkthrough

Adds event-based validation for stock, warrant, and equity-compensation source balances, including dated stock splits. UpdateCapTable invokes the validation, and Daml tests cover overdraws, split ordering, and retired source balances.

Changes

Security Balance Validation

Layer / File(s)	Summary
Security balance events and indexes `scripts/codegen/templates/CapTable.daml.template`	Defines reduction, retirement, and split events; applies deterministic ordering and builds indexes from balance-changing OCF objects.
Issuance validation and update wiring `scripts/codegen/templates/CapTable.daml.template`, `dars/OpenCapTable-v34/0.0.3/OpenCapTable-v34.dar`	Validates issuance quantities against applicable events and invokes validation from `UpdateCapTable`; updates the DAR LFS pointer.
Overdraw, split, and source-retirement regression coverage `Test/daml/OpenCapTable/*`	Adds tests across stock, warrants, and equity compensation for cumulative reductions, overdrawn operations, split timing, edits, and retired sources.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UpdateCapTable
  participant CapTableMaps
  participant EventIndexes
  participant SourceBalanceValidator
  UpdateCapTable->>CapTableMaps: build final maps
  UpdateCapTable->>EventIndexes: build balance and split indexes
  EventIndexes-->>SourceBalanceValidator: provide ordered events
  UpdateCapTable->>SourceBalanceValidator: validate issuance quantities
  SourceBalanceValidator-->>UpdateCapTable: return validation result

🚥 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 main change: enforcing balance invariants for security quantities.

✨ 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-stock-security-balance

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

HardlyDifficult · 2026-07-09T02:40:40Z

@copilot review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: de4daaf240

ℹ️ 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 · 2026-07-09T03:38:07Z

@copilot review

…nto codex/ocf-stock-plan-pool-ceiling-v2

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8c88a6f924

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

Copilot · 2026-07-23T13:37:43Z

CI is green on exact head 8c88a6f. @copilot review

Addressed in 0a5399e (with follow-up clarification in ab29855). I normalized split ordering/applicability to OCF calendar-day semantics via ocfDate and updated the same-day split regression to use a non-midnight split timestamp so differing Time components are explicitly covered.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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

…' into codex/ocf-stock-security-balance # Conflicts: # Test/daml/OpenCapTable/TestStockCancellation.daml # scripts/codegen/templates/CapTable.daml.template

HardlyDifficult · 2026-07-23T13:49:08Z

Review feedback is addressed and the full DAML suite passes on exact head 7fc55ab. @codex review

HardlyDifficult · 2026-07-23T13:51:07Z

CI is green on exact head 7fc55ab. @copilot review

Copilot

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7fc55abc25

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

Copilot · 2026-07-23T13:58:39Z

CI is green on exact head 7fc55ab. @copilot review

Reviewed exact head 7fc55abc256290ae3b5b470168b075a26c4e10ef and re-checked the requested areas. The central non-negative reduction/balance guards are in place, split ordering/applicability is normalized to OCF calendar-day semantics, and I did not find regressions in the warrant/equity balance paths from this revision. I also verified the exact-head Actions runs are green (CI run 30012708906, Check DAR Integrity run 30012708899) and pulled job logs for the CI run (daml-build job 89224654814, successful). No additional code changes are needed from this review.

HardlyDifficult · 2026-07-23T14:15:51Z

CI and DAR integrity are green on exact head 93bc1041cbce08e23b7d3c01980634232e6198a1. The latest follow-up accounts for full security retirements, quantity-less warrant exercises, same-day split ambiguity in both directions, and persisted reductions after issuance edits, with focused regressions for each. @copilot review

HardlyDifficult · 2026-07-23T14:15:52Z

@codex review

Copilot · 2026-07-23T14:18:23Z

CI and DAR integrity are green on exact head 93bc1041cbce08e23b7d3c01980634232e6198a1. The latest follow-up accounts for full security retirements, quantity-less warrant exercises, same-day split am...

Reviewed exact head 93bc1041cbce08e23b7d3c01980634232e6198a1 and re-checked the updated invariants and focused regressions. I did not find additional issues requiring code changes. I also verified Actions for this exact head are green (CI run 30014555067, Check DAR Integrity run 30014555021) and inspected CI job logs (daml-build job 89231012225, successful).

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 1 comment.

HardlyDifficult · 2026-07-23T14:22:44Z

@codex review exact head 93bc1041cbce08e23b7d3c01980634232e6198a1; CI and DAR checks are green and all prior actionable threads are resolved.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 93bc1041cb

ℹ️ 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 · 2026-07-23T14:55:05Z

Exact-head replay evidence for 93bc1041cbce08e23b7d3c01980634232e6198a1:

Dev passed: zero failure phases; every source object passed strict OCF schema validation and the resulting cap table converged on LocalNet. Replay duration: 12m16s.
Production failed only in batch, conversion, and schema—the exact same phases as the current-main baseline, so PR Enforce security quantity balance invariants #253 introduced no new failure phase. Replay duration: 4m54s.
Traffic: dev 8.264 MB ($137.76 equivalent); production 3.636 MB ($60.61 equivalent).
Exact-head CI, DAR integrity, Copilot, and Cursor are clean; all review threads are resolved. Codex was requested twice on this head but has not returned a response yet.

HardlyDifficult · 2026-07-23T15:08:02Z

CI and DAR integrity are green on exact head bec4cfd5f85059c099acb579d6b58aba7f9896bb. The four latest review findings are addressed with passing regressions for safe/unsafe same-day split ordering, same-day reverse splits at issuance, unknown-quantity warrant retirement, and pre-issuance lifecycle events. @copilot review

HardlyDifficult · 2026-07-23T15:08:03Z

@codex review exact head bec4cfd5f85059c099acb579d6b58aba7f9896bb; CI and DAR integrity are green, and all prior actionable threads are resolved.

chatgpt-codex-connector · 2026-07-23T15:12:25Z

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

Reviewed commit: bec4cfd5f8

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

Copilot

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 1 comment.

Copilot · 2026-07-23T15:16:13Z

CI and DAR integrity are green on exact head bec4cfd5f85059c099acb579d6b58aba7f9896bb. The four latest review findings are addressed with passing regressions for safe/unsafe same-day split ordering,...

Reviewed exact head bec4cfd5f85059c099acb579d6b58aba7f9896bb and re-checked the source-balance/same-day split updates; I don’t see additional issues requiring code changes. I also verified Actions on this head are green (CI run 30018786791, Check DAR Integrity run 30018786780) and checked CI logs for daml-build job 89245717810 (successful).

HardlyDifficult · 2026-07-23T15:38:19Z

Definitive exact-head replay evidence for bec4cfd5f85059c099acb579d6b58aba7f9896bb (supersedes the earlier 93bc104 evidence):

Dev passed: zero failure phases; every source object passed strict OCF schema validation and every cap table converged on LocalNet. Replay duration 12m32s; 8.244 MB traffic ($137.43 equivalent).
Production failed only in batch, conversion, and schema, exactly matching the current-main baseline. No new failure phase was introduced by this PR. Replay duration 4m48s; 3.663 MB traffic ($61.07 equivalent).
Exact-head CI, DAR integrity, Copilot, Codex, and Cursor are clean; all actionable review threads are resolved.

HardlyDifficult marked this pull request as ready for review July 9, 2026 02:40

Copilot started work on behalf of HardlyDifficult July 9, 2026 02:41 View session

Copilot finished work on behalf of HardlyDifficult July 9, 2026 02:42

chatgpt-codex-connector Bot reviewed Jul 9, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

HardlyDifficult changed the title ~~Enforce stock security balance invariants~~ Enforce security quantity balance invariants Jul 9, 2026

cursor Bot reviewed Jul 9, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Copilot started work on behalf of HardlyDifficult July 9, 2026 03:38 View session

Copilot finished work on behalf of HardlyDifficult July 9, 2026 03:39

Copilot AI and others added 2 commits July 9, 2026 03:41

Polish stock plan allocation variable naming

9fb27ae

Add authorized share same-date tie-break tests

790d5ce

HardlyDifficult mentioned this pull request Jul 9, 2026

Enforce vesting condition graph integrity #254

Merged

HardlyDifficult added 16 commits July 9, 2026 01:19

Address reference integrity review feedback

45c6352

Merge remote-tracking branch 'origin/codex/ocf-reference-integrity' i…

12e7a41

…nto codex/ocf-stock-plan-pool-ceiling-v2

Restack stock plan ceiling on reference fixes

43c394f

Allow equity compensation same-batch reference edits

37674c1

Merge remote-tracking branch 'origin/codex/ocf-reference-integrity' i…

318ce32

…nto codex/ocf-stock-plan-pool-ceiling-v2

Refresh stock plan DAR after reference restack

771f7b8

Enforce unique security arrays

e64b2f4

Enforce document location oneOf

f4b9bf2

Enforce stock class ratio conversion rights

dac0764

Enforce convertible conversion mechanism domain

1a7bb5b

Document unsupported convertible mechanisms

e7291bd

Add issuer same-date ceiling tie-break test

0820f92

Enforce PPS discount oneOf

633c147

Enforce valuation conversion oneOf

440b3ac

Enforce authorized share ceiling dates

22972de

Reuse authorized share ceiling validation inputs

2e6b4ff

Normalize split date handling to OCF day precision

0a5399e

chatgpt-codex-connector Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Clarify OCF day-precision split ordering semantics

ab29855

cursor Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template

HardlyDifficult added 3 commits July 23, 2026 09:41

Close security balance validation gaps

7764a64

Merge remote-tracking branch 'origin/codex/ocf-stock-security-balance…

52b348c

…' into codex/ocf-stock-security-balance # Conflicts: # Test/daml/OpenCapTable/TestStockCancellation.daml # scripts/codegen/templates/CapTable.daml.template

Reject ambiguous same-day split overdraws

7fc55ab

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread Test/daml/OpenCapTable/TestStockCancellation.daml

chatgpt-codex-connector Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template

Account for full security retirements

93bc104

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

chatgpt-codex-connector Bot reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Comment thread scripts/codegen/templates/CapTable.daml.template

Comment thread scripts/codegen/templates/CapTable.daml.template Outdated

Handle ambiguous security balance dates

bec4cfd

Copilot AI reviewed Jul 23, 2026

View reviewed changes

Comment thread scripts/codegen/templates/CapTable.daml.template

HardlyDifficult mentioned this pull request Jul 23, 2026

Enforce instrument temporal eligibility #278

Merged

coderabbitai Bot mentioned this pull request Aug 12, 2026

chore(deps): safe Dependabot updates (skip breaking majors) Fairmint/ocp-canton-sdk#452

Merged

1 task

Uh oh!

Conversation

HardlyDifficult commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Deliberate exclusions

Version and branch

Validation

Dev data correction

Exact-head replay artifacts (2026-07-23)

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

HardlyDifficult commented Jul 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HardlyDifficult commented Jul 9, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jul 23, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

HardlyDifficult commented Jul 23, 2026

Uh oh!

HardlyDifficult commented Jul 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Jul 23, 2026

Uh oh!

HardlyDifficult commented Jul 23, 2026

Uh oh!

HardlyDifficult commented Jul 23, 2026

Uh oh!

Copilot AI commented Jul 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

HardlyDifficult commented Jul 23, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

HardlyDifficult commented Jul 9, 2026 •

edited

Loading

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading