feat(semantic): agent orientation contract + machine-readable manifest (#20) - #42
Merged
Merged
Conversation
earthshiner
marked this pull request as ready for review
July 20, 2026 05:05
earthshiner
added a commit
to earthshiner/ai-native-data-products
that referenced
this pull request
Aug 12, 2026
…ated to design/implementation split Resolves Teradata#20. Rebases PR Teradata#42 onto the post-Teradata#44 corpus: the old change edited design-standards/Semantic_Module_Design_Standard.md, deleted by the restructure, so this re-expresses it in the two-layer structure and reconciles it with the orientation layer already in main (prose handshake + a manifest_json blob). Design (platform-neutral, no SQL): - design/modules/semantic.md §3.2: DataProductOrientation entity (ordered, one row per resource, controlled resource_role vocabulary, is_required, discovery_order). §4: the orientation relation and consumption contract as normative (process in discovery_order, trust gate before analytics, resolve required resources, identities verbatim), and the manifest-is-generated rule. INV-SEMANTIC-008/009; designer checklist item. Implementation (Teradata binding): - 07-orientation-manifest.sql.j2: data_product_orientation table + generated data_product_manifest view over governance.data_product_registry, so the manifest cannot drift; canonical created_dts/updated_dts via the temporal macro. - validation.sql.j2: INV-SEMANTIC-008/009 checks (missing required role, duplicate role/order, undeployed object, unordered trust gate, unbacked manifest entrypoint). 06-orientation.md points at the relation/view as the authoritative source; manifest_json is the serialised form. README updated. Reconciliation: the generated view supersedes hand-authoring manifest_json; registry.manifest_json is kept as the serialised whole-document form. Reference brief acknowledges the two new invariants. Note: parallel PR Teradata#43 (Teradata#9) also introduces INV-SEMANTIC-008..010 and a 07-*.sql.j2; whichever merges second needs a trivial invariant/file renumber. design-lint + brief-lint clean; 103 tests pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
earthshiner
force-pushed
the
feat/orientation-manifest
branch
from
August 12, 2026 05:29
ca0cd95 to
369346a
Compare
…ated to design/implementation split Resolves Teradata#20. Rebases PR Teradata#42 onto the post-Teradata#44 corpus: the old change edited design-standards/Semantic_Module_Design_Standard.md, deleted by the restructure, so this re-expresses it in the two-layer structure and reconciles it with the orientation layer already in main (prose handshake + a manifest_json blob). Design (platform-neutral, no SQL): - design/modules/semantic.md §3.2: DataProductOrientation entity (ordered, one row per resource, controlled resource_role vocabulary, is_required, discovery_order). §4: the orientation relation and consumption contract as normative (process in discovery_order, trust gate before analytics, resolve required resources, identities verbatim), and the manifest-is-generated rule. INV-SEMANTIC-011/012; designer checklist item. Implementation (Teradata binding): - 09-orientation-manifest.sql.j2: data_product_orientation table + generated data_product_manifest view over governance.data_product_registry, so the manifest cannot drift; canonical created_dts/updated_dts via the temporal macro. - validation.sql.j2: INV-SEMANTIC-011/012 checks (missing required role, duplicate role/order, undeployed object, unordered trust gate, unbacked manifest entrypoint). 06-orientation.md points at the relation/view as the authoritative source; manifest_json is the serialised form. README updated. Reconciliation: the generated view supersedes hand-authoring manifest_json; registry.manifest_json is kept as the serialised whole-document form. Reference brief acknowledges the two new invariants. Numbered to co-exist with parallel PR Teradata#43 (Teradata#9), which owns INV-SEMANTIC-008..010 and 07-/08-*.sql.j2: this PR uses INV-SEMANTIC-011/012 and 09-*.sql.j2, so both merge in either order with no collision. design-lint + brief-lint clean; 103 tests pass. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
earthshiner
force-pushed
the
feat/orientation-manifest
branch
from
August 12, 2026 05:34
369346a to
3b06bf2
Compare
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
1 participant
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.
Resolves #20. Rebased onto the post-#44 corpus (the Design / Implementation split from #49).
The original branch edited
design-standards/Semantic_Module_Design_Standard.md(§3.10–3.11), deleted by the restructure. This re-expresses the change in the two-layer structure and reconciles it with the orientation layer already inmain— which realised orientation as a prose handshake plus amanifest_jsonblob, but with no ordered relation and no generated (drift-proof) manifest.Design (platform-neutral)
design/modules/semantic.md§3.2 —DataProductOrientationentity: an ordered relation, one row per resource, controlledresource_rolevocabulary,is_required,discovery_order.discovery_order; evaluateTRUST_GATEbefore any analytical resource; resolve required resources; use identities verbatim), and the manifest-is-generated rule (a derived view over registry + orientation, so it cannot drift).INV-SEMANTIC-008/009+ designer-checklist item.Implementation (Teradata binding)
implementation/teradata/modules/semantic/07-orientation-manifest.sql.j2—data_product_orientationtable + the generateddata_product_manifestview overgovernance.data_product_registry; canonicalcreated_dts/updated_dtsvia the temporal macro.validation.sql.j2— five orientation checks + a manifest-consistency check.06-orientation.mdnow points at the relation/view as authoritative; README updated.Reconciliation with
mainThe generated
data_product_manifestview supersedes hand-authoring the manifest;data_product_registry.manifest_jsonis kept as the serialised whole-document form (regenerated, not authored). Theresource_rolevocabulary is woven into the §4 prose that previously named resources only loosely.Verification (clean on the branch)
Notes
design-standards/file). Now a single self-contained commit on top ofmain.INV-SEMANTIC-011/012and09-orientation-manifest.sql.j2; feat(semantic): access-object metadata layer — access_object + access_composition (#9) #43 ownsINV-SEMANTIC-008..010and07-/08-*.sql.j2. No duplicate ids, no duplicate filenames. The two PRs still edit four files in common (design/modules/semantic.md, the semanticREADME.md,validation.sql.j2,tooling/evals/reference/customer-orders.md), so whoever merges second will need a one-time rebase — but every change is a disjoint addition at adjacent lines, so resolution is mechanical: keep both sides.