agent-passport-system 1.45.0 → 1.46.0

package/README.md

@@ -123,11 +123,11 @@ Institutional governance: charters, offices, federation, reserves, multi-party a
 npx agent-passport-system-mcp
 ```
 
-20 essential tools by default. Set `APS_PROFILE=full` for all 149 tools. Profiles: essential, identity, governance, coordination, commerce, data, gateway, comms, minimal, full.
+20 essential tools by default. Set `APS_PROFILE=full` for all 151 tools. Profiles: essential, identity, governance, coordination, commerce, data, gateway, comms, minimal, full.
 
 ## Numbers
 
-2,910 tests. 8 protocol layers. 11 framework adapters. Gateway evaluation under 2ms. Zero heavy dependencies. Apache-2.0.
+2,937 tests. 8 protocol layers. 11 framework adapters. Gateway evaluation under 2ms. Zero heavy dependencies. Apache-2.0.
 
 ## Papers
 

package/dist/src/v2/attribution-settlement/aggregate.d.ts

@@ -0,0 +1,30 @@
+import type { AttributionPrimitive } from '../attribution-primitive/types.js';
+import type { SettlementContributor, SettlementPeriod, SettlementRecord, SettlementResidualBucket } from './types.js';
+/** Canonical per-contributor leaf hash — hex sha256 of the canonical
+ *  body (contributor_did, total_weight, contribution_count). Exposed so
+ *  contributor-query verifiers recompute the same bytes. */
+export declare function contributorLeafHashHex(c: SettlementContributor): string;
+/** Residual-bucket leaf hash for the per-axis tree. Canonicalizes the
+ *  full bucket object. */
+export declare function residualLeafHashHex(r: SettlementResidualBucket): string;
+/** 6-digit decimal form for settlement weights. Unlike Build A's
+ *  `toWeightString`, settlement weights can exceed 1.0 (they accumulate
+ *  over many actions); the 6-digit precision is preserved. Rejects
+ *  non-finite or negative values. */
+export declare function formatSettlementWeight(v: number): string;
+export interface AggregateOptions {
+    /** Gateway DID that will sign the settlement record. */
+    gateway_did: string;
+    /** Override issued_at (tests, replayed audits). Must be canonical. */
+    issued_at?: string;
+    /** When false, throws on any receipt whose timestamp is outside
+     *  [t0, t1). Default is true — out-of-period receipts are silently
+     *  dropped so a caller can hand us an uncurated batch. */
+    skipOutOfPeriod?: boolean;
+}
+/** Compute the unsigned settlement record for `receipts` over `period`.
+ *  Half-open interval [t0, t1) — receipts at exactly t1 are excluded.
+ *  Returns the record minus its `signature` field; callers pass the
+ *  result to `signSettlementRecord` to produce the signed record. */
+export declare function aggregateAttributionPrimitives(receipts: AttributionPrimitive[], period: SettlementPeriod, options: AggregateOptions): Omit<SettlementRecord, 'signature'>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/src/v2/attribution-settlement/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../../../src/v2/attribution-settlement/aggregate.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAEV,oBAAoB,EASrB,MAAM,mCAAmC,CAAA;AAE1C,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,YAAY,CAAA;AA8BnB;;4DAE4D;AAC5D,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAEvE;AAED;0BAC0B;AAC1B,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAEvE;AA6GD;;;qCAGqC;AACrC,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxD;AA4ED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;8DAE0D;IAC1D,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;qEAGqE;AACrE,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,oBAAoB,EAAE,EAChC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,gBAAgB,GACxB,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,CA6ErC"}

package/dist/src/v2/attribution-settlement/aggregate.js

@@ -0,0 +1,306 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// Attribution Settlement — aggregation (Build C)
+// ══════════════════════════════════════════════════════════════════
+// Spec: BUILD-C-SETTLEMENT-PIPELINE.md §"The aggregation".
+//
+// Given a stream of Attribution Primitives whose timestamps fall within
+// [t0, t1) (half-open; I-C5 / property test #7), compute:
+//
+//   - per-axis per-contributor total_weight (sum of signed weights)
+//   - per-axis residual bucket aggregation
+//   - per-axis balanced-Merkle axis_merkle_root
+//   - input_receipts_hash (Merkle commitment over sorted action_refs)
+//
+// Axis weight sourcing:
+//   D  contribution_weight (Build B normalized; sums to ~1 per receipt)
+//   C  compute_share        (Build B normalized; sums to ~1 per receipt)
+//   P  weight if present on every explicit entry; equal-split (1/|P|)
+//      otherwise. Mixed-weight receipts fall back to the weights they
+//      carry and omit unweighted entries — documented in the handoff.
+//   G  equal-split (1/|G|) — governance axis has no weight field in
+//      Build A. Equal-split preserves I-C2 conservation (Σ weights per
+//      receipt = 1) without inventing economic meaning the spec declines
+//      to define.
+//
+// Residual buckets are treated as a single virtual contributor per axis;
+// their `total_pooled_weight` sums across the period (I-C6).
+// ══════════════════════════════════════════════════════════════════
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../../core/canonical.js';
+import { assertCanonicalTimestamp, } from '../attribution-primitive/canonical.js';
+import { buildMerkleRoot, emptyAxisMerkleRoot, leafHash } from './merkle.js';
+function isResidual(x) {
+    return (typeof x === 'object' &&
+        x !== null &&
+        'residual_id' in x &&
+        typeof x.residual_id === 'string' &&
+        x.residual_id.startsWith('residual:'));
+}
+function weightNumber(w) {
+    const n = Number.parseFloat(w);
+    if (!Number.isFinite(n))
+        throw new Error(`attribution-settlement: invalid weight string "${w}"`);
+    return n;
+}
+function contributorLeafBody(c) {
+    return {
+        contributor_did: c.contributor_did,
+        total_weight: c.total_weight,
+        contribution_count: c.contribution_count,
+    };
+}
+/** Canonical per-contributor leaf hash — hex sha256 of the canonical
+ *  body (contributor_did, total_weight, contribution_count). Exposed so
+ *  contributor-query verifiers recompute the same bytes. */
+export function contributorLeafHashHex(c) {
+    return createHash('sha256').update(canonicalize(contributorLeafBody(c))).digest('hex');
+}
+/** Residual-bucket leaf hash for the per-axis tree. Canonicalizes the
+ *  full bucket object. */
+export function residualLeafHashHex(r) {
+    return createHash('sha256').update(canonicalize(r)).digest('hex');
+}
+function emptyAccum() {
+    return {
+        map: new Map(),
+        pooledWeight: 0,
+        pooledMemberCount: 0,
+        perReceiptResidualHashes: [],
+        totalActions: 0,
+    };
+}
+function addContributor(accum, did, weight) {
+    const cur = accum.map.get(did);
+    if (cur) {
+        cur.total += weight;
+        cur.count += 1;
+    }
+    else {
+        accum.map.set(did, { total: weight, count: 1 });
+    }
+}
+function accumulateResidual(accum, bucket) {
+    accum.pooledWeight += weightNumber(bucket.total_pooled_weight);
+    accum.pooledMemberCount += bucket.count_of_pooled_contributors;
+    accum.perReceiptResidualHashes.push(bucket.pooled_contributors_hash);
+}
+function pooledWeightOfReceipt(residuals) {
+    let w = 0;
+    for (const r of residuals)
+        w += weightNumber(r.total_pooled_weight);
+    return w;
+}
+function processDataAxis(items, accum) {
+    if (items.length === 0)
+        return;
+    accum.totalActions += 1;
+    for (const item of items) {
+        if (isResidual(item)) {
+            accumulateResidual(accum, item);
+        }
+        else {
+            const e = item;
+            addContributor(accum, e.source_did, weightNumber(e.contribution_weight));
+        }
+    }
+}
+function processComputeAxis(items, accum) {
+    if (items.length === 0)
+        return;
+    accum.totalActions += 1;
+    for (const item of items) {
+        if (isResidual(item)) {
+            accumulateResidual(accum, item);
+        }
+        else {
+            const e = item;
+            addContributor(accum, e.provider_did, weightNumber(e.compute_share));
+        }
+    }
+}
+function protocolEntryDid(e) {
+    return `${e.module_id}@${e.module_version}`;
+}
+function processProtocolAxis(items, accum) {
+    if (items.length === 0)
+        return;
+    accum.totalActions += 1;
+    const explicit = items.filter((x) => !isResidual(x));
+    const residuals = items.filter((x) => isResidual(x));
+    for (const r of residuals)
+        accumulateResidual(accum, r);
+    const anyWeighted = explicit.some((e) => e.weight !== undefined);
+    if (anyWeighted) {
+        for (const e of explicit) {
+            if (e.weight === undefined)
+                continue;
+            addContributor(accum, protocolEntryDid(e), weightNumber(e.weight));
+        }
+    }
+    else if (explicit.length > 0) {
+        const budget = Math.max(0, 1 - pooledWeightOfReceipt(residuals));
+        const w = budget / explicit.length;
+        for (const e of explicit) {
+            addContributor(accum, protocolEntryDid(e), w);
+        }
+    }
+}
+function processGovernanceAxis(items, accum) {
+    if (items.length === 0)
+        return;
+    accum.totalActions += 1;
+    const w = 1 / items.length;
+    for (const e of items) {
+        addContributor(accum, e.signer_did, w);
+    }
+}
+/** 6-digit decimal form for settlement weights. Unlike Build A's
+ *  `toWeightString`, settlement weights can exceed 1.0 (they accumulate
+ *  over many actions); the 6-digit precision is preserved. Rejects
+ *  non-finite or negative values. */
+export function formatSettlementWeight(v) {
+    if (!Number.isFinite(v)) {
+        throw new Error(`attribution-settlement: weight must be finite, got ${v}`);
+    }
+    if (v < 0) {
+        throw new Error(`attribution-settlement: weight must be non-negative, got ${v}`);
+    }
+    return v.toFixed(6);
+}
+function finalizeAxis(axis, accum, period) {
+    const dids = [...accum.map.keys()].sort();
+    const contributors = dids.map((did) => {
+        const { total, count } = accum.map.get(did);
+        const totalStr = formatSettlementWeight(total);
+        const leafBody = {
+            contributor_did: did,
+            total_weight: totalStr,
+            contribution_count: count,
+        };
+        const merkle_leaf_hash = createHash('sha256')
+            .update(canonicalize(leafBody))
+            .digest('hex');
+        return {
+            contributor_did: did,
+            total_weight: totalStr,
+            contribution_count: count,
+            merkle_leaf_hash,
+        };
+    });
+    let residual_bucket = null;
+    if (accum.pooledMemberCount > 0 || accum.perReceiptResidualHashes.length > 0) {
+        if (axis === 'G') {
+            throw new Error('attribution-settlement: governance axis cannot carry a residual bucket');
+        }
+        const sortedPerReceiptHashes = [...accum.perReceiptResidualHashes].sort();
+        const pooled_contributors_hash = createHash('sha256')
+            .update(canonicalize(sortedPerReceiptHashes))
+            .digest('hex');
+        const residual_id = `residual:${axis}`;
+        residual_bucket = {
+            residual_id,
+            total_pooled_weight: formatSettlementWeight(accum.pooledWeight),
+            count_of_pooled_contributors: accum.pooledMemberCount,
+            pooled_contributors_hash,
+        };
+    }
+    const leafHashes = contributors.map((c) => Buffer.from(c.merkle_leaf_hash, 'hex'));
+    if (residual_bucket) {
+        leafHashes.push(Buffer.from(residualLeafHashHex(residual_bucket), 'hex'));
+    }
+    const axis_merkle_root = leafHashes.length === 0 ? emptyAxisMerkleRoot() : buildMerkleRoot(leafHashes).toString('hex');
+    return {
+        axis,
+        period,
+        total_actions: accum.totalActions,
+        contributors,
+        residual_bucket,
+        axis_merkle_root,
+    };
+}
+function assertPeriod(period) {
+    if (!period || typeof period !== 'object') {
+        throw new Error('attribution-settlement: period required');
+    }
+    assertCanonicalTimestamp(period.t0);
+    assertCanonicalTimestamp(period.t1);
+    if (Date.parse(period.t0) >= Date.parse(period.t1)) {
+        throw new Error('attribution-settlement: period.t0 must be strictly before period.t1');
+    }
+    if (typeof period.period_id !== 'string' || period.period_id.length === 0) {
+        throw new Error('attribution-settlement: period.period_id required');
+    }
+}
+/** Compute the unsigned settlement record for `receipts` over `period`.
+ *  Half-open interval [t0, t1) — receipts at exactly t1 are excluded.
+ *  Returns the record minus its `signature` field; callers pass the
+ *  result to `signSettlementRecord` to produce the signed record. */
+export function aggregateAttributionPrimitives(receipts, period, options) {
+    if (!Array.isArray(receipts)) {
+        throw new Error('attribution-settlement: receipts must be an array');
+    }
+    if (!options || typeof options.gateway_did !== 'string' || options.gateway_did.length === 0) {
+        throw new Error('attribution-settlement: options.gateway_did required');
+    }
+    assertPeriod(period);
+    const t0 = Date.parse(period.t0);
+    const t1 = Date.parse(period.t1);
+    const skipOut = options.skipOutOfPeriod !== false;
+    const accums = {
+        D: emptyAccum(),
+        P: emptyAccum(),
+        G: emptyAccum(),
+        C: emptyAccum(),
+    };
+    const inPeriod = [];
+    for (const r of receipts) {
+        assertCanonicalTimestamp(r.timestamp);
+        const ts = Date.parse(r.timestamp);
+        if (ts < t0 || ts >= t1) {
+            if (!skipOut) {
+                throw new Error(`attribution-settlement: receipt ${r.action_ref} timestamp ${r.timestamp} outside period [${period.t0}, ${period.t1})`);
+            }
+            continue;
+        }
+        inPeriod.push(r);
+    }
+    for (const r of inPeriod) {
+        processDataAxis(r.axes.D, accums.D);
+        processProtocolAxis(r.axes.P, accums.P);
+        processGovernanceAxis(r.axes.G, accums.G);
+        processComputeAxis(r.axes.C, accums.C);
+    }
+    // Deep-clone period per axis so the shared-reference DAG doesn't trip
+    // core/canonical.ts's cycle detector (which treats any revisit as a
+    // cycle — a separate latent bug, worked around here). JSON-safe clone
+    // is fine: period is three plain strings.
+    const clonePeriod = () => ({
+        t0: period.t0,
+        t1: period.t1,
+        period_id: period.period_id,
+    });
+    const axes = {
+        D: finalizeAxis('D', accums.D, clonePeriod()),
+        P: finalizeAxis('P', accums.P, clonePeriod()),
+        G: finalizeAxis('G', accums.G, clonePeriod()),
+        C: finalizeAxis('C', accums.C, clonePeriod()),
+    };
+    const sortedActionRefs = inPeriod.map((r) => r.action_ref).sort();
+    const actionRefLeaves = sortedActionRefs.map((ref) => leafHash(ref));
+    const input_receipts_hash = actionRefLeaves.length === 0
+        ? emptyAxisMerkleRoot()
+        : buildMerkleRoot(actionRefLeaves).toString('hex');
+    const issued_at = options.issued_at ?? new Date().toISOString();
+    assertCanonicalTimestamp(issued_at);
+    return {
+        schema: 'aps.settlement.v1',
+        period,
+        gateway_did: options.gateway_did,
+        axes,
+        input_receipts_hash,
+        total_input_count: inPeriod.length,
+        issued_at,
+    };
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/src/v2/attribution-settlement/aggregate.js.map

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

package/dist/src/v2/attribution-settlement/contributor-query.d.ts

@@ -0,0 +1,21 @@
+import type { ContributorQueryResponse, SettlementRecord, SettlementVerifyResult } from './types.js';
+/** Build the per-contributor query response. Returns null if the
+ *  contributor has no share on any axis — callers can surface that
+ *  distinctly from "the gateway returned a response, here it is". */
+export declare function buildContributorQueryResponse(record: SettlementRecord, contributorDid: string, opts?: {
+    gateway_jwks?: string;
+}): ContributorQueryResponse | null;
+/** Verify a contributor-query response end-to-end. Checks:
+ *
+ *   (a) the embedded SettlementRecord passes S1–S4
+ *   (b) each per_axis body's (leaf, leaf_index, merkle_path) reconstructs
+ *       `axis_root`, which matches `record.axes[X].axis_merkle_root`
+ *   (c) the claimed total_weight and contribution_count match the
+ *       record's per-axis contributor row
+ *   (d) settlement_record_hash recomputes
+ *
+ *  Returns the same discriminated result type as `verifySettlementRecord`. */
+export declare function verifyContributorQueryResponse(response: ContributorQueryResponse, options: {
+    gatewayPublicKeyHex: string;
+}): SettlementVerifyResult;
+//# sourceMappingURL=contributor-query.d.ts.map

package/dist/src/v2/attribution-settlement/contributor-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributor-query.d.ts","sourceRoot":"","sources":["../../../../src/v2/attribution-settlement/contributor-query.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAEV,wBAAwB,EAExB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAoBnB;;qEAEqE;AACrE,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,gBAAgB,EACxB,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,wBAAwB,GAAG,IAAI,CAqCjC;AAED;;;;;;;;;8EAS8E;AAC9E,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE;IAAE,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACvC,sBAAsB,CAsExB"}

package/dist/src/v2/attribution-settlement/contributor-query.js

@@ -0,0 +1,147 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// ══════════════════════════════════════════════════════════════════
+// Attribution Settlement — contributor-query response (Build C)
+// ══════════════════════════════════════════════════════════════════
+// Spec: BUILD-C-SETTLEMENT-PIPELINE.md §"The contributor query".
+//
+// Given a signed SettlementRecord and a contributor DID, construct the
+// per-axis proof bundle: for each axis where the contributor has a
+// share, return the Merkle path from their leaf to that axis's root.
+//
+// Verification is fully self-contained: the response embeds the signed
+// record so a third party can reproduce S1–S2 end-to-end with only the
+// gateway public key.
+// ══════════════════════════════════════════════════════════════════
+import { buildContributorMerklePath, verifyMerklePath, } from './merkle.js';
+import { residualLeafHashHex } from './aggregate.js';
+import { settlementRecordHash, verifySettlementSignature, } from './sign.js';
+import { verifySettlementRecord } from './verify.js';
+function buildAxisLeaves(axis) {
+    const leaves = axis.contributors.map((c) => Buffer.from(c.merkle_leaf_hash, 'hex'));
+    if (axis.residual_bucket) {
+        leaves.push(Buffer.from(residualLeafHashHex(axis.residual_bucket), 'hex'));
+    }
+    return leaves;
+}
+function findContributorIndex(axis, contributorDid) {
+    for (let i = 0; i < axis.contributors.length; i++) {
+        if (axis.contributors[i].contributor_did === contributorDid)
+            return i;
+    }
+    return -1;
+}
+/** Build the per-contributor query response. Returns null if the
+ *  contributor has no share on any axis — callers can surface that
+ *  distinctly from "the gateway returned a response, here it is". */
+export function buildContributorQueryResponse(record, contributorDid, opts) {
+    if (!contributorDid || typeof contributorDid !== 'string') {
+        throw new Error('attribution-settlement: contributorDid required');
+    }
+    const per_axis = {};
+    let anyFound = false;
+    for (const tag of ['D', 'P', 'G', 'C']) {
+        const axis = record.axes[tag];
+        const idx = findContributorIndex(axis, contributorDid);
+        if (idx < 0)
+            continue;
+        const leaves = buildAxisLeaves(axis);
+        const merkle_path = buildContributorMerklePath(leaves, idx);
+        const body = {
+            total_weight: axis.contributors[idx].total_weight,
+            contribution_count: axis.contributors[idx].contribution_count,
+            leaf_index: idx,
+            merkle_path,
+            axis_root: axis.axis_merkle_root,
+        };
+        per_axis[tag] = body;
+        anyFound = true;
+    }
+    if (!anyFound)
+        return null;
+    const { signature: _unused, ...unsigned } = record;
+    void _unused;
+    return {
+        settlement_record: record,
+        settlement_record_hash: settlementRecordHash(unsigned),
+        contributor_did: contributorDid,
+        per_axis,
+        gateway_jwks: opts?.gateway_jwks,
+    };
+}
+/** Verify a contributor-query response end-to-end. Checks:
+ *
+ *   (a) the embedded SettlementRecord passes S1–S4
+ *   (b) each per_axis body's (leaf, leaf_index, merkle_path) reconstructs
+ *       `axis_root`, which matches `record.axes[X].axis_merkle_root`
+ *   (c) the claimed total_weight and contribution_count match the
+ *       record's per-axis contributor row
+ *   (d) settlement_record_hash recomputes
+ *
+ *  Returns the same discriminated result type as `verifySettlementRecord`. */
+export function verifyContributorQueryResponse(response, options) {
+    if (!response || typeof response !== 'object') {
+        return { valid: false, reason: 'MALFORMED', detail: 'response must be an object' };
+    }
+    if (!options || !options.gatewayPublicKeyHex) {
+        return { valid: false, reason: 'MALFORMED', detail: 'options.gatewayPublicKeyHex required' };
+    }
+    if (!response.settlement_record) {
+        return { valid: false, reason: 'MALFORMED', detail: 'settlement_record required' };
+    }
+    // (a) delegate to the settlement verifier for S1–S4.
+    const inner = verifySettlementRecord(response.settlement_record, {
+        gatewayPublicKeyHex: options.gatewayPublicKeyHex,
+    });
+    if (!inner.valid)
+        return inner;
+    // Redundant sanity-check on the signature — verifySettlementRecord
+    // already did this, but we want a distinct code path that future
+    // refactors can't silently drop.
+    if (!verifySettlementSignature(response.settlement_record, options.gatewayPublicKeyHex)) {
+        return { valid: false, reason: 'SIGNATURE_INVALID' };
+    }
+    // (d) settlement_record_hash recomputes.
+    const { signature: _unused, ...body } = response.settlement_record;
+    void _unused;
+    const expectedHash = settlementRecordHash(body);
+    if (expectedHash !== response.settlement_record_hash.toLowerCase()) {
+        return { valid: false, reason: 'MERKLE_ROOT_MISMATCH', detail: 'settlement_record_hash mismatch' };
+    }
+    // (b, c) per-axis path and claim verification.
+    for (const tag of Object.keys(response.per_axis)) {
+        const axisBody = response.per_axis[tag];
+        if (!axisBody)
+            continue;
+        const axis = response.settlement_record.axes[tag];
+        if (axisBody.axis_root.toLowerCase() !== axis.axis_merkle_root.toLowerCase()) {
+            return { valid: false, reason: 'MERKLE_ROOT_MISMATCH', detail: `axes.${tag}.axis_root mismatch` };
+        }
+        if (axisBody.leaf_index < 0 || axisBody.leaf_index >= axis.contributors.length) {
+            return { valid: false, reason: 'MALFORMED', detail: `axes.${tag}.leaf_index out of range` };
+        }
+        const row = axis.contributors[axisBody.leaf_index];
+        if (row.contributor_did !== response.contributor_did) {
+            return {
+                valid: false,
+                reason: 'MERKLE_ROOT_MISMATCH',
+                detail: `axes.${tag}.leaf_index points to a different DID`,
+            };
+        }
+        if (row.total_weight !== axisBody.total_weight) {
+            return { valid: false, reason: 'MALFORMED', detail: `axes.${tag}.total_weight claim mismatch` };
+        }
+        if (row.contribution_count !== axisBody.contribution_count) {
+            return {
+                valid: false,
+                reason: 'MALFORMED',
+                detail: `axes.${tag}.contribution_count claim mismatch`,
+            };
+        }
+        const leaf = Buffer.from(row.merkle_leaf_hash, 'hex');
+        if (!verifyMerklePath(leaf, axisBody.leaf_index, axisBody.merkle_path, axisBody.axis_root)) {
+            return { valid: false, reason: 'MERKLE_ROOT_MISMATCH', detail: `axes.${tag} merkle_path does not reconstruct axis_root` };
+        }
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=contributor-query.js.map

package/dist/src/v2/attribution-settlement/contributor-query.js.map

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

package/dist/src/v2/attribution-settlement/index.d.ts

@@ -0,0 +1,9 @@
+export type { SettlementAxisIndex, SettlementContributor, SettlementPeriod, SettlementRecord, SettlementResidualBucket, SettlementVerifyReason, SettlementVerifyResult, ContributorQueryAxisBody, ContributorQueryResponse, } from './types.js';
+export { aggregateAttributionPrimitives, contributorLeafHashHex, formatSettlementWeight, residualLeafHashHex, } from './aggregate.js';
+export type { AggregateOptions } from './aggregate.js';
+export { buildContributorMerklePath, buildMerkleRoot, emptyAxisMerkleRoot, leafHash as settlementLeafHash, verifyMerklePath, } from './merkle.js';
+export { settlementRecordHash, settlementSigningPayload, signSettlementRecord, verifySettlementSignature, } from './sign.js';
+export { verifySettlementRecord } from './verify.js';
+export type { VerifySettlementOptions } from './verify.js';
+export { buildContributorQueryResponse, verifyContributorQueryResponse, } from './contributor-query.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/v2/attribution-settlement/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/v2/attribution-settlement/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtD,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,QAAQ,IAAI,kBAAkB,EAC9B,gBAAgB,GACjB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAE1D,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAA"}

package/dist/src/v2/attribution-settlement/index.js

@@ -0,0 +1,14 @@
+// Copyright 2024-2026 Tymofii Pidlisnyi. Apache-2.0 license. See LICENSE.
+// Attribution Settlement — public surface (Build C).
+//
+// Spec: BUILD-C-SETTLEMENT-PIPELINE.md. Turns a stream of Attribution
+// Primitives over a settlement period into one signed, queryable
+// settlement record. Settlement is evidence, not payment: the economic
+// conversion (weight → currency) stays gateway-private. Reuses Build A
+// canonicalization and Build B weight formats; zero duplicate crypto.
+export { aggregateAttributionPrimitives, contributorLeafHashHex, formatSettlementWeight, residualLeafHashHex, } from './aggregate.js';
+export { buildContributorMerklePath, buildMerkleRoot, emptyAxisMerkleRoot, leafHash as settlementLeafHash, verifyMerklePath, } from './merkle.js';
+export { settlementRecordHash, settlementSigningPayload, signSettlementRecord, verifySettlementSignature, } from './sign.js';
+export { verifySettlementRecord } from './verify.js';
+export { buildContributorQueryResponse, verifyContributorQueryResponse, } from './contributor-query.js';
+//# sourceMappingURL=index.js.map

package/dist/src/v2/attribution-settlement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/v2/attribution-settlement/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,qDAAqD;AACrD,EAAE;AACF,sEAAsE;AACtE,iEAAiE;AACjE,uEAAuE;AACvE,uEAAuE;AACvE,sEAAsE;AActE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,mBAAmB,EACnB,QAAQ,IAAI,kBAAkB,EAC9B,gBAAgB,GACjB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,WAAW,CAAA;AAElB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAA"}

package/dist/src/v2/attribution-settlement/merkle.d.ts

@@ -0,0 +1,20 @@
+/** sha256(canonicalize(obj)) as raw 32 bytes. */
+export declare function leafHash(obj: unknown): Buffer;
+/** Build a balanced binary Merkle tree over arbitrary leaf hashes and
+ *  return the root as raw bytes. Odd levels duplicate the trailing node
+ *  (the standard fold convention). Throws on empty input — the caller is
+ *  responsible for using the empty-axis convention in that case. */
+export declare function buildMerkleRoot(leaves: Buffer[]): Buffer;
+/** Returns the sibling hashes (bottom-up) required to reconstruct the
+ *  root from `leaves[targetIndex]`. The returned hex strings are 32-byte
+ *  sha256 digests. Verification also needs the leaf index so the
+ *  verifier knows which side of each hashNode the sibling sits on —
+ *  {@link verifyMerklePath} takes that argument. */
+export declare function buildContributorMerklePath(leaves: Buffer[], targetIndex: number): string[];
+/** Reconstruct the Merkle root from (leaf, leafIndex, path) and compare
+ *  against `expectedRootHex`. Returns a boolean. Hex comparison is done
+ *  lowercase-insensitively. */
+export declare function verifyMerklePath(leaf: Buffer, leafIndex: number, path: string[], expectedRootHex: string): boolean;
+/** Convenience: the canonical empty-axis merkle root (I-C5). */
+export declare function emptyAxisMerkleRoot(): string;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/src/v2/attribution-settlement/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../../../../src/v2/attribution-settlement/merkle.ts"],"names":[],"mappings":"AAsBA,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE7C;AAED;;;oEAGoE;AACpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAexD;AAED;;;;oDAIoD;AACpD,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EAAE,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CA2BV;AAED;;+BAE+B;AAC/B,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,eAAe,EAAE,MAAM,GACtB,OAAO,CAaT;AAED,gEAAgE;AAChE,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}