@vauban-org/agent-sdk 0.16.0

package/dist/privacy/uar.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Universal Anonymity Root (UAR) contribution — agent anchor commitments.
+ *
+ * Implements checkpoint 5 of sprint-576:agentic-privacy-impl (ORQ-4):
+ * - `contributeAnchorToUAR(agentClaim, holderBlinding)` produces a UAR leaf
+ *   commitment for the `agentic` domain.
+ * - Anchor: `poseidon2(domain_tag, agentNullifier, holderBlinding)` per ORQ-4 §3.2.
+ * - Epoch-stamped for freshness tracking (per-presentation linkability mitigation).
+ * - Mock submit to UAR aggregator (no network I/O in this slice).
+ *
+ * Cross-agent unlinkability (ORQ-4 G5):
+ *   Two agents presenting to the same verifier produce different leaves because:
+ *   - Different `agentNullifier` → different `domain_specific_anchor`.
+ *   - Same holder may use different `holderBlinding` per presentation → different leaf.
+ *   An observer sees only `anchor_commitment` and cannot link across domains or agents.
+ *
+ * References:
+ *   - vauban-privacy-protocol/docs/research/10-orq-cross-domain-anon.md §3.2-§3.3
+ *   - docs/research/03-agentic-privacy.md §2 (agent nullifier hierarchy)
+ *
+ * @module privacy/uar
+ */
+import type { AgentClaim } from "./composition.js";
+/**
+ * Domain tag for agentic leaves in the UAR.
+ * Per ORQ-4 §3.3 projection rules.
+ *
+ * Matches the canonical tag used by the Rust UAR aggregator
+ * (`vauban-domain-agentic-v1`).
+ */
+export declare const UAR_DOMAIN_TAG_AGENTIC: bigint;
+/**
+ * Sentinel domain tags for other Vauban domains (domain separation reference).
+ * These are NOT produced by this module — listed for separation verification in tests.
+ */
+export declare const UAR_DOMAIN_TAG_STARKNET: bigint;
+export declare const UAR_DOMAIN_TAG_W3C_VC: bigint;
+export declare const UAR_DOMAIN_TAG_MDOC: bigint;
+/**
+ * A single UAR leaf contributed by an agentic claim.
+ *
+ * Per ORQ-4 §3.2:
+ *   anchor_commitment = poseidon2(domain_tag, domain_specific_anchor, holder_blinding)
+ *
+ * For the agentic domain:
+ *   domain_specific_anchor = agentNullifier (the HDNT nullifier for the agent)
+ *   domain_tag             = UAR_DOMAIN_TAG_AGENTIC
+ */
+export interface UARLeaf {
+    /**
+     * Domain tag felt252 — identifies the `agentic` domain in the UAR.
+     * Public: verifier knows which domain the leaf came from.
+     */
+    domainTag: bigint;
+    /**
+     * Blinded anchor commitment.
+     * anchor = poseidon2(domainTag, agentNullifier, holderBlinding)
+     *
+     * The holderBlinding is NEVER revealed — the leaf is indistinguishable
+     * from leaves contributed by other agents or other domains.
+     */
+    anchor: bigint;
+    /**
+     * Epoch number when this leaf was produced.
+     * Epoch = Math.floor(Date.now() / 3600_000) — hourly cadence per ORQ-4 §3.4.
+     *
+     * Freshness: verifiers accept leaves within a configurable window (default 24h = 24 epochs).
+     */
+    epoch: number;
+    /**
+     * The role of the contributing agent (informational, not included in anchor hash).
+     * Helps the holder track which agent contributed which leaf.
+     * NOT published to the UAR aggregator — local metadata only.
+     */
+    agentRole: string;
+}
+/**
+ * Mock submit result from the UAR aggregator.
+ *
+ * Phase 1 is a mock — no network I/O. Phase 1.5+ will wire to the real
+ * off-chain aggregator service (separate ADR-ECO).
+ *
+ * The `leafIndex` is a deterministic mock index derived from the anchor
+ * commitment to keep tests reproducible.
+ */
+export interface UARAggregatorReceipt {
+    /** The submitted anchor commitment. */
+    anchor: bigint;
+    /** Epoch of submission. */
+    epoch: number;
+    /**
+     * Mock leaf index in the Sparse Merkle Tree (depth 64).
+     * Phase 1: derived from anchor via felt-mod to [0, 2^32) for tractability.
+     * Phase 2+: real SMT path from the aggregator.
+     */
+    leafIndex: bigint;
+    /**
+     * Whether the leaf was accepted (always true in mock).
+     * Phase 2+: false if epoch is stale or anchor is malformed.
+     */
+    accepted: boolean;
+}
+/**
+ * Contribute an agent's HDNT nullifier to the Universal Anonymity Root (UAR).
+ *
+ * Computes the UAR leaf commitment per ORQ-4 §3.2:
+ *   anchor = poseidon2(domain_tag, agentNullifier, holderBlinding)
+ *
+ * The `holderBlinding` is a 32-byte random felt (felt252 BigInt) chosen by
+ * the holder. It MUST be:
+ *   - Freshly generated per leaf contribution (never reused across presentations).
+ *   - Secret: never revealed to the verifier or the UAR aggregator.
+ *   - Derived from the holder's secret key (e.g., Poseidon(masterKey, epoch, role)).
+ *
+ * **Cross-agent unlinkability**: Two agents with different `agentNullifier`
+ * values produce different `anchor` values even with the same `holderBlinding`,
+ * because `agentNullifier` is part of the Poseidon preimage. Conversely, the
+ * same agent with different `holderBlinding` values produces different anchors,
+ * preventing cross-presentation correlation.
+ *
+ * @param agentClaim     - AgentClaim whose nullifier contributes the leaf.
+ * @param holderBlinding - 32-byte random felt (felt252 BigInt). Secret.
+ * @returns UARLeaf — the commitment, epoch, and domain metadata.
+ */
+export declare function contributeAnchorToUAR(agentClaim: AgentClaim, holderBlinding: bigint): UARLeaf;
+/**
+ * Mock-submit a UAR leaf to the off-chain aggregator service.
+ *
+ * Phase 1: no network I/O. Returns a deterministic mock receipt.
+ * Phase 1.5+: replace body with HTTP POST to the aggregator endpoint.
+ *
+ * The aggregator would:
+ *   1. Validate the anchor commitment format (felt252 in range).
+ *   2. Verify the epoch is within the freshness window.
+ *   3. Insert the leaf into the SMT at `leafIndex`.
+ *   4. Return the SMT root update (deferred to Phase 2).
+ *
+ * TODO (Phase 1.5): Replace mock with real aggregator HTTP call.
+ *
+ * @param leaf - UARLeaf to submit.
+ * @returns UARAggregatorReceipt with mock leaf index.
+ */
+export declare function mockSubmitToUAR(leaf: UARLeaf): UARAggregatorReceipt;
+/**
+ * Verify that a UAR leaf is fresh (within the given window).
+ *
+ * A leaf is fresh if its epoch is within `maxEpochAge` epochs of the current
+ * epoch. Default window: 24 epochs = 24 hours (per ORQ-4 §4.4).
+ *
+ * @param leaf         - UARLeaf to verify.
+ * @param maxEpochAge  - Maximum allowed epoch age (default 24).
+ * @returns true if the leaf is within the freshness window.
+ */
+export declare function isLeafFresh(leaf: UARLeaf, maxEpochAge?: number): boolean;
+/**
+ * Contribute multiple agent claims to the UAR, returning one leaf per claim.
+ *
+ * Each leaf uses the SAME `holderBlinding` — the caller must provide a
+ * separate blinding per claim for maximum privacy. This helper is a
+ * convenience for bulk contribution with a single blinding (e.g., for tests).
+ *
+ * For production use, derive per-leaf blindings:
+ *   blinding_i = Poseidon(masterKey, epoch, role_i)
+ *
+ * @param agentClaims    - Array of AgentClaims to contribute.
+ * @param holderBlinding - Shared blinding (use per-leaf blindings in production).
+ * @returns Array of UARLeaf, one per claim.
+ */
+export declare function contributeMultipleAnchors(agentClaims: AgentClaim[], holderBlinding: bigint): UARLeaf[];
+//# sourceMappingURL=uar.d.ts.map

package/dist/privacy/uar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uar.d.ts","sourceRoot":"","sources":["../../src/privacy/uar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAA0C,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAyD,CAAC;AAC9F,eAAO,MAAM,qBAAqB,QAAyC,CAAC;AAC5E,eAAO,MAAM,mBAAmB,QAAgD,CAAC;AAIjF;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAyBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAa7F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,oBAAoB,CAOnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,SAAK,GAAG,OAAO,CAGpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,UAAU,EAAE,EACzB,cAAc,EAAE,MAAM,GACrB,OAAO,EAAE,CAEX"}

package/dist/privacy/uar.js

@@ -0,0 +1,150 @@
+/**
+ * Universal Anonymity Root (UAR) contribution — agent anchor commitments.
+ *
+ * Implements checkpoint 5 of sprint-576:agentic-privacy-impl (ORQ-4):
+ * - `contributeAnchorToUAR(agentClaim, holderBlinding)` produces a UAR leaf
+ *   commitment for the `agentic` domain.
+ * - Anchor: `poseidon2(domain_tag, agentNullifier, holderBlinding)` per ORQ-4 §3.2.
+ * - Epoch-stamped for freshness tracking (per-presentation linkability mitigation).
+ * - Mock submit to UAR aggregator (no network I/O in this slice).
+ *
+ * Cross-agent unlinkability (ORQ-4 G5):
+ *   Two agents presenting to the same verifier produce different leaves because:
+ *   - Different `agentNullifier` → different `domain_specific_anchor`.
+ *   - Same holder may use different `holderBlinding` per presentation → different leaf.
+ *   An observer sees only `anchor_commitment` and cannot link across domains or agents.
+ *
+ * References:
+ *   - vauban-privacy-protocol/docs/research/10-orq-cross-domain-anon.md §3.2-§3.3
+ *   - docs/research/03-agentic-privacy.md §2 (agent nullifier hierarchy)
+ *
+ * @module privacy/uar
+ */
+import { feltMod, labelToFelt, poseidonHashBigInt } from "./poseidon-felt252.js";
+// ─── Domain tags ──────────────────────────────────────────────────────────────
+/**
+ * Domain tag for agentic leaves in the UAR.
+ * Per ORQ-4 §3.3 projection rules.
+ *
+ * Matches the canonical tag used by the Rust UAR aggregator
+ * (`vauban-domain-agentic-v1`).
+ */
+export const UAR_DOMAIN_TAG_AGENTIC = labelToFelt("vauban-domain-agentic-v1");
+/**
+ * Sentinel domain tags for other Vauban domains (domain separation reference).
+ * These are NOT produced by this module — listed for separation verification in tests.
+ */
+export const UAR_DOMAIN_TAG_STARKNET = labelToFelt("vauban-domain-starknet-shieldedvault-v1");
+export const UAR_DOMAIN_TAG_W3C_VC = labelToFelt("vauban-domain-w3c-vc-v1");
+export const UAR_DOMAIN_TAG_MDOC = labelToFelt("vauban-domain-iso18013-mdoc-v1");
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Current epoch number (hourly cadence).
+ * Epoch = Math.floor(Date.now() / 3_600_000).
+ * Deterministic within a single hour — prevents timing-based linkability
+ * from sub-second clock differences.
+ */
+function currentEpoch() {
+    return Math.floor(Date.now() / 3_600_000);
+}
+/**
+ * Derive a mock leaf index from an anchor commitment.
+ * Deterministic: same anchor → same index. Phase 1 only.
+ */
+function mockLeafIndex(anchor) {
+    // Fold anchor into [0, 2^32) — deterministic, no RNG.
+    return anchor % 2n ** 32n;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Contribute an agent's HDNT nullifier to the Universal Anonymity Root (UAR).
+ *
+ * Computes the UAR leaf commitment per ORQ-4 §3.2:
+ *   anchor = poseidon2(domain_tag, agentNullifier, holderBlinding)
+ *
+ * The `holderBlinding` is a 32-byte random felt (felt252 BigInt) chosen by
+ * the holder. It MUST be:
+ *   - Freshly generated per leaf contribution (never reused across presentations).
+ *   - Secret: never revealed to the verifier or the UAR aggregator.
+ *   - Derived from the holder's secret key (e.g., Poseidon(masterKey, epoch, role)).
+ *
+ * **Cross-agent unlinkability**: Two agents with different `agentNullifier`
+ * values produce different `anchor` values even with the same `holderBlinding`,
+ * because `agentNullifier` is part of the Poseidon preimage. Conversely, the
+ * same agent with different `holderBlinding` values produces different anchors,
+ * preventing cross-presentation correlation.
+ *
+ * @param agentClaim     - AgentClaim whose nullifier contributes the leaf.
+ * @param holderBlinding - 32-byte random felt (felt252 BigInt). Secret.
+ * @returns UARLeaf — the commitment, epoch, and domain metadata.
+ */
+export function contributeAnchorToUAR(agentClaim, holderBlinding) {
+    const anchor = poseidonHashBigInt([
+        UAR_DOMAIN_TAG_AGENTIC,
+        feltMod(agentClaim.agentNullifier),
+        feltMod(holderBlinding),
+    ]);
+    return {
+        domainTag: UAR_DOMAIN_TAG_AGENTIC,
+        anchor,
+        epoch: currentEpoch(),
+        agentRole: agentClaim.role,
+    };
+}
+/**
+ * Mock-submit a UAR leaf to the off-chain aggregator service.
+ *
+ * Phase 1: no network I/O. Returns a deterministic mock receipt.
+ * Phase 1.5+: replace body with HTTP POST to the aggregator endpoint.
+ *
+ * The aggregator would:
+ *   1. Validate the anchor commitment format (felt252 in range).
+ *   2. Verify the epoch is within the freshness window.
+ *   3. Insert the leaf into the SMT at `leafIndex`.
+ *   4. Return the SMT root update (deferred to Phase 2).
+ *
+ * TODO (Phase 1.5): Replace mock with real aggregator HTTP call.
+ *
+ * @param leaf - UARLeaf to submit.
+ * @returns UARAggregatorReceipt with mock leaf index.
+ */
+export function mockSubmitToUAR(leaf) {
+    return {
+        anchor: leaf.anchor,
+        epoch: leaf.epoch,
+        leafIndex: mockLeafIndex(leaf.anchor),
+        accepted: true,
+    };
+}
+/**
+ * Verify that a UAR leaf is fresh (within the given window).
+ *
+ * A leaf is fresh if its epoch is within `maxEpochAge` epochs of the current
+ * epoch. Default window: 24 epochs = 24 hours (per ORQ-4 §4.4).
+ *
+ * @param leaf         - UARLeaf to verify.
+ * @param maxEpochAge  - Maximum allowed epoch age (default 24).
+ * @returns true if the leaf is within the freshness window.
+ */
+export function isLeafFresh(leaf, maxEpochAge = 24) {
+    const now = currentEpoch();
+    return now - leaf.epoch <= maxEpochAge;
+}
+/**
+ * Contribute multiple agent claims to the UAR, returning one leaf per claim.
+ *
+ * Each leaf uses the SAME `holderBlinding` — the caller must provide a
+ * separate blinding per claim for maximum privacy. This helper is a
+ * convenience for bulk contribution with a single blinding (e.g., for tests).
+ *
+ * For production use, derive per-leaf blindings:
+ *   blinding_i = Poseidon(masterKey, epoch, role_i)
+ *
+ * @param agentClaims    - Array of AgentClaims to contribute.
+ * @param holderBlinding - Shared blinding (use per-leaf blindings in production).
+ * @returns Array of UARLeaf, one per claim.
+ */
+export function contributeMultipleAnchors(agentClaims, holderBlinding) {
+    return agentClaims.map((claim) => contributeAnchorToUAR(claim, holderBlinding));
+}
+//# sourceMappingURL=uar.js.map

package/dist/privacy/uar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uar.js","sourceRoot":"","sources":["../../src/privacy/uar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC,0BAA0B,CAAC,CAAC;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC,yCAAyC,CAAC,CAAC;AAC9F,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC,yBAAyB,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC,gCAAgC,CAAC,CAAC;AAsEjF,iFAAiF;AAEjF;;;;;GAKG;AACH,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CAAC,MAAc;IACnC,sDAAsD;IACtD,OAAO,MAAM,GAAG,EAAE,IAAI,GAAG,CAAC;AAC5B,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAsB,EAAE,cAAsB;IAClF,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,sBAAsB;QACtB,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC;QAClC,OAAO,CAAC,cAAc,CAAC;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,SAAS,EAAE,sBAAsB;QACjC,MAAM;QACN,KAAK,EAAE,YAAY,EAAE;QACrB,SAAS,EAAE,UAAU,CAAC,IAAI;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC;QACrC,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,WAAW,GAAG,EAAE;IACzD,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,OAAO,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,WAAW,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACvC,WAAyB,EACzB,cAAsB;IAEtB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,qBAAqB,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;AAClF,CAAC"}

package/dist/prompts/build-orient-prompt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * buildOrientPrompt — generic OODA orient-phase prompt factory.
+ *
+ * Promoted from forge/src/agents/shared/orient-prompt.ts (Vague 1.B.5).
+ * Forge-specific fields (agentId, agentRole, outputSchema) have been replaced
+ * by generic opts so any SDK consumer can drive the orient phase.
+ *
+ * Hard cap: `userContext` is truncated to `maxContextChars` (default 2500)
+ * to stay within per-turn token budgets on M/L tasks.
+ *
+ * @public @since 0.18.0
+ */
+export interface BuildOrientPromptOpts {
+    /** System-level instructions for the LLM. */
+    systemPrompt: string;
+    /** User-facing context (observation, data, etc.) — capped to `maxContextChars`. */
+    userContext: string;
+    /**
+     * JSON Schema object injected into the system prompt when present.
+     * Tells the LLM which output shape is expected.
+     */
+    jsonSchema?: object;
+    /** Recent memory entries prepended as a bullet list. */
+    recentMemory?: string[];
+    /**
+     * Maximum characters for `userContext` before truncation.
+     * @default 2500
+     */
+    maxContextChars?: number;
+}
+/**
+ * Build the `{ system, user }` prompt pair for an OODA orient phase.
+ *
+ * The system prompt receives optional JSON Schema injection.
+ * The user prompt is capped at `maxContextChars` with a truncation indicator.
+ */
+export declare function buildOrientPrompt(opts: BuildOrientPromptOpts): {
+    system: string;
+    user: string;
+};
+//# sourceMappingURL=build-orient-prompt.d.ts.map

package/dist/prompts/build-orient-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-orient-prompt.d.ts","sourceRoot":"","sources":["../../src/prompts/build-orient-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAiCA"}

package/dist/prompts/build-orient-prompt.js

@@ -0,0 +1,40 @@
+/**
+ * buildOrientPrompt — generic OODA orient-phase prompt factory.
+ *
+ * Promoted from forge/src/agents/shared/orient-prompt.ts (Vague 1.B.5).
+ * Forge-specific fields (agentId, agentRole, outputSchema) have been replaced
+ * by generic opts so any SDK consumer can drive the orient phase.
+ *
+ * Hard cap: `userContext` is truncated to `maxContextChars` (default 2500)
+ * to stay within per-turn token budgets on M/L tasks.
+ *
+ * @public @since 0.18.0
+ */
+const DEFAULT_MAX_CONTEXT_CHARS = 2500;
+const TRUNCATION_MARKER = "[...truncated]";
+/**
+ * Build the `{ system, user }` prompt pair for an OODA orient phase.
+ *
+ * The system prompt receives optional JSON Schema injection.
+ * The user prompt is capped at `maxContextChars` with a truncation indicator.
+ */
+export function buildOrientPrompt(opts) {
+    const { systemPrompt, userContext, jsonSchema, recentMemory, maxContextChars = DEFAULT_MAX_CONTEXT_CHARS, } = opts;
+    // ── System prompt ────────────────────────────────────────────────────────────
+    const schemaBlock = jsonSchema !== undefined
+        ? `\n\nOutput JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`
+        : "";
+    const system = `${systemPrompt}${schemaBlock}`;
+    // ── User prompt ──────────────────────────────────────────────────────────────
+    const memoryBlock = recentMemory && recentMemory.length > 0
+        ? `Recent memory:\n${recentMemory.map((m) => `- ${m}`).join("\n")}`
+        : "";
+    // Truncate userContext if it exceeds the cap.
+    const cappedContext = userContext.length > maxContextChars
+        ? `${userContext.slice(0, maxContextChars)}${TRUNCATION_MARKER}`
+        : userContext;
+    const userParts = [memoryBlock, cappedContext].filter(Boolean);
+    const user = userParts.join("\n\n");
+    return { system, user };
+}
+//# sourceMappingURL=build-orient-prompt.js.map

package/dist/prompts/build-orient-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-orient-prompt.js","sourceRoot":"","sources":["../../src/prompts/build-orient-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,yBAAyB,GAAG,IAAI,CAAC;AACvC,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAqB3C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA2B;IAI3D,MAAM,EACJ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,eAAe,GAAG,yBAAyB,GAC5C,GAAG,IAAI,CAAC;IAET,gFAAgF;IAChF,MAAM,WAAW,GACf,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,4BAA4B,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QACnE,CAAC,CAAC,EAAE,CAAC;IAET,MAAM,MAAM,GAAG,GAAG,YAAY,GAAG,WAAW,EAAE,CAAC;IAE/C,gFAAgF;IAChF,MAAM,WAAW,GACf,YAAY,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;QACrC,CAAC,CAAC,mBAAmB,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACnE,CAAC,CAAC,EAAE,CAAC;IAET,8CAA8C;IAC9C,MAAM,aAAa,GACjB,WAAW,CAAC,MAAM,GAAG,eAAe;QAClC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,GAAG,iBAAiB,EAAE;QAChE,CAAC,CAAC,WAAW,CAAC;IAElB,MAAM,SAAS,GAAG,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEpC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC"}

package/dist/proof/chain.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ProofChain — tamper-evident SHA-256 step chain for TRACE_V1.
+ *
+ * Coexists with the legacy Poseidon proof system in `./poseidon.ts`.
+ * This module targets the TRACE_V1 schema (sprint-561:a2/a4).
+ *
+ * buildChain  — builds a ProofChain from a finalized Trace.
+ * verifyChain — runs 7 integrity checks (R8-M4, CH9, AR6).
+ *
+ * rootHash binding (CH9):
+ *   rootHash = sha256(canonical({
+ *     lastStepHash,
+ *     totalSteps,
+ *     configHash,    ← anti config-swap
+ *     agentId,
+ *     agentVersion,
+ *     runId,
+ *   }))
+ *
+ * All-zeros prevStepHash sentinel for step[0]:
+ *   "0000000000000000000000000000000000000000000000000000000000000000"
+ *
+ * @module proof/chain
+ */
+import type { Trace, TraceStep } from "../trace/schema.js";
+export interface ProofChainEntry {
+    /** Zero-based step index (mirrors TraceStep.index). */
+    index: number;
+    /** SHA-256(canonical({ ...step fields (excl. stepHash), runId })). */
+    stepHash: string;
+}
+export interface ProofChain {
+    /** Hash algorithm identifier. Always sha-256 in this schema version. */
+    algorithm: "sha-256";
+    /** One entry per step; ordered by index. */
+    entries: ProofChainEntry[];
+    /**
+     * SHA-256(canonical({ lastStepHash, totalSteps, configHash, agentId, agentVersion, runId })).
+     * Binds config, identity, and chain tail into a single commitment (CH9).
+     */
+    rootHash: string;
+}
+/**
+ * Discriminated union returned by verifyChain.
+ * R8-M4: receiptStatus propagated on BOTH branches when present.
+ */
+export type VerifyChainResult = {
+    valid: true;
+    receiptStatus?: "present" | "pending" | "failed";
+} | {
+    valid: false;
+    /** Zero-based index of the first tampered step, or -1 for structural errors. */
+    tamperedAt: number;
+    reason: string;
+    receiptStatus?: "present" | "pending" | "failed";
+};
+/** All-zeros sentinel for prevStepHash of the first step. */
+export declare const GENESIS_PREV_HASH = "0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * SHA-256(canonical({ ...step fields (excluding stepHash), runId })).
+ *
+ * The stepHash field itself is excluded from its own digest to avoid
+ * circular dependency. runId is included explicitly even though it is
+ * already a step field — this is intentional for AR6 clarity.
+ */
+export declare function computeStepHash(step: TraceStep, runId: string): Promise<string>;
+/**
+ * Build a ProofChain from a finalized Trace.
+ *
+ * Recomputes stepHash for every step to produce the entries array,
+ * then computes rootHash = sha256(canonical({ lastStepHash, totalSteps,
+ * configHash, agentId, agentVersion, runId })).
+ *
+ * @throws If the trace has no steps.
+ */
+export declare function buildChain(trace: Trace): Promise<ProofChain>;
+/**
+ * Verify a ProofChain against a Trace — 7 integrity checks.
+ *
+ * Checks (in order):
+ *   1. steps[i].index === i                    (monotone, anti-deletion)
+ *   2. steps.length === trace.totalSteps        (anti-truncation)
+ *   3. steps[i].runId === trace.runId for all i (anti-splice AR6)
+ *   4. recompute stepHash === step.stepHash     (data integrity)
+ *   5. steps[i].prevStepHash === steps[i-1].stepHash (chain linkage)
+ *   6. rootHash === recomputed rootHash         (root commitment CH9)
+ *   7. trace.configHash === sha256(canonical(trace.config)) (config anti-swap)
+ */
+export declare function verifyChain(trace: Trace, chain: ProofChain): Promise<VerifyChainResult>;
+//# sourceMappingURL=chain.d.ts.map

package/dist/proof/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/proof/chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK3D,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,SAAS,EAAE,SAAS,CAAC;IACrB,4CAA4C;IAC5C,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,KAAK,EAAE,IAAI,CAAC;IACZ,aAAa,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CAClD,GACD;IACE,KAAK,EAAE,KAAK,CAAC;IACb,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;CAClD,CAAC;AAIN,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,qEACsC,CAAC;AAIrE;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAQjB;AAID;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,CA0BlE;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,iBAAiB,CAAC,CAiG5B"}