Provenance

@telixon/core ships its engine as a compiled artifact: Google libphonenumber metadata transformed into typed-array tables (Engine). Provenance answers two questions about that artifact: which metadata revision it was compiled from, and how the runtime knows it is loading the artifact released with it.

PROVENANCE.json

Every published package carries the engine’s build record at dist/engine/PROVENANCE.json:

dist/engine/PROVENANCE.json

{
  "source": {
    "repo": "https://github.com/google/libphonenumber",
    "commit": "2b407afb2e005e5c2b3056881ecca3830e2dc585",
    "xmlPath": "resources/PhoneNumberMetadata.xml",
    "fetchedAt": "2026-06-08",
    "xmlSha256": "e4725a4852a8c4676dbcf74f1767efc89db39fb8ebcc55d9f4a984633b7ce1a3"
  },
  "coverage": {
    "territories": 245,
    "callingCodes": 206,
    "formats": 740,
    "numberTypes": 11
  },
  "validation": {
    "passedAt": "2026-06-24T15:46:53.864Z"
  },
  "builtAt": "2026-06-24T15:46:53.864Z"
}

Field	Meaning
source.repo	The metadata source repository
source.commit	The google/libphonenumber commit the engine was compiled from
source.xmlPath	The file consumed, resources/PhoneNumberMetadata.xml
source.fetchedAt	The date the metadata was fetched
source.xmlSha256	The SHA-256 recorded for the metadata XML the build consumed
coverage.*	What the compilation covers: territories, calling codes, format rules, number types
validation.passedAt	When the build’s validation of the compiled artifact passed
builtAt	When the artifact was built

The pinned commit is load-bearing. The conformance oracle reads source.commit and fetches Google’s implementation at exactly that commit, so the verification suite (Verified against Google libphonenumber) always compares the engine against the metadata revision it was compiled from. CI caches Google’s source keyed by a hash of this file, so a new engine build re-pins the oracle automatically.

Reading the record

The package exports no engine subpath, so resolve the file relative to the package entry:

read-provenance.ts

import { readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { dirname, join } from 'node:path';

const require = createRequire(import.meta.url);
const packageEntry = require.resolve('@telixon/core');
const provenancePath = join(dirname(packageEntry), 'engine', 'PROVENANCE.json');
const provenance = JSON.parse(readFileSync(provenancePath, 'utf8'));

provenance.source.commit; // '2b407afb2e005e5c2b3056881ecca3830e2dc585'
provenance.coverage.territories; // 245

Layer self-validation

The engine’s tables ship as nine binary layers packaged into four ES modules, each layer gzip-compressed and embedded as base64. Engine loading covers when and how they decode.

Module	Layers
walk.bin.js	trie, callingCodes, regionSelect
verdict.bin.js	verdict, exact
scope.bin.js	scope, regionMasks
metadata.bin.js	metadata, formatSelect

Every layer begins with an eight-byte header validated before any table is read:

Bytes	Field	Check
0 to 3	Magic	The ASCII bytes TXF1; anything else is rejected as not an engine binary
4 to 5	Layer identifier	Must match the layer being decoded, so a payload wired into the wrong slot is rejected as the wrong file
6 to 7	Format version	Must equal the runtime’s decoder version, currently 3

Beyond the header, a payload shorter than eight bytes is rejected as corrupt or truncated, and assembly requires all nine layers, naming any missing one. Every failure throws with the violated condition in the message; there is no partial-load fallback.

The format version is the coupling between data and code. Tables and decoder ship in the same package version, and the error on a mismatch states the contract directly: engine and artifacts must come from the same release.

What a metadata update means

Numbering plans change and Google’s metadata tracks them. For Telixon, a metadata update is a new compilation, not a runtime event:

• The tables ship inside the package and nothing is fetched at runtime, so numbering plan changes reach an application only through a new @telixon/core version.
• A new compilation pins a new google/libphonenumber commit and writes a new PROVENANCE.json: new commit, new checksum, new coverage counts, new timestamps.
• The conformance oracle re-pins to the new commit through this file, so the full gate set re-runs against the new metadata revision before release. The parity claim stays version-matched by construction.
• The format version ties the new tables to the decoder they were released with; mixing releases fails at load with an explicit error instead of misreading the tables.

To see which metadata revision an installed version carries, read source.commit from its PROVENANCE.json.

See also

• Verified is the parity claim this pipeline exists to keep true.
• Engine describes the artifact the compilation produces.
• ensureEngineReady is where the shipped tables load at runtime.