Skip to content

Status: implemented

Implemented — this change has shipped.

RFC 0062: Permit same-day cash-flow rows while refusing ambiguous selectors ​

Summary ​

Separate document validity from selector uniqueness for the existing cash_flow_series.series registry entry. Legal same-day rows remain separate and do not emit PS-02; an ordinary date selector refuses CALC-PERIOD-002 when its requested date matches multiple rows, while a unique date in the same series resolves normally. The four other registered series keep their existing duplicate rules.

This is an accepted normative reconciliation, not an implementation bug fix. Implemented; released in core/CLI 2.14.0 as Protocol 2.17.1 — normative errata (shipped within Protocol 2.18.0). No schema or public type changes. See Resolution.

The accepted contract is: legal, separate same-day cash-flow rows without PS-02; deterministic refusal of selectors matching multiple rows; selectable unique dates; unchanged duplicate-period protection for other registered series; and no numeric row-index syntax or other calc-grammar expansion.

Motivation ​

The released requirements conflict:

  • Format §4.26, CF-02 permits equal dates, forbids merging same-day rows and retains row identity. RFC 0034 supplies the dated verifier; Protocol §VIII.9 operates on these source rows.
  • Protocol §VIII.2a registers this same series but requires a PS-02 error for every duplicate canonical identity. Its resolver also refuses any duplicate identity in the entire selected series before looking up the requested date. RFC 0041 records those requirements.
  • RFC 0044 / Protocol §VIII.9.5 preserves same-day projected rows and says date selectors retain duplicate-date ambiguity. RFC 0045 / §VIII.9.6 retains separate property cash components and source-index bindings.

A private validation corpus demonstrated the interaction. No private data is needed to reproduce it: conformance/property-cash-flow-assembly/valid-same-day assembles successfully but its source document emits three PS-02 errors. conformance/cash-flow/verify-same-day-flows/case.json verifies successfully; wrapping its identical payload in a document emits PS-02.

Against the latter payload at commit 17749ed, both the repeated 2026-03-17 selector and the unique 2031-03-17 selector refuse CALC-PERIOD-002. The second result proves that merely suppressing validation is insufficient. The accepted reconciliation changes the whole-series refusal scope for ordinary cash-flow selection as well as the document verdict.

Proposed change ​

Document validity ​

For cash_flow_series.series, multiple rows MAY have the same valid ISO date. They MUST remain distinct. An implementation MUST NOT merge, net, reorder or collapse rows merely because dates are equal. Equal dates alone MUST NOT produce PS-02. Existing CF-01, CF-02 and CF-03 requirements remain in force, including finite amounts, valid calendar dates and non-decreasing ordering. PS-01 still reports malformed registered period data; PS-03 is unchanged.

Ordinary date selection ​

A selector cash_flow_series.series@<date>.<leaf> MUST inspect the source series and require a unique row at the requested canonical date. Two or more matching rows MUST refuse with the existing CALC-PERIOD-002. It MUST NOT choose first or last, sum rows, or infer intent from kind, label, amount or position. A unique requested date MUST resolve even when other dates repeat. Absent dates, absent/null sections or series, and incompatible selector kinds retain the existing null behavior; malformed source periods still refuse. Section/variant selection, full-path overrides, safe traversal and scalar quantization remain unchanged.

The exception MUST NOT relax document or selector duplicate rules for dcf.annual_cash_flows, noi_model.projections, lease_up_schedule.schedule or distribution_waterfall.stated_schedule. For those series, any duplicate canonical identity still invalidates the whole series for selection, including selection of a different unique period.

Rows remain individually addressable only through existing legitimate identity-preserving surfaces, such as declared cash-flow metric row bindings and RFC 0045 source-index mappings. No numeric-index calc grammar is added.

Whole-column Excel boundary ​

resolvePeriodColumn currently projects a complete identity-keyed column for RFC 0043 contextual bindings. It MUST continue to refuse duplicate identities rather than silently dropping same-day rows from its map. This RFC does not authorize a duplicate-key workbook binding or change §VIII.2c's whole-column validity guard. Unique scalar lookup and acceptance of a whole workbook column are distinct contracts. Ordinary selector tests must not be used to claim a new Excel export capability. Full-series duplicates remain visible to the scan.

Compatibility analysis ​

No source data shape changes. Existing valid unique-date documents lose no capability. Format-legal same-day ledgers gain a consistent document verdict and unique-date scalar lookup; repeated-date lookup still refuses. Readers and validators adopting the reconciled protocol must stop emitting the cash-flow-only PS-02 error. Editors retain byte/order preservation. Calc hosts must narrow only this series' ordinary selector refusal scope. Agent hosts inherit the lower-tier requirements. Module manifest shapes and other period series are unchanged. As with an explicit protocol pin, a module requiring exactly 2.17.0 must opt into 2.17.1 (or an appropriate compatible range); the default supported-version list now names the errata version rather than advertising both contradictory contracts.

This changes required observable behavior of released implementations. Conformance to the old contradictory rules is not silently relabeled: version treatment must be settled before adoption. Absent cash-flow sections and legacy unique-date sections behave unchanged. No migrations, inferred dates, new financial formulas, defaults or tolerance changes are introduced.

Version treatment selected by the UWMD maintainers ​

Protocol §0.3 requires a bump for any normative required-behavior change. conformance/README.md, “Regenerating expected outputs,” requires a protocol bump when expected normative output changes. Released Protocol 2.17.0 pairs with core/CLI 2.13.0. The repository's minor-version rule says requirements strengthen monotonically, yet the old rule requires an error that this reconciliation forbids; that rule does not mechanically settle the bump.

RFC 0061 was editorial (labels only); core 2.6.1 restored an existing required behavior without changing the protocol; RFC 0036 introduced normative behavior with a protocol minor. None determined this released contradiction. The CHANGELOG's older “Versioning” anchor referenced by VERSIONS does not currently exist. The version treatment was therefore an accepted decision rather than an inferred policy.

The maintainers chose Protocol 2.17.1 as normative errata, rather than 2.18.0 as a normative feature change. This explicitly acknowledges both the changed PS-02 verdict and unique-date resolver behavior; it does not claim byte-identical results or automatic compatibility with both contradictory old requirements. This is a narrow errata precedent, not blanket authority to put new protocol features into patches.

The executable constant, checked protocol labels, current source matrix and receipt-issuance protocol labels move together to 2.17.1. Format remains 2.0.

Conformance impact ​

Add a minimal public full-document scenario under conformance/cash-flow/ using synthetic rows with one repeated date and one unique date. Pin together:

  1. Parsing and full validation: no errors and no CF/PS diagnostics for legal data; compare source rows before/after to prove no merging or reordering.
  2. Cash-flow verification of the same preserved rows.
  3. The repeated-date selector returns CALC-PERIOD-002.
  4. The unique-date selector returns its stated amount in that same document.
  5. An absent date remains null.

Extend the existing full-document cash-flow runner narrowly to execute optional selector expectations and row-preservation expectations on that same parsed document. Add a negative-control scenario for another registered series that still emits PS-02 and refuses CALC-PERIOD-002, including selection of a different unique period. Preserve the existing tier-3-calc-host/fixtures/period-07-duplicate result.

Strengthen the existing public RFC 0045 same-day case to check the absence of PS-02 while retaining its existing assembled row/binding expectations. The unrelated LU-04/CC-14 warnings in that source fixture are not suppressed. No private workbook data enters conformance.

Portable-driver coverage (added 2026-10-02, after acceptance). The scenarios above run in the TypeScript suite only. Tier-3 fixtures period-09-same-day-unique, period-10-same-day-repeated, period-11-same-day-absent and period-12-other-series-duplicate carry the selection rule into the RFC 0004 driver, so a non-TypeScript calc host cannot self-certify while refusing every same-day series. They add tests only; this RFC's contract is unchanged.

Reference implementation ​

The public PeriodSeriesEntry type and its closed JSON Schema already describe the five frozen series. The cash-flow payload schema explicitly permits same-day rows; no schema change is needed.

The reference implementation checks the existing registered path narrowly in period-validation.ts and period-path.ts, with comments referencing this RFC. A registry policy field would change an exported type and schema to model one known exception; it is unnecessary here. Do not create another registry.

  • scanPeriodSeries keeps reporting all duplicate canonical identities.
  • Document validation omits only cash-flow duplicate-date PS-02 diagnostics.
  • resolvePeriodReference checks the requested identity for cash-flow duplicates; all other series retain whole-series refusal.
  • resolvePeriodColumn retains its whole-column refusal.
  • protocol.ts remediation copy describes the narrowed PS-02 scope.
  • No new public type, function, enum, error code or schema field is needed.

Updated Protocol §VIII.2a's selection and validation paragraphs and clarified the existing Format §4.26 row-addressability statement with a reference to unique date selection. The executable validation-code description, period-addressing wiki and living status are updated together. Historical RFC 0034/0041 release statements are preserved and link this reconciliation, released in 2.14.0.

Focused tests must cover scanner duplicate reporting, every active variant, malformed-date/CF retention, repeated versus unique selectors, missing and kind-mismatched selectors, all four unaffected registry entries, overrides, source non-mutation, exact row order and whole-column refusal. Build and run focused tests before the full repository gates and independent new-fixture execution. Existing financial algorithms, tolerances and Excel formulas do not change.

Alternatives considered ​

  1. Merge/net same-day rows: destroys component identity, provenance and reserve/acquisition distinctions; explicitly violates CF-02.
  2. Make same-day rows globally invalid: contradicts RFC 0034 and legal acquisition/draw/assembly consumers.
  3. Choose a row by array order: silently invents selector intent; row reordering would change the selected financial fact.
  4. Add row-index calc syntax: outside RFC 0041's grammar and this task. Existing source-index binding surfaces do not authorize numeric indexing in arbitrary calc expressions.
  5. Relax duplicates for every registered series: there is no evidence or normative authorization for other series; repeated NOI years, lease periods and waterfall statement dates remain protected.
  6. Only suppress PS-02: leaves unique cash-flow dates unselectable whenever another date repeats; does not meet the accepted selector contract.
  7. Discard duplicate rows in the scanner: makes first-match lookup appear unique and breaks whole-column safety. Preserve duplicate observations.

Unresolved questions ​

None for this reconciliation. The UWMD maintainers accepted the normative resolution, and the 2.17.1 errata version is settled. Terminal settlement, reserve rollforward, levered assembly and any other protocol feature are excluded.

Resolution ​

  • Status. Accepted 2026-09-24; implemented and released 2026-10-02 in core/CLI 2.14.0. The errata are Protocol 2.17.1 (see Version treatment selected by the UWMD maintainers), shipped within Protocol 2.18.0 together with RFC 0063. Format remains 2.0. No schema or public type changed.
  • Decided. The contract under Proposed change, as summarized in Summary.
  • Implementing PRs. The 2.14.0 package generation merged in #218; the portable-driver tier-3 cases (see Conformance impact) landed in #235.
  • Verification. The new period tests failed against the old behavior and pass after reconciliation. The DCF negative control retains PS-02 and both duplicate/unique selector refusals. No schema or financial math changed.

Prior art ​

RFC 0034 defines a ledger of individual flows; RFC 0041 defines identity-based selection; RFCs 0044/0045 preserve same-day projection/assembly rows. RFC 0043's guarded whole-column Excel binding remains a separate consumer. These existing repository contracts supply the required semantics without a new date primitive or error family.

Released under the MIT License.