@coderifts/agent-guard 3.0.1 → 4.0.0

package/dist/cjs/execution-proof.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Guard-produced execution proof block.
+ *
+ * Assembled ONLY from state the guard itself observed while handling a call. Callers cannot supply
+ * fields into this object: builders take GuardOutcome-internal facts, not a host "proof" option.
+ * The returned object is deeply frozen so post-return mutation of proof fields is rejected.
+ *
+ * What this block proves (when the corresponding fields are present):
+ *  - preflight happened          → preflighted + decision_id
+ *  - receipt was fresh           → receipt.status === 'VERIFIED_CURRENT' + expires_at
+ *  - scope matched               → binds_to.operation + currently_authorized
+ *  - ran on the guarded path     → execution.enforced === true (runtime-asserted only with
+ *                                  receipt.verified + preflighted; same invariant the types encode)
+ *  - artifact checked vs executed → change_fp is WHAT WAS CHECKED; execution_result_hash is NOT a
+ *                                  general claim that the applied side effect matched that fp
+ *
+ * What this block must never claim: that the change is safe, that the host cannot bypass the
+ * package, or that an absent field means compliance. Those limits are explicit on every block.
+ */
+import type { GuardVerdict } from './types.js';
+/** Machine-readable schema id for this block. */
+export declare const EXECUTION_PROOF_SPEC: "guard-execution-proof.v1";
+/**
+ * Hash of the factory return value — only when the value is already byte-stable.
+ *
+ * Not hashed (and the block says so) when:
+ *  - the factory did not run / threw / produced no result
+ *  - the result is an object, array, number, boolean, null, bigint, symbol, function — any of these
+ *    would require a serialization choice (key order, undefined, non-JSON values) that reformats
+ *    the value rather than hashing the bytes the factory returned
+ *
+ * A hash of a string/Buffer does NOT prove the contract artifacts applied match change_fp_checked.
+ * That gap is named on limits.
+ */
+export type ExecutionResultHash = {
+    status: 'hashed';
+    algorithm: 'sha256';
+    value: string;
+} | {
+    status: 'not_hashed';
+    reason: 'not_executed' | 'execution_threw' | 'result_not_byte_stable' | 'result_type_unsupported';
+};
+export type GuardExecutionProof = {
+    proof_spec: typeof EXECUTION_PROOF_SPEC;
+    /** Observed: true iff this call completed a preflight round-trip that produced a decision envelope. */
+    preflighted: boolean;
+    /** Observed from the decision envelope when preflighted; null otherwise. */
+    decision_id: string | null;
+    receipt: {
+        /**
+         * Observed: true only when the guard's verify+bind step branded the envelope
+         * (requires valid signature, status VERIFIED_CURRENT, body hash + fp + scope match).
+         */
+        verified: boolean;
+        /**
+         * Observed derivation: bind requires status === 'VERIFIED_CURRENT', so verified ⇒ this value.
+         * null when the receipt was not verified (or no receipt path).
+         */
+        status: 'VERIFIED_CURRENT' | null;
+        /** Observed from the envelope when present; null when no envelope. */
+        expires_at: string | null;
+    };
+    /**
+     * Observed from the authenticated envelope fields when an envelope exists.
+     * change_fp is the fingerprint of WHAT WAS CHECKED (preflighted), not of what the factory applied.
+     * null when no envelope (SKIPPED / unavailable without envelope).
+     */
+    binds_to: {
+        operation: string | null;
+        change_fp: string | null;
+    } | null;
+    /**
+     * Observed at verify time: true iff receipt.verified (VERIFIED_CURRENT + bind).
+     * false when an envelope/receipt was present but did not verify.
+     * null when there was no receipt path to evaluate (SKIPPED, no envelope).
+     */
+    currently_authorized: boolean | null;
+    execution: {
+        attempted: boolean;
+        executed: boolean;
+        enforced: boolean;
+    };
+    /**
+     * Observed: kind of the guard verdict that produced this outcome.
+     * On a blocked call this is how the block is named (BLOCK / APPROVAL / UNAVAILABLE / …).
+     */
+    verdict_kind: string;
+    execution_result_hash: ExecutionResultHash;
+    /**
+     * Explicit non-claims. Readers that treat missing fields as "ok" are wrong; these are always set.
+     */
+    limits: {
+        does_not_claim_change_safe: true;
+        does_not_claim_host_cannot_bypass: true;
+        does_not_claim_absent_field_is_compliance: true;
+        change_fp_is_what_was_checked_not_what_executed: true;
+        calls_outside_guarded_path_invisible: true;
+        execution_result_hash_is_not_artifact_match_proof: true;
+    };
+};
+export type ProofBuildInput = {
+    preflighted: boolean;
+    executionAttempted: boolean;
+    executed: boolean;
+    enforced: boolean;
+    verdict: GuardVerdict;
+    /** Present only when executed:true (factory returned). */
+    result?: unknown;
+    /** Present only when factory threw. */
+    error?: unknown;
+};
+/**
+ * Runtime twin of the type-level enforced⟺receiptVerified invariant.
+ * Throws if enforced:true is paired with anything other than receiptVerified+preflighted.
+ * The proof block is read by consumers that do not have our TypeScript brands.
+ */
+export declare function assertEnforcedReceiptInvariant(input: {
+    enforced: boolean;
+    preflighted: boolean;
+    receiptVerified: boolean;
+}): void;
+/**
+ * Honest byte hash of a factory return. Only string / Buffer / Uint8Array are hashed as raw bytes.
+ * Everything else is not_hashed with an explicit reason — never a JSON reformat hash.
+ */
+export declare function hashExecutionResult(result: unknown): ExecutionResultHash;
+/**
+ * Build the proof block from guard-observed outcome facts only.
+ * Never accepts a caller-supplied proof object or partial field map.
+ */
+export declare function buildExecutionProof(input: ProofBuildInput): GuardExecutionProof;
+//# sourceMappingURL=execution-proof.d.ts.map

package/dist/cjs/execution-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-proof.d.ts","sourceRoot":"","sources":["../../src/execution-proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,EAAG,0BAAmC,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxD;IACE,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EACF,cAAc,GACd,iBAAiB,GACjB,wBAAwB,GACxB,yBAAyB,CAAC;CAC/B,CAAC;AAEN,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,OAAO,oBAAoB,CAAC;IACxC,uGAAuG;IACvG,WAAW,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE;QACP;;;WAGG;QACH,QAAQ,EAAE,OAAO,CAAC;QAClB;;;WAGG;QACH,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;QAClC,sEAAsE;QACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;IACF;;;;OAIG;IACH,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,GAAG,IAAI,CAAC;IACT;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE;QACT,SAAS,EAAE,OAAO,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,EAAE,mBAAmB,CAAC;IAC3C;;OAEG;IACH,MAAM,EAAE;QACN,0BAA0B,EAAE,IAAI,CAAC;QACjC,iCAAiC,EAAE,IAAI,CAAC;QACxC,yCAAyC,EAAE,IAAI,CAAC;QAChD,+CAA+C,EAAE,IAAI,CAAC;QACtD,oCAAoC,EAAE,IAAI,CAAC;QAC3C,iDAAiD,EAAE,IAAI,CAAC;KACzD,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAWF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;CAC1B,GAAG,IAAI,CAQP;AA0BD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,mBAAmB,CAuBxE;AAeD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAsD/E"}

package/dist/cjs/execution-proof.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Guard-produced execution proof block.
+ *
+ * Assembled ONLY from state the guard itself observed while handling a call. Callers cannot supply
+ * fields into this object: builders take GuardOutcome-internal facts, not a host "proof" option.
+ * The returned object is deeply frozen so post-return mutation of proof fields is rejected.
+ *
+ * What this block proves (when the corresponding fields are present):
+ *  - preflight happened          → preflighted + decision_id
+ *  - receipt was fresh           → receipt.status === 'VERIFIED_CURRENT' + expires_at
+ *  - scope matched               → binds_to.operation + currently_authorized
+ *  - ran on the guarded path     → execution.enforced === true (runtime-asserted only with
+ *                                  receipt.verified + preflighted; same invariant the types encode)
+ *  - artifact checked vs executed → change_fp is WHAT WAS CHECKED; execution_result_hash is NOT a
+ *                                  general claim that the applied side effect matched that fp
+ *
+ * What this block must never claim: that the change is safe, that the host cannot bypass the
+ * package, or that an absent field means compliance. Those limits are explicit on every block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXECUTION_PROOF_SPEC = void 0;
+exports.assertEnforcedReceiptInvariant = assertEnforcedReceiptInvariant;
+exports.hashExecutionResult = hashExecutionResult;
+exports.buildExecutionProof = buildExecutionProof;
+const node_crypto_1 = require("node:crypto");
+/** Machine-readable schema id for this block. */
+exports.EXECUTION_PROOF_SPEC = 'guard-execution-proof.v1';
+const LIMITS = Object.freeze({
+    does_not_claim_change_safe: true,
+    does_not_claim_host_cannot_bypass: true,
+    does_not_claim_absent_field_is_compliance: true,
+    change_fp_is_what_was_checked_not_what_executed: true,
+    calls_outside_guarded_path_invisible: true,
+    execution_result_hash_is_not_artifact_match_proof: true,
+});
+/**
+ * Runtime twin of the type-level enforced⟺receiptVerified invariant.
+ * Throws if enforced:true is paired with anything other than receiptVerified+preflighted.
+ * The proof block is read by consumers that do not have our TypeScript brands.
+ */
+function assertEnforcedReceiptInvariant(input) {
+    if (input.enforced === true) {
+        if (input.preflighted !== true || input.receiptVerified !== true) {
+            throw new Error('@coderifts/agent-guard: enforced:true without receiptVerified+preflighted (runtime invariant)');
+        }
+    }
+}
+function receiptVerifiedOf(verdict) {
+    if ('receiptVerified' in verdict && typeof verdict.receiptVerified === 'boolean') {
+        return verdict.receiptVerified === true;
+    }
+    return false;
+}
+function envelopeOf(verdict) {
+    if ('envelope' in verdict && verdict.envelope && typeof verdict.envelope === 'object') {
+        return verdict.envelope;
+    }
+    return null;
+}
+/**
+ * Honest byte hash of a factory return. Only string / Buffer / Uint8Array are hashed as raw bytes.
+ * Everything else is not_hashed with an explicit reason — never a JSON reformat hash.
+ */
+function hashExecutionResult(result) {
+    if (typeof result === 'string') {
+        return {
+            status: 'hashed',
+            algorithm: 'sha256',
+            value: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(result, 'utf8').digest('hex'),
+        };
+    }
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(result)) {
+        return {
+            status: 'hashed',
+            algorithm: 'sha256',
+            value: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(result).digest('hex'),
+        };
+    }
+    if (result instanceof Uint8Array) {
+        return {
+            status: 'hashed',
+            algorithm: 'sha256',
+            value: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(result).digest('hex'),
+        };
+    }
+    return { status: 'not_hashed', reason: 'result_not_byte_stable' };
+}
+function executionResultHashOf(input) {
+    if (input.executionAttempted && !input.executed && 'error' in input && input.error !== undefined) {
+        return { status: 'not_hashed', reason: 'execution_threw' };
+    }
+    if (!input.executed) {
+        return { status: 'not_hashed', reason: 'not_executed' };
+    }
+    if (!('result' in input)) {
+        return { status: 'not_hashed', reason: 'result_type_unsupported' };
+    }
+    return hashExecutionResult(input.result);
+}
+/**
+ * Build the proof block from guard-observed outcome facts only.
+ * Never accepts a caller-supplied proof object or partial field map.
+ */
+function buildExecutionProof(input) {
+    const receiptVerified = receiptVerifiedOf(input.verdict);
+    assertEnforcedReceiptInvariant({
+        enforced: input.enforced,
+        preflighted: input.preflighted,
+        receiptVerified,
+    });
+    const env = envelopeOf(input.verdict);
+    const hasEnvelope = env !== null;
+    let decision_id = null;
+    let expires_at = null;
+    let binds_to = null;
+    if (hasEnvelope && env) {
+        decision_id = typeof env.decision_id === 'string' ? env.decision_id : null;
+        expires_at = typeof env.expires_at === 'string' ? env.expires_at : null;
+        binds_to = Object.freeze({
+            operation: typeof env.operation === 'string' ? env.operation : null,
+            change_fp: typeof env.fingerprint === 'string' ? env.fingerprint : null,
+        });
+    }
+    // currently_authorized: only evaluable when a receipt path existed.
+    // verified ⇒ true (bind required VERIFIED_CURRENT). envelope present but not verified ⇒ false.
+    // no envelope (SKIPPED / some UNAVAILABLE) ⇒ null.
+    let currently_authorized = null;
+    if (hasEnvelope) {
+        currently_authorized = receiptVerified;
+    }
+    const proof = {
+        proof_spec: exports.EXECUTION_PROOF_SPEC,
+        preflighted: input.preflighted === true,
+        decision_id,
+        receipt: Object.freeze({
+            verified: receiptVerified,
+            status: receiptVerified ? 'VERIFIED_CURRENT' : null,
+            expires_at,
+        }),
+        binds_to: binds_to ? Object.freeze(binds_to) : null,
+        currently_authorized,
+        execution: Object.freeze({
+            attempted: input.executionAttempted === true,
+            executed: input.executed === true,
+            enforced: input.enforced === true,
+        }),
+        verdict_kind: typeof input.verdict?.kind === 'string' ? input.verdict.kind : 'UNKNOWN',
+        execution_result_hash: Object.freeze(executionResultHashOf(input)),
+        limits: LIMITS,
+    };
+    return freezeProof(proof);
+}
+function freezeProof(p) {
+    return Object.freeze(p);
+}
+//# sourceMappingURL=execution-proof.js.map

package/dist/cjs/execution-proof.js.map

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

package/dist/cjs/freshness.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Freshness-safe prior content — PURE comparison core (TOCTOU close for the fresh-snapshot conjunct).
+ *
+ * Settled decisions (do not relitigate):
+ *   1. Freshness is CONTENT IDENTITY, not time. No TTL. Byte identity of `before` vs gate-time resolve.
+ *   2. The caller NAMES (artifact id); the gate RESOLVES prior content. A caller-supplied `before`
+ *      is a claim, not a measurement — no fallback ladder that relabels a guess as measured.
+ *   3. Four outcomes, never collapsed: TARGET_MUTATED | STALE_CONTEXT | TAMPERED | UNKNOWN_FRESHNESS.
+ *   4. STALE_CONTEXT fails closed by default; policy may opt out deliberately.
+ *   5. Tree hash is OPTIONAL in the binding. Without it, STALE_CONTEXT is skipped, TARGET_MUTATED
+ *      still runs, and the result SAYS the reduced level (never silently pretends full check ran).
+ *
+ * Merge-gate pattern generalized: recompute from current inputs; compare to what preflight bound;
+ * do not trust a claim about itself. Tree hash stays OUT of verdict_fingerprint and input_fingerprint
+ * (those preimages are frozen — their frozenness is what makes recompute meaningful).
+ *
+ * PURE: no I/O, no network, no Date.now(). Host supplies resolved content as inputs.
+ */
+/**
+ * Four outcomes. Callers distinguish them by the `outcome` field (never by message text alone).
+ *
+ *   TARGET_MUTATED     — the contract `before` bytes moved (field removal, type change, …)
+ *   STALE_CONTEXT      — repository path-set tree moved, contract `before` identical (e.g. format-only
+ *                        neighbouring files, or raw blob change with same contract content). Message
+ *                        MUST state this is not tampering.
+ *   TAMPERED           — contract moved AND tree moved (both axes disagree)
+ *   UNKNOWN_FRESHNESS  — a candidate was named, but current state is not measurable (missing resolve)
+ *
+ * Plus FRESH when both applicable axes match.
+ */
+export type FreshnessOutcome = 'FRESH' | 'TARGET_MUTATED' | 'STALE_CONTEXT' | 'TAMPERED' | 'UNKNOWN_FRESHNESS';
+/**
+ * Which axes were eligible to run.
+ *   full           — tree hash was bound; contract + tree both evaluated
+ *   contract_only  — no tree hash on the binding; only TARGET_MUTATED axis ran (reported, not silent)
+ */
+export type FreshnessCheckLevel = 'full' | 'contract_only';
+export type FreshnessAssessInput = {
+    /**
+     * Contract `before` that entered preflight (and thus digests / the decision). Bound measurement —
+     * not a host claim at execute time.
+     */
+    preflightBefore: string;
+    /**
+     * Gate-resolved prior content for the same artifact id NOW.
+     * null/undefined = current state not measurable → UNKNOWN_FRESHNESS.
+     * The gate (or host adapter feeding the gate) supplies this by resolving the caller's artifact id;
+     * a caller-supplied `before` string must NOT be passed here as if measured.
+     */
+    resolvedBeforeNow: string | null | undefined;
+    /**
+     * Optional tree commitment bound at preflight (additive; NOT in input_fingerprint / verdict_fp).
+     * Absent/empty → level is contract_only; STALE_CONTEXT axis is skipped.
+     */
+    preflightTreeHash?: string | null;
+    /**
+     * Tree commitment recomputed at gate time from the same path set + current blobs.
+     * Only consulted when preflightTreeHash is present.
+     * null/undefined when tree was bound but cannot be re-measured → UNKNOWN_FRESHNESS.
+     */
+    resolvedTreeHashNow?: string | null | undefined;
+    /**
+     * Policy opt-out for STALE_CONTEXT only (default false = fail closed).
+     * TARGET_MUTATED / TAMPERED / UNKNOWN_FRESHNESS are never opted out by this flag.
+     * Same shape as an explicit team choice (approver allowlist): say so deliberately.
+     */
+    allowStaleContext?: boolean;
+};
+export type FreshnessAssessResult = {
+    outcome: FreshnessOutcome;
+    /** Which axes ran. Always set — even on FRESH — so a reduced check cannot look like a full one. */
+    level: FreshnessCheckLevel;
+    /** True when the gate must refuse enforced execution. */
+    failClosed: boolean;
+    /** Contract before bytes match (only meaningful when resolvedBeforeNow was measurable). */
+    contractMatch: boolean | null;
+    /** Tree match; null when tree axis skipped or unmeasurable. */
+    treeMatch: boolean | null;
+    /**
+     * Human message. For STALE_CONTEXT always includes that this is not tampering.
+     * Machine consumers should branch on `outcome`, not parse the message.
+     */
+    message: string;
+};
+/**
+ * Write-style call: path + new content only is the shape the composition residual names.
+ * Gateable requires an artifact identifier the gate can resolve — not a caller-supplied before.
+ */
+export type WriteStylePriorInput = {
+    /** Artifact id from a prior preflight artifacts[] entry (caller names; gate resolves). */
+    artifactId?: string | null;
+    path?: string | null;
+    /** New content (the write payload). */
+    after?: string | null;
+    /**
+     * If present, this is a CLAIM. It is never treated as a measurement and never substitutes
+     * for artifactId. Recorded only so tests can assert there is no "use claimed before" ladder.
+     */
+    claimedBefore?: string | null;
+};
+export type WriteStylePriorResult = {
+    gateable: boolean;
+    reason: 'ok' | 'MISSING_ARTIFACT_ID' | 'CLAIMED_BEFORE_NOT_MEASUREMENT';
+    message: string;
+    /** Always false — claimedBefore is never elevated to a measurement. */
+    claimedBeforeAcceptedAsMeasurement: false;
+};
+/** Byte identity of two content strings (freshness definition: not time, not TTL). */
+export declare function contentByteIdentical(a: string, b: string): boolean;
+/**
+ * Optional path-set tree commitment. Additive only — never fold into input_fingerprint or
+ * verdict_fingerprint. Preimage: sorted path + sha256(content), then outer sha256.
+ * Missing content for a path is the caller's problem: pass only complete pairs.
+ */
+export declare function computePathSetTreeHash(entries: ReadonlyArray<{
+    path: string;
+    content: string;
+}>): string;
+/**
+ * Assess freshness of prior content by recompute-and-compare (merge-gate pattern generalized).
+ *
+ * Pure. Does not read the filesystem; the host/adapter resolves artifact id → content and passes
+ * `resolvedBeforeNow` / optional tree hashes as inputs.
+ */
+export declare function assessFreshness(input: FreshnessAssessInput): FreshnessAssessResult;
+/**
+ * Write-style prior requirements (Decision 2).
+ * Caller must supply artifactId. claimedBefore is never accepted as measurement.
+ */
+export declare function assessWriteStylePrior(input: WriteStylePriorInput): WriteStylePriorResult;
+/**
+ * Convenience: whether enforced execution is allowed for this freshness result.
+ * Equivalent to !failClosed: FRESH always; STALE_CONTEXT only when the team opted out;
+ * TARGET_MUTATED / TAMPERED / UNKNOWN never.
+ */
+export declare function freshnessAllowsEnforce(result: FreshnessAssessResult): boolean;
+/**
+ * Whether a resolver ran for THIS call.
+ *   ACTIVE         — resolver was supplied and returned content for at least one artifact id
+ *   NOT_CONFIGURED — no resolver on the host config; we never attempted measurement
+ *   DEGRADED       — resolver was supplied and threw, or returned nothing usable
+ *
+ * NOT_CONFIGURED ≠ UNKNOWN_FRESHNESS. The latter is an assessFreshness outcome after a measurement
+ * was attempted with empty/unusable resolved content under ACTIVE wiring.
+ */
+export type FreshnessWiringState = 'ACTIVE' | 'NOT_CONFIGURED' | 'DEGRADED';
+export type FreshnessDegradeReason = 'resolver_threw' | 'resolver_returned_empty' | 'resolver_returned_non_string';
+/**
+ * Per-call forensic basis. Rides on the GuardOutcome so a receipt chain audited later can see,
+ * call by call, whether the check ran — not only a composition-level "wired?" flag.
+ */
+export type FreshnessBasis = {
+    wiring: FreshnessWiringState;
+    /** Present when wiring === ACTIVE and assessFreshness ran against preflight before. */
+    assessment?: FreshnessAssessResult;
+    /** Present when wiring === DEGRADED — never report DEGRADED as NOT_CONFIGURED. */
+    degrade?: {
+        reason: FreshnessDegradeReason;
+        detail?: string;
+    };
+    /**
+     * Whether this call was treated as write-style (path + new content / needs prior resolve).
+     * Forensic: opt-out on a write is not silent.
+     */
+    write_style: boolean;
+    /** Config requireFreshness for this call (policy). */
+    require_freshness: boolean;
+};
+/** Host callback: artifact id → current prior content. Async I/O lives here — never inside assessFreshness. */
+export type PriorContentResolver = (req: {
+    artifactId: string;
+    path?: string;
+    toolName: string;
+}) => Promise<string | null | undefined> | string | null | undefined;
+/**
+ * Values the RUNNER collected before entering the pure guard path.
+ * The guard never invokes the resolver; it only consumes these values.
+ */
+export type FreshnessCallContext = {
+    wiring: FreshnessWiringState;
+    /** artifactId → resolved current before (only when wiring ACTIVE or partial DEGRADED with empties) */
+    priorResolved?: Record<string, string | null | undefined>;
+    degrade?: {
+        reason: FreshnessDegradeReason;
+        detail?: string;
+    };
+};
+/**
+ * Detect write-style: contract-relevant path present, but no both-side artifacts on the descriptor.
+ * (edits[]/old_string+new_string binders already lift both sides — those are not write-style.)
+ */
+export declare function isWriteStyleCall(call: {
+    artifacts?: ReadonlyArray<{
+        before?: unknown;
+        after?: unknown;
+    }> | undefined;
+    arguments?: unknown;
+    filesTouched?: string[];
+}): boolean;
+/** Artifact ids the runner should ask the host to resolve (from lifted artifacts or path-derived id). */
+export declare function artifactIdsForResolve(call: {
+    toolName?: string;
+    artifacts?: ReadonlyArray<{
+        id?: unknown;
+    }> | undefined;
+    arguments?: unknown;
+}): string[];
+/**
+ * RUNNER-side collection. Invokes the host resolver (async I/O). Never call from pure assessFreshness.
+ * - no resolver → NOT_CONFIGURED (did not try)
+ * - resolver throws → DEGRADED (opted in, failed)
+ * - resolver returns empty/non-string for all ids → DEGRADED
+ * - otherwise ACTIVE with priorResolved map
+ */
+export declare function collectFreshnessCallContext(input: {
+    call: {
+        toolName: string;
+        artifacts?: ReadonlyArray<{
+            id?: unknown;
+            before?: unknown;
+        }> | undefined;
+        arguments?: unknown;
+    };
+    resolvePriorContent?: PriorContentResolver | null;
+}): Promise<FreshnessCallContext>;
+/**
+ * Build the per-call basis and optional enforce block reason from context + preflight artifacts.
+ * Pure once priorResolved is a value (no I/O).
+ */
+export declare function buildFreshnessBasis(input: {
+    writeStyle: boolean;
+    requireFreshness: boolean;
+    ctx: FreshnessCallContext;
+    /** Preflight-bound before per artifact id (from call.artifacts after detect/bind). */
+    preflightBeforeById?: Record<string, string>;
+    allowStaleContext?: boolean;
+    preflightTreeHash?: string | null;
+    resolvedTreeHashNow?: string | null;
+}): {
+    basis: FreshnessBasis;
+    /** If set, enforced execution must not proceed (permission fail-closed). */
+    blockCause?: 'FRESHNESS_REQUIRED' | 'FRESHNESS_FAILED';
+};
+//# sourceMappingURL=freshness.d.ts.map

package/dist/cjs/freshness.d.ts.map

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