@primust/artifact-core 1.0.0 → 1.3.0

package/dist/hierarchical_leaf.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Primust Artifact Core — Hierarchical-ZK Canonical Encoder (L13 P3)
+ *
+ * Implements the leaf encoders specified in
+ * `followup/L13_STEP3_HIERARCHICAL_ZK_LEAF_DESIGN.md` §3.6.
+ *
+ * This module is the language-independent encoding contract: TS (SDK +
+ * verifier) and Python (`primust-verify`) MUST produce byte-identical
+ * `poseidon2:<hex>` output for the same logical input. The parity test at
+ * §13 T-7 exercises shared fixtures against both implementations.
+ *
+ * No new crypto primitive is introduced — every step is a composition of
+ * `_bytesToFieldElements` + `_parseHashToField` + `_poseidon2Sponge` +
+ * the `poseidon2:` hex-format helper.
+ *
+ * Three leaf shapes are exposed:
+ *
+ *   1. `poseidon2HexRecordLeaf` (§4) — the 4-tuple per-record leaf hash
+ *       (commitment_hash, check_result_u8, manifest_hash, sequence_index).
+ *       Fed into `buildCommitmentRoot(record_leaves, 'poseidon2')` to
+ *       obtain an action-unit's `action_unit_merkle_root`.
+ *
+ *   2. `poseidon2HexL1ActionUnitLeaf` (§3.1) — the 3-tuple action-unit
+ *       leaf (action_unit_id, aggregated_result_u8, action_unit_merkle_root).
+ *       Used as a run leaf when action_unit_count ≤ 64.
+ *
+ *   3. `poseidon2HexL2SuperUnitLeaf` (§3.2) — the 3-tuple super-unit
+ *       leaf (super_unit_id, super_unit_aggregated_result_u8,
+ *       super_unit_action_unit_merkle_root). Used as a run leaf when
+ *       action_unit_count > 64. Identical math to L1; the circuit cannot
+ *       tell L1 and L2 leaves apart.
+ */
+/**
+ * Per-record leaf hash (§4). The 4-tuple feeds the per-action-unit
+ * Merkle fold whose root is the `action_unit_merkle_root` consumed by
+ * the L1/L2 leaf encoders below.
+ *
+ * Encoding (§3.6):
+ *   elements = [
+ *     parseHashToField(commitment_hash),
+ *     BigInt(check_result_u8),
+ *     parseHashToField(manifest_hash),
+ *     BigInt(sequence_index),
+ *   ]
+ *   return 'poseidon2:' + sponge(elements).hex64
+ *
+ * @param commitmentHash  must match `^(sha256|poseidon2):[0-9a-f]{64}$`.
+ * @param checkResultU8   0..255 (codec spec lives outside this module).
+ * @param manifestHash    same shape as commitmentHash.
+ * @param sequenceIndex   0..BN254_MODULUS-1; bigint or number.
+ */
+export declare function poseidon2HexRecordLeaf(commitmentHash: string, checkResultU8: number, manifestHash: string, sequenceIndex: bigint | number): string;
+/**
+ * L1 action-unit leaf (§3.1). Used as a run leaf when
+ * action_unit_count ≤ 64.
+ *
+ * Encoding (§3.6):
+ *   elements = concat(
+ *     bytesToFieldElements(utf8(action_unit_id)),
+ *     [BigInt(aggregated_result_u8)],
+ *     [parseHashToField(action_unit_merkle_root)],
+ *   )
+ *   return 'poseidon2:' + sponge(elements).hex64
+ */
+export declare function poseidon2HexL1ActionUnitLeaf(actionUnitId: string, aggregatedResultU8: number, actionUnitMerkleRoot: string): string;
+/**
+ * L2 super-unit leaf (§3.2). Used as a run leaf when
+ * action_unit_count > 64. Identical math to L1; the circuit cannot
+ * distinguish the two leaf shapes.
+ */
+export declare function poseidon2HexL2SuperUnitLeaf(superUnitId: string, superUnitAggregatedResultU8: number, superUnitActionUnitMerkleRoot: string): string;
+//# sourceMappingURL=hierarchical_leaf.d.ts.map

package/dist/hierarchical_leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical_leaf.d.ts","sourceRoot":"","sources":["../src/hierarchical_leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAqEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GAAG,MAAM,GAC7B,MAAM,CAQR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,EAC1B,oBAAoB,EAAE,MAAM,GAC3B,MAAM,CAOR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,2BAA2B,EAAE,MAAM,EACnC,6BAA6B,EAAE,MAAM,GACpC,MAAM,CAOR"}

package/dist/hierarchical_leaf.js

@@ -0,0 +1,144 @@
+/**
+ * Primust Artifact Core — Hierarchical-ZK Canonical Encoder (L13 P3)
+ *
+ * Implements the leaf encoders specified in
+ * `followup/L13_STEP3_HIERARCHICAL_ZK_LEAF_DESIGN.md` §3.6.
+ *
+ * This module is the language-independent encoding contract: TS (SDK +
+ * verifier) and Python (`primust-verify`) MUST produce byte-identical
+ * `poseidon2:<hex>` output for the same logical input. The parity test at
+ * §13 T-7 exercises shared fixtures against both implementations.
+ *
+ * No new crypto primitive is introduced — every step is a composition of
+ * `_bytesToFieldElements` + `_parseHashToField` + `_poseidon2Sponge` +
+ * the `poseidon2:` hex-format helper.
+ *
+ * Three leaf shapes are exposed:
+ *
+ *   1. `poseidon2HexRecordLeaf` (§4) — the 4-tuple per-record leaf hash
+ *       (commitment_hash, check_result_u8, manifest_hash, sequence_index).
+ *       Fed into `buildCommitmentRoot(record_leaves, 'poseidon2')` to
+ *       obtain an action-unit's `action_unit_merkle_root`.
+ *
+ *   2. `poseidon2HexL1ActionUnitLeaf` (§3.1) — the 3-tuple action-unit
+ *       leaf (action_unit_id, aggregated_result_u8, action_unit_merkle_root).
+ *       Used as a run leaf when action_unit_count ≤ 64.
+ *
+ *   3. `poseidon2HexL2SuperUnitLeaf` (§3.2) — the 3-tuple super-unit
+ *       leaf (super_unit_id, super_unit_aggregated_result_u8,
+ *       super_unit_action_unit_merkle_root). Used as a run leaf when
+ *       action_unit_count > 64. Identical math to L1; the circuit cannot
+ *       tell L1 and L2 leaves apart.
+ */
+import { BN254_MODULUS, _bytesToFieldElements, _parseHashToField, _poseidon2Sponge, } from './commitment.js';
+// ── Helpers ──────────────────────────────────────────────────────────
+/** Format a BN254 field element as a poseidon2-prefixed 64-hex commitment. */
+function _poseidon2Hex(field) {
+    return 'poseidon2:' + field.toString(16).padStart(64, '0');
+}
+/** UTF-8 encode a string to bytes — wrapped so behavior is one line per call. */
+const _utf8Encoder = new TextEncoder();
+function _utf8(value) {
+    return _utf8Encoder.encode(value);
+}
+/** Encode an unsigned 8-bit value as a single field element. */
+function _encodeU8(value, fieldName) {
+    if (!Number.isInteger(value) || value < 0 || value > 255) {
+        throw new Error(`${fieldName} must be an integer in [0, 255]; got ${value}`);
+    }
+    return BigInt(value);
+}
+/**
+ * Encode a u64 sequence index as a single field element.
+ *
+ * Rejects JS `number` values that are not safe integers — per t_62bc
+ * correctness HOLD on PR #363: `BigInt(unsafeNumber)` silently rounds
+ * the value BEFORE conversion (`9007199254740993` → `9007199254740992`
+ * because JS already lost the bit), so a Python caller that passes the
+ * exact integer would produce a different field element than a JS
+ * caller passing the same numeric literal. To preserve TS↔Python
+ * parity, the encoder requires either a `bigint` or a safe-integer
+ * `number`.
+ */
+function _encodeU64(value, fieldName) {
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error(`${fieldName} must be an integer; got ${value}`);
+        }
+        if (!Number.isSafeInteger(value)) {
+            throw new Error(`${fieldName} number ${value} exceeds Number.MAX_SAFE_INTEGER ` +
+                `(${Number.MAX_SAFE_INTEGER}); pass a bigint to avoid silent ` +
+                'rounding (TS↔Python parity)');
+        }
+    }
+    const v = typeof value === 'bigint' ? value : BigInt(value);
+    if (v < 0n)
+        throw new Error(`${fieldName} must be non-negative; got ${v}`);
+    if (v >= BN254_MODULUS) {
+        throw new Error(`${fieldName} must be < BN254_MODULUS; got ${v} (exceeds field)`);
+    }
+    return v;
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Per-record leaf hash (§4). The 4-tuple feeds the per-action-unit
+ * Merkle fold whose root is the `action_unit_merkle_root` consumed by
+ * the L1/L2 leaf encoders below.
+ *
+ * Encoding (§3.6):
+ *   elements = [
+ *     parseHashToField(commitment_hash),
+ *     BigInt(check_result_u8),
+ *     parseHashToField(manifest_hash),
+ *     BigInt(sequence_index),
+ *   ]
+ *   return 'poseidon2:' + sponge(elements).hex64
+ *
+ * @param commitmentHash  must match `^(sha256|poseidon2):[0-9a-f]{64}$`.
+ * @param checkResultU8   0..255 (codec spec lives outside this module).
+ * @param manifestHash    same shape as commitmentHash.
+ * @param sequenceIndex   0..BN254_MODULUS-1; bigint or number.
+ */
+export function poseidon2HexRecordLeaf(commitmentHash, checkResultU8, manifestHash, sequenceIndex) {
+    const elements = [
+        _parseHashToField(commitmentHash),
+        _encodeU8(checkResultU8, 'checkResultU8'),
+        _parseHashToField(manifestHash),
+        _encodeU64(sequenceIndex, 'sequenceIndex'),
+    ];
+    return _poseidon2Hex(_poseidon2Sponge(elements));
+}
+/**
+ * L1 action-unit leaf (§3.1). Used as a run leaf when
+ * action_unit_count ≤ 64.
+ *
+ * Encoding (§3.6):
+ *   elements = concat(
+ *     bytesToFieldElements(utf8(action_unit_id)),
+ *     [BigInt(aggregated_result_u8)],
+ *     [parseHashToField(action_unit_merkle_root)],
+ *   )
+ *   return 'poseidon2:' + sponge(elements).hex64
+ */
+export function poseidon2HexL1ActionUnitLeaf(actionUnitId, aggregatedResultU8, actionUnitMerkleRoot) {
+    const elements = [
+        ..._bytesToFieldElements(_utf8(actionUnitId)),
+        _encodeU8(aggregatedResultU8, 'aggregatedResultU8'),
+        _parseHashToField(actionUnitMerkleRoot),
+    ];
+    return _poseidon2Hex(_poseidon2Sponge(elements));
+}
+/**
+ * L2 super-unit leaf (§3.2). Used as a run leaf when
+ * action_unit_count > 64. Identical math to L1; the circuit cannot
+ * distinguish the two leaf shapes.
+ */
+export function poseidon2HexL2SuperUnitLeaf(superUnitId, superUnitAggregatedResultU8, superUnitActionUnitMerkleRoot) {
+    const elements = [
+        ..._bytesToFieldElements(_utf8(superUnitId)),
+        _encodeU8(superUnitAggregatedResultU8, 'superUnitAggregatedResultU8'),
+        _parseHashToField(superUnitActionUnitMerkleRoot),
+    ];
+    return _poseidon2Hex(_poseidon2Sponge(elements));
+}
+//# sourceMappingURL=hierarchical_leaf.js.map

package/dist/hierarchical_leaf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical_leaf.js","sourceRoot":"","sources":["../src/hierarchical_leaf.ts"],"names":[],"mappings":"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"}

package/dist/hierarchical_leaf.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * T-7 cross-language parity tests for the L13 P3 canonical encoder.
+ *
+ * The golden fixtures at `schemas/golden/hierarchical_leaf_vectors.json`
+ * are produced by the Python encoder and asserted byte-for-byte by both
+ * Python and TS test suites. A drift between TS and Python on any fixture
+ * means a sealed VPEC's verifier-side root recompute will diverge from the
+ * SDK-side root emission — i.e. proofs that the SDK generates will not
+ * verify.
+ *
+ * Per merged design doc:
+ *   followup/L13_STEP3_HIERARCHICAL_ZK_LEAF_DESIGN.md §13 T-7.
+ */
+export {};
+//# sourceMappingURL=hierarchical_leaf.test.d.ts.map

package/dist/hierarchical_leaf.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical_leaf.test.d.ts","sourceRoot":"","sources":["../src/hierarchical_leaf.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/hierarchical_leaf.test.js

@@ -0,0 +1,145 @@
+/**
+ * T-7 cross-language parity tests for the L13 P3 canonical encoder.
+ *
+ * The golden fixtures at `schemas/golden/hierarchical_leaf_vectors.json`
+ * are produced by the Python encoder and asserted byte-for-byte by both
+ * Python and TS test suites. A drift between TS and Python on any fixture
+ * means a sealed VPEC's verifier-side root recompute will diverge from the
+ * SDK-side root emission — i.e. proofs that the SDK generates will not
+ * verify.
+ *
+ * Per merged design doc:
+ *   followup/L13_STEP3_HIERARCHICAL_ZK_LEAF_DESIGN.md §13 T-7.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { BN254_MODULUS } from './commitment.js';
+import { poseidon2HexL1ActionUnitLeaf, poseidon2HexL2SuperUnitLeaf, poseidon2HexRecordLeaf, } from './hierarchical_leaf.js';
+// ── Fixture loading ──────────────────────────────────────────────────
+const vectorsPath = resolve(__dirname, '../../../schemas/golden/hierarchical_leaf_vectors.json');
+const VECTORS = JSON.parse(readFileSync(vectorsPath, 'utf-8'));
+// ── record-leaf (§4 / §3.6) ──────────────────────────────────────────
+describe('hierarchical_leaf / record leaf (§4)', () => {
+    for (const v of VECTORS.record_leaves) {
+        it(`golden vector — ${v.name}`, () => {
+            const actual = poseidon2HexRecordLeaf(v.inputs.commitment_hash, v.inputs.check_result_u8, v.inputs.manifest_hash, BigInt(v.inputs.sequence_index));
+            expect(actual).toBe(v.expected);
+        });
+    }
+});
+// ── L1 action-unit leaf (§3.1 / §3.6) ────────────────────────────────
+describe('hierarchical_leaf / L1 action-unit leaf (§3.1)', () => {
+    for (const v of VECTORS.l1_action_unit_leaves) {
+        it(`golden vector — ${v.name}`, () => {
+            const actual = poseidon2HexL1ActionUnitLeaf(v.inputs.action_unit_id, v.inputs.aggregated_result_u8, v.inputs.action_unit_merkle_root);
+            expect(actual).toBe(v.expected);
+        });
+    }
+});
+// ── L2 super-unit leaf (§3.2 / §3.6) ─────────────────────────────────
+describe('hierarchical_leaf / L2 super-unit leaf (§3.2)', () => {
+    for (const v of VECTORS.l2_super_unit_leaves) {
+        it(`golden vector — ${v.name}`, () => {
+            const actual = poseidon2HexL2SuperUnitLeaf(v.inputs.super_unit_id, v.inputs.super_unit_aggregated_result_u8, v.inputs.super_unit_action_unit_merkle_root);
+            expect(actual).toBe(v.expected);
+        });
+    }
+});
+// ── L1 / L2 indistinguishability invariant ───────────────────────────
+describe('hierarchical_leaf / L1 == L2 indistinguishability (§3.2)', () => {
+    for (const v of VECTORS.l1_l2_indistinguishability) {
+        it(`circuit cannot distinguish L1 vs L2 — ${v.name}`, () => {
+            const l1 = poseidon2HexL1ActionUnitLeaf(v.inputs.id, v.inputs.result_u8, v.inputs.sub_root);
+            const l2 = poseidon2HexL2SuperUnitLeaf(v.inputs.id, v.inputs.result_u8, v.inputs.sub_root);
+            expect(l1).toBe(v.expected_l1);
+            expect(l2).toBe(v.expected_l2);
+            expect(l1).toBe(l2);
+        });
+    }
+});
+// ── Negative paths — input validation ────────────────────────────────
+describe('hierarchical_leaf / validation', () => {
+    const VALID = 'poseidon2:' + 'a'.repeat(64);
+    it('rejects negative u8 in record leaf', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, -1, VALID, 0n)).toThrow(/checkResultU8/);
+    });
+    it('rejects u8 > 255 in record leaf', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, 256, VALID, 0n)).toThrow(/checkResultU8/);
+    });
+    it('rejects non-integer u8', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, 1.5, VALID, 0n)).toThrow(/checkResultU8/);
+    });
+    it('rejects negative sequence_index', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, 0, VALID, -1n)).toThrow(/sequenceIndex/);
+    });
+    it('rejects sequence_index overflowing BN254', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, 0, VALID, BN254_MODULUS)).toThrow(/sequenceIndex/);
+    });
+    it('rejects prefixless hash in L1 leaf', () => {
+        expect(() => poseidon2HexL1ActionUnitLeaf('au_x', 0, 'a'.repeat(64))).toThrow(/Invalid hash format/);
+    });
+    // t_62bc HOLD #2898 — unsafe-integer numeric sequenceIndex parity gap.
+    // JS BigInt() silently rounds a number above Number.MAX_SAFE_INTEGER
+    // BEFORE conversion, so the TS encoder would hash a different field
+    // element than the Python encoder for the same integer literal. The
+    // encoder must reject such values, forcing callers to pass a bigint.
+    it('rejects numeric sequenceIndex above Number.MAX_SAFE_INTEGER (T-7 parity gap)', () => {
+        // Number.MAX_SAFE_INTEGER + 2 is 9007199254740993 mathematically,
+        // but JS already loses the bit and stores it as 9007199254740992.
+        // The encoder must reject the value rather than silently encode
+        // the rounded number — Python would encode the exact integer
+        // 9007199254740993, so the TS↔Python parity breaks. The test
+        // demonstrates the encoder's rejection on a non-safe-integer
+        // numeric input.
+        const unsafe = Number.MAX_SAFE_INTEGER + 2;
+        expect(Number.isSafeInteger(unsafe)).toBe(false);
+        expect(() => poseidon2HexRecordLeaf(VALID, 0, VALID, unsafe)).toThrow(/exceeds Number\.MAX_SAFE_INTEGER|pass a bigint/);
+    });
+    it('rejects non-integer numeric sequenceIndex (defensive)', () => {
+        expect(() => poseidon2HexRecordLeaf(VALID, 0, VALID, 1.5)).toThrow(/must be an integer/);
+    });
+    it('accepts bigint sequenceIndex above Number.MAX_SAFE_INTEGER (parity path)', () => {
+        // The bigint path is the parity-correct way to encode a sequence
+        // index above 2**53-1 — TS encodes the exact field element, no
+        // rounding. (BN254_MODULUS upper bound still applies.)
+        const aboveSafe = BigInt(Number.MAX_SAFE_INTEGER) + 2n;
+        expect(() => poseidon2HexRecordLeaf(VALID, 0, VALID, aboveSafe)).not.toThrow();
+    });
+});
+// ── Encoding invariants spot-checks ──────────────────────────────────
+describe('hierarchical_leaf / encoding invariants', () => {
+    const ROOT = 'poseidon2:' + '0'.repeat(64);
+    it('record leaf produces poseidon2:hex64 shape', () => {
+        const r = poseidon2HexRecordLeaf(ROOT, 0, ROOT, 0n);
+        expect(r.startsWith('poseidon2:')).toBe(true);
+        expect(r.length).toBe('poseidon2:'.length + 64);
+    });
+    it('L1 leaf produces poseidon2:hex64 shape', () => {
+        const r = poseidon2HexL1ActionUnitLeaf('au_x', 0, ROOT);
+        expect(r.startsWith('poseidon2:')).toBe(true);
+        expect(r.length).toBe('poseidon2:'.length + 64);
+    });
+    it('L2 leaf produces poseidon2:hex64 shape', () => {
+        const r = poseidon2HexL2SuperUnitLeaf('su_x', 0, ROOT);
+        expect(r.startsWith('poseidon2:')).toBe(true);
+        expect(r.length).toBe('poseidon2:'.length + 64);
+    });
+    it('record leaf is deterministic', () => {
+        const a = poseidon2HexRecordLeaf(ROOT, 4, ROOT, 42n);
+        const b = poseidon2HexRecordLeaf(ROOT, 4, ROOT, 42n);
+        expect(a).toBe(b);
+    });
+    it('different commitment_hash produces different leaf', () => {
+        const a = poseidon2HexRecordLeaf('sha256:' + 'a'.repeat(64), 0, ROOT, 0n);
+        const b = poseidon2HexRecordLeaf('sha256:' + 'b'.repeat(64), 0, ROOT, 0n);
+        expect(a).not.toBe(b);
+    });
+    it('sha256:HEX and poseidon2:HEX produce identical leaf (algorithm-agnostic-after-parse, per ZK ruling §3.2)', () => {
+        const hex = 'a'.repeat(64);
+        const a = poseidon2HexRecordLeaf('sha256:' + hex, 0, ROOT, 0n);
+        const b = poseidon2HexRecordLeaf('poseidon2:' + hex, 0, ROOT, 0n);
+        expect(a).toBe(b);
+    });
+});
+//# sourceMappingURL=hierarchical_leaf.test.js.map

package/dist/hierarchical_leaf.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical_leaf.test.js","sourceRoot":"","sources":["../src/hierarchical_leaf.test.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,9 +1,17 @@
 export { canonical } from './canonical.js';
 export { generateKeyPair, sign, verify, rotateKey, toBase64Url, fromBase64Url } from './signing.js';
-export { commit, commitOutput, buildCommitmentRoot, selectProofLevel, ZK_IS_BLOCKING, } from './commitment.js';
+export { commit, commitOutput, buildCommitmentRoot, selectProofLevel, ZK_IS_BLOCKING, BN254_MODULUS, } from './commitment.js';
 export type { CommitmentResult } from './commitment.js';
+export { poseidon2HexRecordLeaf, poseidon2HexL1ActionUnitLeaf, poseidon2HexL2SuperUnitLeaf, } from './hierarchical_leaf.js';
 export { validateArtifact } from './validate-artifact.js';
 export type { ValidationError, ValidationResult } from './validate-artifact.js';
 export type { SignerRecord, SignatureEnvelope, KeyStatus, RevocationReason, SignerType, } from './types.js';
 export type { VPECArtifact, ProofLevel, SurfaceEntry, ProofDistribution, Coverage, GapEntry, ZkProof, ArtifactIssuer, ArtifactSignature, TimestampAnchor, TransparencyLog, PendingFlags, GapType, GapSeverity, SurfaceType, ObservationMode, ScopeType, PolicyBasis, ArtifactState, CommitmentAlgorithm, Prover, ProverSystem, TsaProvider, OrgRegion, } from './types/artifact.js';
+export type { ProofArtifact, VerificationStatus } from './types/proof_artifact.js';
+export { TAXONOMY_VERSION, REVERSIBILITY_CLASSES, isReversibilityClass, classify as classifyReversibility, isWedgeSurfaceCovered, } from './reversibility_taxonomy.js';
+export type { ReversibilityClass, ClassifyOptions } from './reversibility_taxonomy.js';
+export { MAPPING_VERSION, TRUST_EDGES, classify as classifyTrustEdge, knownKinds as knownTrustEdgeKinds, } from './trust_edge_mapping.js';
+export type { TrustEdge } from './trust_edge_mapping.js';
+export { METADATA_SOURCE_VALUES, isMetadataSource } from './metadata_source.js';
+export type { MetadataSource } from './metadata_source.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,OAAO,EACP,WAAW,EACX,WAAW,EACX,eAAe,EACf,SAAS,EACT,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,YAAY,EACZ,WAAW,EACX,SAAS,GACV,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,OAAO,EACP,WAAW,EACX,WAAW,EACX,eAAe,EACf,SAAS,EACT,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,MAAM,EACN,YAAY,EACZ,WAAW,EACX,SAAS,GACV,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACnF,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,QAAQ,IAAI,qBAAqB,EACjC,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,EACL,eAAe,EACf,WAAW,EACX,QAAQ,IAAI,iBAAiB,EAC7B,UAAU,IAAI,mBAAmB,GAClC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,6 +1,10 @@
 // @primust/artifact-core — Canonical JSON, hashing, signing, commitments, artifact types
 export { canonical } from './canonical.js';
 export { generateKeyPair, sign, verify, rotateKey, toBase64Url, fromBase64Url } from './signing.js';
-export { commit, commitOutput, buildCommitmentRoot, selectProofLevel, ZK_IS_BLOCKING, } from './commitment.js';
+export { commit, commitOutput, buildCommitmentRoot, selectProofLevel, ZK_IS_BLOCKING, BN254_MODULUS, } from './commitment.js';
+export { poseidon2HexRecordLeaf, poseidon2HexL1ActionUnitLeaf, poseidon2HexL2SuperUnitLeaf, } from './hierarchical_leaf.js';
 export { validateArtifact } from './validate-artifact.js';
+export { TAXONOMY_VERSION, REVERSIBILITY_CLASSES, isReversibilityClass, classify as classifyReversibility, isWedgeSurfaceCovered, } from './reversibility_taxonomy.js';
+export { MAPPING_VERSION, TRUST_EDGES, classify as classifyTrustEdge, knownKinds as knownTrustEdgeKinds, } from './trust_edge_mapping.js';
+export { METADATA_SOURCE_VALUES, isMetadataSource } from './metadata_source.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACpG,OAAO,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAoC1D,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,QAAQ,IAAI,qBAAqB,EACjC,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,eAAe,EACf,WAAW,EACX,QAAQ,IAAI,iBAAiB,EAC7B,UAAU,IAAI,mBAAmB,GAClC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/metadata_source.d.ts

@@ -0,0 +1,4 @@
+export declare const METADATA_SOURCE_VALUES: readonly ["hook_observed", "sdk_decomposed", "sdk_caller_supplied", "hook_and_sdk_concordant"];
+export type MetadataSource = (typeof METADATA_SOURCE_VALUES)[number];
+export declare function isMetadataSource(value: unknown): value is MetadataSource;
+//# sourceMappingURL=metadata_source.d.ts.map

package/dist/metadata_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata_source.d.ts","sourceRoot":"","sources":["../src/metadata_source.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,sBAAsB,gGAmBzB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAIxE"}

package/dist/metadata_source.js

@@ -0,0 +1,54 @@
+// metadata_source enum — TypeScript sibling of
+// `packages/primust-checks/src/primust_checks/metadata_source.py`.
+//
+// Single source of truth for the metadata_source CHECK enum on
+// check_execution_records (migration 179) on the TS side.
+//
+// Each of the four values is a PRECISE, NARROW provenance claim —
+// not a fallback ladder. The values' trust meaning depends on staying
+// narrow.
+//
+//   - 'hook_observed' — A runtime intercept (CC / Cursor / Anthropic
+//     Agent SDK lifecycle hook) saw this at the framework boundary.
+//     Substrate witness; strongest non-repudiation.
+//
+//   - 'sdk_decomposed' — An SDK adapter derived the bounded metadata
+//     in-process (LLM quadruple, enforcement attribution, redaction).
+//     Adapter composition — observed and shaped, not relayed.
+//
+//   - 'sdk_caller_supplied' — App code passed metadata args to
+//     run.record() and the SDK relayed without deriving or
+//     independently observing. Caller-as-source-of-truth. Honest,
+//     narrow; weaker evidence than hook_observed (no substrate
+//     witness) or sdk_decomposed (no adapter composition).
+//
+//   - 'hook_and_sdk_concordant' — Both layers independently confirmed
+//     the same fact via the trace_context join (Phase 3+). Cross-
+//     checked; highest trust. Back-filled server-side.
+//
+//   - NULL — RESERVED for legacy pre-179 rows and aggregator-emitted
+//     records with no single per-record derivation. No new emitter
+//     should land NULL. A NULL on a fresh record is an emitter bug.
+//
+// SI-1: enum-constrained string, never content.
+export const METADATA_SOURCE_VALUES = [
+    // Runtime intercept saw the event at the framework boundary.
+    // Substrate witness; strongest non-repudiation.
+    'hook_observed',
+    // SDK adapter derived the bounded metadata in-process (LLM
+    // quadruple, enforcement attribution, redaction). Adapter
+    // composition — observed and shaped, not relayed.
+    'sdk_decomposed',
+    // App code passed metadata args to run.record() and the SDK
+    // relayed without deriving or independently observing. Honest,
+    // narrow; weaker than hook_observed / sdk_decomposed.
+    'sdk_caller_supplied',
+    // Both layers independently confirmed the same fact via the
+    // trace_context join (Phase 3+). Cross-checked; highest trust.
+    // Back-filled server-side; never emitted directly by a single layer.
+    'hook_and_sdk_concordant',
+];
+export function isMetadataSource(value) {
+    return (typeof value === 'string' && METADATA_SOURCE_VALUES.includes(value));
+}
+//# sourceMappingURL=metadata_source.js.map

package/dist/metadata_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata_source.js","sourceRoot":"","sources":["../src/metadata_source.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,mEAAmE;AACnE,EAAE;AACF,+DAA+D;AAC/D,0DAA0D;AAC1D,EAAE;AACF,kEAAkE;AAClE,sEAAsE;AACtE,UAAU;AACV,EAAE;AACF,qEAAqE;AACrE,oEAAoE;AACpE,oDAAoD;AACpD,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,EAAE;AACF,+DAA+D;AAC/D,2DAA2D;AAC3D,kEAAkE;AAClE,+DAA+D;AAC/D,2DAA2D;AAC3D,EAAE;AACF,sEAAsE;AACtE,kEAAkE;AAClE,uDAAuD;AACvD,EAAE;AACF,qEAAqE;AACrE,mEAAmE;AACnE,oEAAoE;AACpE,EAAE;AACF,gDAAgD;AAEhD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,6DAA6D;IAC7D,gDAAgD;IAChD,eAAe;IAEf,2DAA2D;IAC3D,0DAA0D;IAC1D,kDAAkD;IAClD,gBAAgB;IAEhB,4DAA4D;IAC5D,+DAA+D;IAC/D,sDAAsD;IACtD,qBAAqB;IAErB,4DAA4D;IAC5D,+DAA+D;IAC/D,qEAAqE;IACrE,yBAAyB;CACjB,CAAC;AAIX,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAA4C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAC3F,CAAC;AACJ,CAAC"}

package/dist/metadata_source.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metadata_source.test.d.ts.map

package/dist/metadata_source.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata_source.test.d.ts","sourceRoot":"","sources":["../src/metadata_source.test.ts"],"names":[],"mappings":""}

package/dist/metadata_source.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { METADATA_SOURCE_VALUES, isMetadataSource } from './metadata_source.js';
+describe('metadata_source', () => {
+    it('has exactly the four canonical values from migration 179', () => {
+        expect(new Set(METADATA_SOURCE_VALUES)).toEqual(new Set([
+            'hook_observed',
+            'sdk_decomposed',
+            'sdk_caller_supplied',
+            'hook_and_sdk_concordant',
+        ]));
+    });
+    it('isMetadataSource accepts all four enum strings', () => {
+        for (const v of METADATA_SOURCE_VALUES) {
+            expect(isMetadataSource(v)).toBe(true);
+        }
+    });
+    it('rejects unknown strings (including the distinct `source` enum)', () => {
+        expect(isMetadataSource('garbage')).toBe(false);
+        expect(isMetadataSource('hook')).toBe(false); // bare 'hook' is `source`, not metadata_source
+        expect(isMetadataSource('sdk')).toBe(false);
+    });
+    it('rejects non-strings', () => {
+        expect(isMetadataSource(null)).toBe(false);
+        expect(isMetadataSource(42)).toBe(false);
+        expect(isMetadataSource([])).toBe(false);
+        expect(isMetadataSource({ value: 'hook_observed' })).toBe(false);
+    });
+});
+//# sourceMappingURL=metadata_source.test.js.map

package/dist/metadata_source.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata_source.test.js","sourceRoot":"","sources":["../src/metadata_source.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,CAAC,IAAI,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC,OAAO,CAC7C,IAAI,GAAG,CAAC;YACN,eAAe;YACf,gBAAgB;YAChB,qBAAqB;YACrB,yBAAyB;SAC1B,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,KAAK,MAAM,CAAC,IAAI,sBAAsB,EAAE,CAAC;YACvC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,+CAA+C;QAC7F,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/reversibility_taxonomy.d.ts

@@ -0,0 +1,23 @@
+export declare const TAXONOMY_VERSION: "1.0.0";
+export declare const REVERSIBILITY_CLASSES: readonly ["reversible", "append_only", "external_side_effect", "irreversible", "unknown"];
+export type ReversibilityClass = (typeof REVERSIBILITY_CLASSES)[number];
+export declare function isReversibilityClass(v: unknown): v is ReversibilityClass;
+export interface ClassifyOptions {
+    overrides?: Record<string, string>;
+}
+/**
+ * Classify an outbound action by `(target_system_kind, operation)`.
+ *
+ * Lookup order:
+ *   1. Customer override for the exact (kind, op) pair.
+ *   2. System default for the exact (kind, op) pair.
+ *   3. Per-kind fallback.
+ *   4. `'unknown'`.
+ */
+export declare function classify(target_system_kind: string, operation: string, options?: ClassifyOptions): ReversibilityClass;
+/**
+ * True if this kind has real (non-`'unknown'`) classifications in the
+ * system defaults. Used by the Phase 1 acceptance gate.
+ */
+export declare function isWedgeSurfaceCovered(target_system_kind: string): boolean;
+//# sourceMappingURL=reversibility_taxonomy.d.ts.map

package/dist/reversibility_taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reversibility_taxonomy.d.ts","sourceRoot":"","sources":["../src/reversibility_taxonomy.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,gBAAgB,EAAG,OAAgB,CAAC;AAEjD,eAAO,MAAM,qBAAqB,2FAMxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAGxE,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,kBAAkB,CAExE;AAgKD,MAAM,WAAW,eAAe;IAI9B,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,kBAAkB,CAcpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAMzE"}