Grounding Shape reference

The warmhub-data/grounding component (4.0.0) is the installable field-level contract. It contains exactly the two durable provenance Shapes Source and SourceArtifact, with no seeded repository documentation.

normalized knowledge → grounded source record → SourceArtifact → Source
                                                  └────────────→ canonical semantic bytes

This is deliberately a knowledge contract, not an execution ledger. The graph records which logical Source and exact versioned canonical semantic snapshot support a grounded record. The producing system records raw transport, attempts, retries, schedules, request/response telemetry, deployments, operation plans, and commit receipts in its own bounded operational storage.

Source

Thing. The durable identity of a logical publisher or source system across many artifacts. Naming is repository-specific: a per-source repo may use Source/{system-slug}, while a co-located repo may use Source/grounding/{authority}/{source-system}. These are NamingContract examples, not platform-fixed names.

Field	Type	Meaning
publisherName	string	Human-readable organization responsible for publication.
systemName	string	Human-readable source system or dataset.
authorityClass?	string	Source authority class when the ontology needs it.
canonicalUrl	string	Stable public entry point for the source system, not an individual fetch locator.

SourceArtifact

Thing. The versioned canonical semantic snapshots of one logical dataset stream from one logical Source in a target repository. The Thing identity is the stream; its versions are accepted snapshots. A per-source repo may use SourceArtifact/{stream-slug}; a co-located repo may use SourceArtifact/grounding/{authority}/{source-system}/{stream-slug}. When the Source already identifies one dataset stream, the SourceArtifact may mirror its source-system slug without a redundant final segment.

The Thing name never contains the hash, fetch date, run id, or packaging. A changed current semantic hash revises this Thing. Re-observing the current hash is a no-op. If a source later returns to an older semantic state, that is still a change from current state: create a new version with the repeated semantic hash and its new acceptedAt.

Field	Type	Meaning
source	wref<Source>	Logical publishing source system.
semanticSha256	string	Required lowercase 64-character SHA-256 of the canonical semantic artifact bytes for this snapshot.
mediaType	string	Media type of the canonical semantic artifact; normally application/x-ndjson for record-oriented sources.
byteLength?	non-negative number	Exact canonical artifact length in bytes when recorded.
originalUrl	string	Credential-free publisher entry or retrieval locator from which the source claims were obtained.
durableUri	string	Credential-free authoritative durable locator for the canonical semantic bytes whose hash is semanticSha256.
archiveUri?	string	Credential-free publisher or independent archive locator; corroborating evidence, not the root of trust.
acceptedAt	ISO timestamp string	When this semantic snapshot first became the accepted current version of the logical stream; not revised on unchanged recapture.
sourcePublishedAt?	ISO timestamp string	Publisher-declared artifact publication time when known.
sourceEffectiveDate?	string	Publisher-declared period described by the artifact when known.
canonicalizationPolicy	string	Reviewed stable policy name/version for semantic projection, ordering, and serialization; never a run, deployment, connector instance, or attempt id.

originalUrl, durableUri, and archiveUri must exclude userinfo, fragments, signed URLs, and unreviewed secret-bearing query material. A writer fails closed when it cannot produce a safe durable locator. source identifies the logical publisher whose claims are being grounded, not a transport mirror. A repository that accepts several publishers or streams must choose a NamingContract that keeps stream identities distinct even when two canonical versions have identical bytes.

Canonical semantic artifacts

The semantic hash is trustworthy only when the producer publishes and tests a deterministic canonicalization policy. Record-oriented source policies must declare the source-grain key and normally emit canonical JSONL:

1. Parse every page, attachment, member, or chunk needed for complete stream coverage.
2. Project the complete source claims at the stream grain. Exclude transport envelopes and telemetry; do not trim, coerce, or discard claim values merely to stabilize the hash.
3. Reject duplicate or missing source-grain keys unless the source contract defines a deterministic, semantics-preserving resolution.
4. Sort records by the declared stable source-grain key.
5. Serialize each record using RFC 8785/JCS-compatible canonical JSON; emit UTF-8, one record per LF-delimited line, with a final LF.
6. Hash and durably store those exact canonical bytes before committing the SourceArtifact version.

Golden tests must permute page boundaries, page and record order, object-key order, insignificant whitespace, transport metadata, and equivalent archive packaging and obtain the same bytes and hash. A changed source claim must change the canonical bytes and hash. JCS canonicalizes objects, not dataset record order; source-specific stable ordering remains mandatory.

For non-record sources, the policy names another justified canonical form. Exact publisher bytes may be the canonical semantic artifact for a signed document, image, or other medium where normalization would erase or invent meaning. The contract rejects universal transport-byte identity, not faithful binary evidence.

Writer and access invariants

Shape validation cannot enforce stream naming, canonicalization, locator safety, or physical byte verification. The grounding writer must additionally enforce:

• the persisted canonical bytes match semanticSha256, mediaType, and byteLength when present;
• source resolves to the logical publisher represented by the artifact;
• acceptedAt is the first accepted time for this stream version and is not revised by an unchanged recapture;
• canonicalizationPolicy is a reviewed stable semantics contract rather than an execution identifier;
• the current semantic hash is compared before revision, so unchanged capture is a complete no-op;
• a grounded record’s semantic fields are compared independently of the newest artifact version, so later confirming evidence does not revise the record;
• every changed grounded-record version pins the exact SourceArtifact version that established its changed claims;
• production artifacts have a verified durable retrieval path; and
• every reader authorized to read a grounded Thing can retrieve its artifact bytes under the repository’s visibility and access policy.

Raw publisher transport, including MIME envelopes, API page bodies, response archives, and rejected candidates, stays outside WarmHub. When retained for replay or debugging, the adopting producer must enforce deletion after 30 days. An orchestrator may retain bounded run metadata, but must not copy raw bodies into logs. Explicitly reviewed, public or sanitized test fixtures may remain in source control when they are necessary to prove transport parsing; they are fixtures, not production artifact identity.

Install the grounding component per grounding repo when the repo owns acquisition, or centrally in a shared grounding repo when one authorized producer captures artifacts on behalf of several targets. In the centralized topology, grounded records use canonical cross-repo wrefs. Scratch downloads, chunks, retries, execution history, and temporary locators stay in the producing system. The ontology contract is unchanged whether that producer is scheduled, event-driven, batch-oriented, or human-supervised.

Migrating from grounding 3.x

Grounding 4.0 removes GroundingGuide and all seeds so stale method prose cannot contradict the canonical toolkit. It changes SourceArtifact identity from one Thing per raw hash to one Thing per logical dataset stream, with versions for canonical semantic snapshots. Existing 1.2/3.x hash-named artifacts remain valid historical evidence under their validated Shape versions and are not rewritten or retracted merely to adopt 4.0. New producers stop creating them and start the stream identity under 4.0.