Native meaning first Implemented
Most extraction systems perform a lossy act early and never admit it: they replace the provider's vocabulary with their own and discard the original. Afterwards there is no way to tell a correct normalisation from a wrong one, because the evidence that would settle it is gone.
TWIRX keeps both. Every field carries the provider's own term, the provider's own lexical value, and the exact locator where it appeared — beside, not beneath, the shared semantic interpretation. Normalisation is an additional view. It is never an erasure.
This matters most in the cases where normalisation is subtly wrong. A currency that was inferred rather than stated, a status vocabulary that does not quite align with the shared one, a number whose units were assumed: in each case the native value is the thing that lets a reviewer notice. Discarding it converts a recoverable error into a permanent one.
A worked example
This is a real field from the Gate E1 demonstration, taken from
examples/demo-result.json.
The origin said usd. The agent-facing value is USD. Everything
between those two facts is recorded.
{
"id": "price_currency",
"status": "resolved",
"native": { ← what the provider said
"term": "origin:testorigin/currency",
"locator": "/offer/currency",
"lexical_value": "usd"
},
"semantic": { ← our interpretation of it
"term": "commerce:OfferPrice.currency",
"value": { "type": "currency_code", "lexical": "USD" }
},
"provenance": { ← how one became the other
"final_url": "http://127.0.0.1:18080/product/sku-001",
"retrieved_at": "2026-08-10T05:07:03.9995434Z",
"body_digest": "sha256:e194e7df…",
"observation_hash": "sha256:98025ae3…",
"adapter_id": "origin:testorigin/product-offer",
"adapter_digest": "sha256:86995ebf…",
"extraction_method": "json_pointer",
"locator": "/offer/currency",
"transform_chain": ["trim", "uppercase"],
"mapping_relation": "equivalent_in_context"
}
}
Nothing here is impressive on its own. What is unusual is that the record is
complete: an auditor can fetch the body by its digest, confirm it still
hashes to the same value, find /offer/currency inside it, apply
trim then uppercase, and arrive at USD —
without trusting the system that produced the result, and without the origin
being online.
The transform chain is part of the claim
uppercase in Gate E1 operates on ASCII only, by decision, because
stable cross-language Unicode case conversion requires a versioned Unicode data
contract that does not exist yet. A future Unicode-aware transform will be a
different, versioned transform rather than a silent change in behaviour.
That is recorded in ADR 001.
Mappings are claims, not equivalences Implemented
A mapping from a provider's term to a shared term is an assertion someone made, in a context, at a version. TWIRX records it as such — including when the assertion is weak.
The same demonstration contains a second field that makes the point better than
any argument. The origin's availability value is in_stock.
It is mapped to commerce:Offer.availability, but the recorded relation
is not equivalence:
| Field | Native | Semantic | Recorded relation |
|---|---|---|---|
price_currency |
usd |
USD |
equivalent_in_context |
availability |
in_stock |
in_stock |
related |
related is the system saying: this provider's availability
vocabulary is not the same vocabulary as ours, and we are not going to pretend
otherwise. An agent that requires exact availability semantics can see that
the claim is weak and decide what to do. A system that had normalised silently
would have handed over the same string with none of that information attached.
Even equivalent_in_context carries a qualifier in its name. Equivalence
without context is the assumption that breaks first when two vocabularies meet.
Semantic closure Implemented
A result is only interpretable against the exact set of semantic modules that were in force when it was produced. Gate E1 records that set, and a digest of it, on every result:
"semantic_closure": [
"mapping:testorigin-commerce@0.1.0",
"origin:testorigin@2026-08-10",
"tw:commerce@0.1.0",
"tw:kernel@0.1.0"
],
"semantic_closure_hash": "sha256:9ef146c9…"If a mapping module is later corrected, results produced under the old closure do not silently change meaning — they remain attributable to the version that produced them. This is what makes semantic drift detectable instead of invisible.
A small kernel and unbounded extension Specified
Openness means anyone may publish an extension. Trust means not every extension becomes canonical automatically. Those two commitments only coexist if the canonical core stays small.
Kernel Specified
A deliberately tiny set of stable primitives that everything else is defined against. Changing it is a constitutional act.
Domain modules Specified
Immutable, versioned vocabularies for a subject area — commerce, transport, public records. Superseded, never edited in place.
Origin-native modules Specified
A provider's own vocabulary, described in its own terms. This is what makes native meaning representable rather than merely retained as a string.
Mapping modules Specified
Explicit, versioned bridges between an origin-native module and a domain module, carrying the relation strength and the context of the claim.
Status
Gate E1 exercises this structure concretely — the demonstration result above names four modules and hashes their closure — but the module system itself is a written direction. There is no semantic module compiler, no registry, and no admission process for modules yet. Treat the four boxes above as a design commitment, not as software.
Uncertainty is a state, not a gap Implemented
Missing, unresolved, invalid, stale, contradictory, and degraded are different
conditions, and collapsing them into null destroys the difference.
Gate E1 already enforces the two cases it can:
- A required field that cannot be extracted fails closedNo result is published. Producing nothing is correct; producing a plausible value is not.
- An optional field that is absent becomes an explicit unresolved resultIt carries provenance and omits the lexical member entirely. There is no fabricated value to mistake for data.
- A resolved empty string stays distinct from unresolved"The provider said nothing here" and "the provider said the empty string" are different statements about the world.
Contradiction between sources, staleness, and degradation are named in the charter as distinct visible states Planned. Representing them properly requires more than one source, which is a later gate.
Why this is not a centralised truth oracle
A system that assigns meaning to the whole web is one decision away from being the authority on what the web means. The design refuses that role structurally, not as a matter of policy.
- The provider's own statement is preserved, so the shared vocabulary never becomes the only record.
- Mappings are versioned claims with a stated relation strength, so disagreement can be expressed rather than resolved by fiat.
- Modules are immutable and superseded, so a correction is visible as a change rather than applied retroactively.
- Extension is open to anyone, so a vocabulary the canon refuses can still exist and compete.
- When sources disagree, the disagreement is meant to remain visible — not be averaged into a confident answer.
The project's position is that a confidence score is not an epistemology. TWIRX can prove what an origin returned and how a value was derived from it. It cannot prove the origin was right, and it is designed so that no one can later claim it did.
Related: the architecture for where semantics sits between evidence and execution, and governance for how a module would ever become canonical.