joining updated with uploaded docs - #257
Merged
Merged
Conversation
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
added a commit
that referenced
this pull request
Aug 20, 2026
Merge pull request #257 from csvpath/main
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.