Skip to content

joining updated with uploaded docs - #257

Merged
dk107dk merged 3 commits into
docs/add-references-v3-specsfrom
main
Aug 20, 2026
Merged

dk107dk merged 3 commits into
docs/add-references-v3-specsfrom
main

Conversation

@dk107dk

@dk107dk dk107dk commented Aug 20, 2026

Copy link
Copy Markdown
Collaborator

No description provided.

dk107dk and others added 3 commits August 19, 2026 21:27
Add references v3 specs and notes to the repo
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.
…endium

Catch up references_v3_compendium.md with everything since mid-August
@dk107dk
dk107dk merged commit b2855cf into docs/add-references-v3-specs Aug 20, 2026
3 checks passed
dk107dk added a commit that referenced this pull request Aug 20, 2026
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