Skip to content

Catch up references_v3_compendium.md with everything since mid-August - #256

Merged
dk107dk merged 1 commit into
mainfrom
docs/catch-up-references-v3-compendium
Aug 20, 2026
Merged

dk107dk merged 1 commit into
mainfrom
docs/catch-up-references-v3-compendium

Conversation

@dk107dk

@dk107dk dk107dk commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator

Summary

Catches up references_v3_compendium.md (§5/§6/§7) with everything built since it was last updated, roughly mid-August. Pure documentation, no code changes.

Directly prompted by two things David asked about while reviewing the recent :manifest()-traversal-gap work: what ReferenceResult3.path actually means (it turned out to have no documented type at all -- entirely inferred from which finder/branch produced it), and where Rule 1/1a/1b are written down (Rule 1b turned out to exist only in code comments, never in any spec doc).

What's new in §5

  • ReferenceResult3's actual four fields (path/uuid/data/identity -- the existing description omitted identity entirely), plus a table of what path holds per producer, since there's no discriminator field recording that.
  • Rule 1 / Rule 1a / Rule 1b -- whole-resource content resolving to exactly one entity, and the two global-ledger exceptions.
  • _check_position() -- the enforced, declarative replacement for scattered hand-written guards, and the bug class it closed.
  • The manifest field-accessor catalog (Part A/B) -- 34 functions and :path(), the shared shape, without reproducing the exhaustive per-function table that already lives in manifest_field_functions_proposal.md.
  • :having()/:from()/:to() ranges, at both version/run and statement level.
  • ReferenceExpression3 -- UNION/SUBTRACT/INTERSECT semantics, the join-key rule, and the left-side-dedup bug caught by testing.
  • The full '*' traversal generalization -- field accessors, :having()/:flatten(), the :all() meaning-collision (resolved via a worked example), path narrowing, name_three, and pointer optionality, including the previously-latent bugs each fix surfaced and the CSVPATHS-vs-RESULTS/FILES inconsistency found and deliberately left documented rather than silently "fixed."

§6/§7

  • §6: marked the INTERSECT "later phase" note resolved; added the one traversal restriction that survived every generalization pass (:manifest() + real '*'-traversal narrowing), with the specific result.path-vs-result.uuid disambiguation problem that blocks it.
  • §7: nearly everything it tracked as unbuilt is now built -- collapsed into a pointer back to §5 rather than repeating the reasoning, and corrected the genuinely-still-true items (type-ahead, {...} interpolation evaluation, v3's still-pending production integration) where they'd gone stale.

Verification

Re-ran the suite while writing this, to state current numbers accurately rather than guess: tests/references/ 486 → 1099 passed; full suite 2066 → 2687 passed, same known 11-failure SFTP/S3/Nos baseline throughout, unrelated to references v3.

The compendium had not been updated since roughly the point
ResultsReferenceFinder3 and string interpolation shipped -- everything
built since then (a large fraction of the whole references v3 effort)
was undocumented here. This is a pure documentation update, no code
changes.

Added, in §5, in the same "settled facts, not chat narrative" voice
the rest of the document already uses:

- ReferenceResult3's actual four fields (path/uuid/data/identity --
  the existing description omitted identity entirely) and a table of
  what `path` actually holds per producer, since there is no
  discriminator field recording that.
- Rule 1 / Rule 1a / Rule 1b -- whole-resource content resolving to
  exactly one entity, and the two global-ledger exceptions. Rule 1b
  existed only in code comments before this, never in
  manifest_field_functions_proposal.md alongside Rule 1/1a.
- _check_position() -- the enforced, declarative replacement for
  scattered hand-written "is this recognized" guards, and the bug
  class it closed project-wide.
- The manifest field-accessor catalog (Part A/B) -- 34 field-accessor
  functions and :path() (Rule 2/3), the shared SOURCE/KEY/POSITIONS
  shape, without reproducing the exhaustive per-function table that
  already lives in the proposal doc.
- :having() and :from()/:to() ranges, at both version/run level
  (two modes: index and date) and statement level (index-mode only).
- ReferenceExpression3 -- UNION/SUBTRACT/INTERSECT semantics, the
  join-key rule, and the left-side-dedup bug caught by testing against
  a concrete worked example rather than design review.
- The full '*' traversal generalization across all three datatypes:
  field accessors, :having()/:flatten(), the :all() meaning-collision
  (resolved via a worked example, composite-key partitioning), path
  narrowing, name_three, and pointer optionality -- including the two
  previously-latent bugs each pointer-optionality fix surfaced, and
  the CSVPATHS-vs-RESULTS/FILES inconsistency found and deliberately
  left as a documented, not-silently-fixed gap.

Updated §6 (Known gaps) to mark the INTERSECT "later phase" note
resolved (ReferenceExpression3 is built) and add the one traversal
restriction that has survived every generalization pass:
:manifest() combined with real '*'-traversal narrowing, with the
specific result.path-vs-result.uuid disambiguation problem that blocks
it, planned as a dedicated next branch.

Rewrote §7 (Not yet built at all) -- nearly everything it tracked is
now built; collapsed those into a short pointer back to §5 rather than
repeating the design reasoning, and corrected the remaining genuinely-
still-true items (type-ahead, {...} interpolation evaluation, v3's
still-pending production integration) where they had gone stale
(e.g. "no VALUE-role function is registered today" -- now false, the
whole field-accessor catalog is VALUE-role).

Re-verified test counts while at it: tests/references/ 486 -> 1099
passed; full suite 2066 -> 2687 passed, same known 11-failure
SFTP/S3/Nos baseline throughout, unrelated to references v3.

Also updated the document's own header (stale references_notes/ paths
-> specs/references_v3/, and the "as of 2026-07-31" date) to reflect
the 2026-08-19 reorganization into specs/references_v3/ and this catch-
up pass itself.
@dk107dk
dk107dk merged commit 5e24301 into main Aug 20, 2026
@dk107dk
dk107dk deleted the docs/catch-up-references-v3-compendium branch August 20, 2026 21:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant