Enforce OCF schema field constraints by HardlyDifficult · Pull Request #269 · Fairmint/open-captable-protocol-daml

HardlyDifficult · 2026-07-09T13:04:09Z

Summary

Consolidates the schema/field-format OCF enforcement PRs into one category branch stacked on #268. Supersedes #257, #258, #259, #260, #261, #262, #263, #264, #265, #266, and #267.

Grouped requirements enforced here:

Transfer and consolidation arrays enforce schema-declared non-empty/unique cardinality. Every resulting-security array rejects duplicate successor IDs for object-identity consistency while retaining each OCF schema's empty-array behavior.
Document path / uri mutual-exclusion schema rule.
Conversion-mechanism and trigger constraints representable by the v34 model, including strict convertible/warrant variants and the v34 stock-class ratio subset.
Conversion mechanism variant constraints for share-price, valuation-based, and conversion-trigger payloads.
Currency code, phone number, and country subdivision code format constraints.
Stock issuance share-number range consistency and non-overlap checks, including final-state overlaps across issuances in the same stock class.
Optional stock cost_basis and warrant exercise_price payloads enforce the OCF Monetary amount/currency constraints on both create and edit.
Materialized non-split reissuance and consolidation results preserve the numbered certificate ranges of their source lineage.

Review feedback carried forward from superseded PRs:

#259: stock-class ratio conversion rights now reject expires_at.
#263: stock-class conversion-right validation ignores the non-OCF placeholder trigger and enforces the ratio fields representable by v34; exact structural parity requires a package-version model change.
#267: stock issuance share-number overlaps are checked across the final cap-table state, per stock class.

OCF documentation

OCF object IDs are unique
Transfer resulting security IDs
Consolidation security IDs
Exercise resulting security IDs
Release resulting security IDs
Reissuance resulting security IDs
Conversion resulting security IDs
Document path/URI shape
Stock class conversion rights
Convertible conversion rights
Warrant conversion rights
Conversion trigger variants
Share-price-based conversion mechanism
Valuation-based conversion mechanism
Currency code
Phone number
Country subdivision code
Stock issuance share numbers
Stock issuance cost_basis is Monetary
Warrant exercise_price is Monetary
Monetary requires amount and ISO currency fields
Reissuance resulting security IDs and split distinction identify replacement issuances and distinguish split-driven reissuances.
Consolidation source and resulting security IDs identify the source positions and consolidated balance security.

The exercise, release, reissuance, and conversion schemas require the field but do not declare minItems or uniqueItems. This PR preserves zero-cardinality input while rejecting repeated references to the same resulting OCF object as a contract-level consistency rule.

Scope boundary

This PR strictly validates constraints representable by OpenCapTable-v34. It does not claim complete structural parity for StockClassConversionRight: the v34 record predates the current nested ratio mechanism and cannot represent required rounding_type or a targetless future-round right without changing the package model. This PR intentionally does not synthesize dummy target, trigger, or rounding values. The proper completion is a corrected next-version model plus an explicit v34-to-next-version migration.

Validation

npm run build
Focused stock/warrant issuance suite (28 behavioral scripts plus 2 setup scripts)
npm test (536 behavioral scripts plus 2 setup scripts)
npm run lint (0 errors; 2 pre-existing warnings in scripts/remove-participant-dar.ts)
npm run lint:daml
npm run format
npm run check:schema-gaps -- --ocf-schema-dir /tmp/open-cap-format-ocf-schema-check/schema
npm run verify-dars
npm run verify-package
npm run check-upgrade-compat (0.0.10 -> 0.0.11)
git diff --check
OpenCapTable-v34-0.0.11.dar: SHA-256 23fc9940acf68156ce2594da14b0783ce38c9195d9aaf15e113fb5124f05d8ee, 3,114,372 bytes

Note

High Risk
Wide validation tightening on issuance, conversion, transfers, and share-number lineage can reject previously accepted cap-table payloads; stock-class conversion is narrowed to ratio-only in v34, which is a breaking behavioral change for importers.

Overview
Bumps OpenCapTable-v34 to 0.0.11 and tightens OCF-shaped validation across cap-table templates and shared types, with a large DAML test expansion.

Arrays and documents: Transfer/consolidation paths use shared non-empty + unique string-array helpers; other transaction types still allow empty resulting_security_ids but reject duplicates. Documents must have exactly one of path or uri, not both or neither.

Formats: ISO currency (3 uppercase letters), phone (space-separated parts with optional ext./extension), and country subdivision codes are validated centrally; issuer and address fields use the shared rules.

Conversion: Shared trigger variant rules (validateOcfConversionTriggerFields) gate which optional date/condition fields are allowed. Convertible mechanisms no longer accept PPS/valuation/ratio variants OCF disallows; warrant valuation uses CAP/FIXED/ACTUAL; share-price and valuation-based discount rules are stricter. Stock-class conversion rights in v34 are limited to ratio mechanics with required conversion_price and no extra mechanism fields; non-ratio stock-class rights fail validation.

Stock issuance: Optional cost_basis and warrant exercise_price go through Monetary validation. Share number ranges must sum to quantity, not overlap on the issuance, and cap-table logic (tests) enforces per-class final-state overlap and lineage rules on transfers, reissuance, and consolidation.

Packaging: New 0.0.7–0.0.11 DAR artifacts and lockfile entries; tests depend on 0.0.11.

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

…nto codex/ocf-stock-plan-pool-ceiling-v2 # Conflicts: # scripts/codegen/templates/CapTable.daml.template

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

Also reject expires_at on ratio stock-class conversion rights and refresh fixtures for the stricter validator.

HardlyDifficult · 2026-07-11T06:10:06Z

@copilot review

Retrying the mandatory review gate for exact head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5; the prior request has not received a response. Please focus on mixed numbered/unnumbered consolidation lineage, empty stock-reissuance lifecycle rejection, and partial numbered-stock balance successors. CI is green, the branch is merge-clean, and the thread-aware sweep is clear.

Copilot · 2026-07-11T06:10:50Z

@copilot review

Retrying the mandatory review gate for exact head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5; the prior request has not received a response. Please focus on mixed numbered/unnumbered ...

Reviewed exact head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5 in the requested areas (mixed numbered/unnumbered consolidation lineage, empty stock-reissuance lifecycle rejection, and partial numbered-stock balance successors). I don’t see any additional blocking issues to address.

HardlyDifficult · 2026-07-11T06:20:49Z

@codex review current head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5

@coderabbitai resume
@coderabbitai review current head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5

cursor review current head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5

Copilot completed its exact-head review with no blocking findings. Please review the grouped OCF field-shape constraints and numbered-security lineage behavior on this same revision.

coderabbitai · 2026-07-11T06:21:05Z

@HardlyDifficult I'll resume automatic reviews and review the latest changes on exact head 66c1b9bf4be98f5cca64fea5be68ee134703fbc5, focusing on the grouped OCF field-shape constraints and numbered-security lineage behavior.

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

chatgpt-codex-connector · 2026-07-11T06:28:28Z

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 66c1b9bf4b

ℹ️ 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-11T06:58:18Z

@cursor review Please review exact head 66c1b9b, focusing on schema cardinality, unique identifiers, and transaction-array constraints. Copilot, Codex, and CodeRabbit have completed exact-head reviews; CI is green and review threads are clear.

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 66c1b9b. Configure here.}

HardlyDifficult · 2026-07-11T14:49:25Z

Added the remaining direct optional Monetary enforcement in e9c512bf0ab2c5772450856ccf0864938973a706:

StockIssuance.cost_basis now runs validateOcfMonetary when present.
WarrantIssuance.exercise_price now runs validateOcfMonetary when present.
Contract-level regressions reject invalid currency on create and negative amount on edit for both fields.

OCF basis:

Validation is green locally: build, focused 28 behavioral + 2 setup scripts, full 536 behavioral + 2 setup scripts, codegen/package verification, format, ESLint (0 errors; 2 pre-existing warnings), DAML lint, 55/55 schema-gap check, 11 DARs, and 0.0.10 -> 0.0.11 upgrade compatibility. DAR SHA-256: 23fc9940acf68156ce2594da14b0783ce38c9195d9aaf15e113fb5124f05d8ee.

The PR is back in draft pending exact-head CI. Downstream stack heads will be restacked only after this base is green.

HardlyDifficult · 2026-07-11T14:53:25Z

@copilot review exact head e9c512bf0ab2c5772450856ccf0864938973a706.

Please review the optional Monetary enforcement for stock cost_basis and warrant exercise_price, including create/edit contract regressions. Exact-head CI is green, the branch is merge-clean, all 538 scripts pass locally, and the thread-aware sweep has zero unresolved threads.

Copilot · 2026-07-11T14:54:37Z

@copilot review exact head e9c512bf0ab2c5772450856ccf0864938973a706.

Please review the optional Monetary enforcement for stock cost_basis and warrant exercise_price, including create/edit con...

Reviewed exact head e9c512bf0ab2c5772450856ccf0864938973a706 with focus on optional Monetary enforcement for StockIssuance.cost_basis and WarrantIssuance.exercise_price, including create/edit regression coverage. I don’t see any additional blocking issues to address.

HardlyDifficult · 2026-07-11T14:57:06Z

@codex review exact head e9c512bf0ab2c5772450856ccf0864938973a706.

Copilot has completed this exact revision with no blocking findings. Please review the optional Monetary enforcement and create/edit regressions.

HardlyDifficult · 2026-07-11T14:57:07Z

@cursor review exact head e9c512bf0ab2c5772450856ccf0864938973a706.

Copilot has completed this exact revision with no blocking findings. Please review the optional Monetary enforcement and create/edit regressions.

HardlyDifficult · 2026-07-11T14:57:07Z

@coderabbitai review

Please perform the required substantive review of exact head e9c512bf0ab2c5772450856ccf0864938973a706. Copilot has completed this exact revision with no blocking findings; CI is green, the branch is merge-clean, and zero review threads are unresolved.

coderabbitai · 2026-07-11T14:57:21Z

@HardlyDifficult I'll review the latest changes on exact head e9c512bf0ab2c5772450856ccf0864938973a706, focusing on the optional Monetary enforcement for StockIssuance.cost_basis and WarrantIssuance.exercise_price, and the associated create/edit contract regressions.

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

HardlyDifficult · 2026-07-11T14:57:37Z

@coderabbitai Please explicitly confirm whether your completed review of exact head e9c512bf0ab2c5772450856ccf0864938973a706 found any actionable issues. No new review is requested.

coderabbitai · 2026-07-11T14:57:50Z

Tip

For best results, initiate chat on the files or code changes.

@HardlyDifficult Confirmed — the completed review of exact head e9c512bf0ab2c5772450856ccf0864938973a706 did not surface any actionable issues (no line comments were posted). As noted, CodeRabbit is an incremental review system, so that pass covered only the diff introduced up to that commit relative to the last reviewed state; no new review was triggered per your request.

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

chatgpt-codex-connector · 2026-07-11T15:00:56Z

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: e9c512bf0a

ℹ️ 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-14T14:04:49Z

Preliminary OCF validation-policy audit

Policy: OCF Validation Policy

Appears supported

Formal schema rules: formats, conditional variants, document path/URI exclusivity, and array minItems/uniqueItems where OCF declares them.
Conversion-mechanism shapes and monetary/phone/currency/subdivision validation that directly implement official schemas.
Semantic share-number integrity where the OCF model explicitly treats share numbers as unique identifiers for non-fungible shares.

Needs line-by-line evidence or narrowing

Duplicate-result rejection for arrays whose schema omits uniqueItems, unless OCF semantics independently require uniqueness.
Exact share-number quantity equality, cross-issuance overlap windows, and successor-range reconstruction where the algorithm goes beyond documented share-number semantics.
Result cardinality or lineage constraints not declared by schema or documentation.

Proposed next step
Separate schema-parity rules from second-order share-number/lifecycle rules, then review the latter individually. No merge recommendation yet.

HardlyDifficult and others added 30 commits July 8, 2026 21:03

Enforce stock plan reserved share ceilings

87737fa

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

852f2b0

…nto codex/ocf-stock-plan-pool-ceiling-v2 # Conflicts: # scripts/codegen/templates/CapTable.daml.template

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

b7debe1

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

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

4cb7f2c

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

Restack stock plan ceiling on reference integrity

283256c

Restack stock plan ceiling on indexed share ceilings

7c3ed35

Optimize stock plan pool ceiling validation indexes

ecd2422

Refine map aggregation helpers for stock plan checks

73ad3fc

Simplify stock plan net allocation map merging

5fa7204

Polish stock plan allocation variable naming

9fb27ae

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

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

Enforce PPS discount oneOf

633c147

Enforce valuation conversion oneOf

440b3ac

Merge reference integrity base into stock plan ceiling

c21a636

Merge stock plan ceiling base into unique security arrays

6fd314b

Merge unique security arrays base into document location oneOf

fb77a30

Merge document oneOf base into stock class ratio conversion rights

721947f

Also reject expires_at on ratio stock-class conversion rights and refresh fixtures for the stricter validator.

Merge stock class ratio base into convertible mechanism domain

6b530f6

Merge convertible mechanism base into PPS discount oneOf

e9a90b5

Merge PPS discount base into valuation oneOf

7956e47

Enforce conversion trigger variant fields

a48f2e0

Enforce currency code pattern

d45f3a1

Copilot started work on behalf of HardlyDifficult July 11, 2026 06:10 View session

Copilot finished work on behalf of HardlyDifficult July 11, 2026 06:11

cursor Bot reviewed Jul 11, 2026

View reviewed changes

HardlyDifficult self-assigned this Jul 11, 2026

HardlyDifficult marked this pull request as draft July 11, 2026 14:40

HardlyDifficult removed their assignment Jul 11, 2026

fix: validate optional monetary issuance fields

e9c512b

HardlyDifficult marked this pull request as ready for review July 11, 2026 14:53

Copilot started work on behalf of HardlyDifficult July 11, 2026 14:53 View session

Copilot finished work on behalf of HardlyDifficult July 11, 2026 14:55

cursor Bot reviewed Jul 11, 2026

View reviewed changes

HardlyDifficult self-assigned this Jul 11, 2026

HardlyDifficult marked this pull request as draft July 13, 2026 19:06

Uh oh!

Conversation

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

Uh oh!

Summary

OCF documentation

Scope boundary

Validation

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

Copilot AI commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

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

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

Copilot AI commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

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

Uh oh!

Uh oh!

HardlyDifficult commented Jul 11, 2026

Uh oh!

coderabbitai Bot commented Jul 11, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot commented Jul 11, 2026

Uh oh!

HardlyDifficult commented Jul 14, 2026

Preliminary OCF validation-policy audit

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HardlyDifficult commented Jul 9, 2026 •

edited by cursor Bot

Loading

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading

HardlyDifficult commented Jul 11, 2026 •

edited

Loading

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading