@planu/cli 4.12.3 → 4.14.1

package/dist/engine/validation/validation-freshness.js

@@ -0,0 +1,427 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, watch } from 'node:fs';
+import { lstat, mkdir, open, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { ValidationReceiptStore } from './validation-receipt.js';
+import { isValidationSourcePath } from './validation-source-policy.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { gitSourceTreeDigest } from './durable-validation.js';
+const LEASE_TTL_MS = 35 * 60 * 1_000;
+const MAX_EVIDENCE_FILE_BYTES = 2 * 1024 * 1024;
+const FINGERPRINT_CHUNK_BYTES = 64 * 1024;
+const EVIDENCE_FILE = /^(?:discovery|task-plan|traceability-matrix|contract-validation-(?:api|graphql|event|ui|mcp))\.json$/u;
+const active = new Map();
+function key(projectId, specId) {
+    return `${projectId}:${specId}`;
+}
+function invalidateState(projectId, specId, state) {
+    const invalidating = state.invalidating.then(async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const database = __addDisposableResource(env_1, new RuntimeDatabase({ path: resolveStorageLayout().runtimeDatabase }), false);
+            const store = new ValidationReceiptStore({ database, workspaceId: 'global' });
+            await store.invalidateCurrentBindings(projectId, specId);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    });
+    return { ...state, generation: state.generation + 1, bindings: undefined, invalidating };
+}
+/**
+ * Invalidate the active validation lease for a spec.
+ *
+ * Filesystem watchers and Planu-owned writers share this entry point so callers
+ * that know they changed validation evidence do not depend on fs.watch timing.
+ */
+export function invalidateValidationFreshness(input) {
+    const identity = key(input.projectId, input.specId);
+    const state = active.get(identity);
+    if (!state) {
+        return false;
+    }
+    active.set(identity, invalidateState(input.projectId, input.specId, state));
+    return true;
+}
+function startWatch(path, relevant, onRelevantChange, onError) {
+    try {
+        const watchedRoot = basename(path);
+        const watcher = watch(path, { recursive: true }, (event, filename) => {
+            // macOS emits a synthetic `change` for the watched directory itself in
+            // addition to the actionable relative child event.
+            if (event === 'change' && filename === watchedRoot) {
+                return;
+            }
+            if (!filename || relevant(filename.replaceAll('\\', '/'))) {
+                onRelevantChange();
+            }
+        });
+        watcher.on('error', onError);
+        return watcher;
+    }
+    catch (error) {
+        /* reliability-optional: FILE_MTIME_UNAVAILABLE — explicit undefined invalidates reuse */
+        reportClassifiedDegradation('FILE_MTIME_UNAVAILABLE', error);
+        return undefined;
+    }
+}
+async function evidenceFingerprint(path) {
+    const names = (await readdir(path, { withFileTypes: true }))
+        .filter((entry) => EVIDENCE_FILE.test(entry.name))
+        .map((entry) => entry.name.normalize('NFC'))
+        .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    const entries = await Promise.all(names.map(async (name) => {
+        const evidencePath = join(path, name);
+        const pathStats = await lstat(evidencePath, { bigint: true });
+        if (!pathStats.isFile() || pathStats.isSymbolicLink()) {
+            throw new Error(`[Planu] Validation evidence must be a regular file: ${name}`);
+        }
+        const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+        const handle = await open(evidencePath, constants.O_RDONLY | noFollow);
+        try {
+            const openedStats = await handle.stat({ bigint: true });
+            if (!openedStats.isFile() ||
+                openedStats.dev !== pathStats.dev ||
+                openedStats.ino !== pathStats.ino ||
+                openedStats.size > BigInt(MAX_EVIDENCE_FILE_BYTES)) {
+                throw new Error(`[Planu] Validation evidence changed or exceeds its size limit: ${name}`);
+            }
+            const contentHash = createHash('sha256');
+            const chunk = Buffer.allocUnsafe(FINGERPRINT_CHUNK_BYTES);
+            let position = 0;
+            for (;;) {
+                const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+                if (bytesRead === 0) {
+                    break;
+                }
+                position += bytesRead;
+                if (position > MAX_EVIDENCE_FILE_BYTES) {
+                    throw new Error(`[Planu] Validation evidence exceeds its size limit: ${name}`);
+                }
+                contentHash.update(chunk.subarray(0, bytesRead));
+            }
+            const finalStats = await handle.stat({ bigint: true });
+            if (finalStats.dev !== openedStats.dev ||
+                finalStats.ino !== openedStats.ino ||
+                finalStats.size !== openedStats.size ||
+                finalStats.mtimeNs !== openedStats.mtimeNs ||
+                finalStats.ctimeNs !== openedStats.ctimeNs) {
+                throw new Error(`[Planu] Validation evidence changed while being read: ${name}`);
+            }
+            return {
+                name,
+                bytes: position,
+                digest: contentHash.digest('hex'),
+                device: openedStats.dev.toString(),
+                inode: openedStats.ino.toString(),
+                changedAt: openedStats.ctimeNs.toString(),
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }));
+    const hash = createHash('sha256');
+    hash.update('planu-validation-evidence-v1\0');
+    for (const entry of entries) {
+        hash.update(`${Buffer.byteLength(entry.name)}:${entry.name}${entry.bytes}:${entry.device}:${entry.inode}:${entry.changedAt}:${entry.digest.length}:${entry.digest}`);
+    }
+    return hash.digest('hex');
+}
+/** Start both watchers before snapshotting and invalidate any older receipt immediately. */
+export async function beginValidationFreshnessBarrier(input) {
+    const identity = key(input.projectId, input.specId);
+    await mkdir(input.handoffPath, { recursive: true, mode: 0o700 });
+    const initialEvidenceFingerprint = await evidenceFingerprint(input.handoffPath);
+    active.get(identity)?.watchers.forEach((watcher) => {
+        watcher.close();
+    });
+    let state = {
+        epoch: randomUUID(),
+        expiresAt: Date.now() + LEASE_TTL_MS,
+        generation: 0,
+        healthy: true,
+        projectPath: input.projectPath,
+        handoffPath: input.handoffPath,
+        evidenceFingerprint: initialEvidenceFingerprint,
+        invalidating: Promise.resolve(),
+        watchers: [],
+    };
+    const watchedEpoch = state.epoch;
+    const changed = () => {
+        if (active.get(identity)?.epoch !== watchedEpoch) {
+            return;
+        }
+        invalidateValidationFreshness(input);
+        state = active.get(identity) ?? state;
+    };
+    const failed = () => {
+        if (active.get(identity)?.epoch !== watchedEpoch) {
+            return;
+        }
+        changed();
+        state = { ...state, healthy: false };
+        active.set(identity, state);
+    };
+    const projectWatcher = startWatch(input.projectPath, isValidationSourcePath, changed, failed);
+    const handoffWatcher = startWatch(input.handoffPath, (filename) => EVIDENCE_FILE.test(filename), changed, failed);
+    if (!projectWatcher || !handoffWatcher) {
+        projectWatcher?.close();
+        handoffWatcher?.close();
+        throw new Error('[Planu] Validation freshness watchers could not be established');
+    }
+    state = { ...state, watchers: [projectWatcher, handoffWatcher] };
+    active.set(identity, state);
+    if (input.invalidateCurrentBindings !== false) {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const database = __addDisposableResource(env_2, new RuntimeDatabase({ path: resolveStorageLayout().runtimeDatabase }), false);
+            const store = new ValidationReceiptStore({ database, workspaceId: 'global' });
+            await store.invalidateCurrentBindings(input.projectId, input.specId);
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
+    }
+    return {
+        projectId: input.projectId,
+        specId: input.specId,
+        epoch: state.epoch,
+        generation: state.generation,
+    };
+}
+/** Bind the post-watch snapshot; an event before this call makes the lease unusable. */
+export async function bindValidationFreshnessLease(lease, bindings) {
+    const state = active.get(key(lease.projectId, lease.specId));
+    if (!state ||
+        !state.healthy ||
+        state.epoch !== lease.epoch ||
+        state.generation !== lease.generation ||
+        Date.now() >= state.expiresAt) {
+        return false;
+    }
+    let fingerprintBefore;
+    try {
+        fingerprintBefore = await evidenceFingerprint(state.handoffPath);
+        if ((await gitSourceTreeDigest(state.projectPath)) !== bindings.sourceDigest) {
+            invalidateValidationFreshness(lease);
+            return false;
+        }
+    }
+    catch (error) {
+        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    if (fingerprintBefore !== state.evidenceFingerprint) {
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    const confirmed = active.get(key(lease.projectId, lease.specId));
+    if (!confirmed?.healthy ||
+        confirmed.epoch !== state.epoch ||
+        confirmed.generation !== state.generation) {
+        return false;
+    }
+    active.set(key(lease.projectId, lease.specId), {
+        ...confirmed,
+        bindings: structuredClone(bindings),
+    });
+    return true;
+}
+async function readStableState(lease, expectedGeneration) {
+    const identity = key(lease.projectId, lease.specId);
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const before = active.get(identity);
+        if (!before?.healthy ||
+            before.epoch !== lease.epoch ||
+            (expectedGeneration !== undefined && before.generation !== expectedGeneration)) {
+            return undefined;
+        }
+        await before.invalidating;
+        const after = active.get(identity);
+        if (after?.healthy &&
+            after.epoch === before.epoch &&
+            after.generation === before.generation &&
+            after.invalidating === before.invalidating) {
+            return after;
+        }
+    }
+    return undefined;
+}
+/** Drain invalidation work and verify epoch, generation, health, expiry and bound inputs. */
+export async function assertValidationFreshnessBarrier(lease, bindings) {
+    const candidate = active.get(key(lease.projectId, lease.specId));
+    if (!candidate?.healthy ||
+        candidate.epoch !== lease.epoch ||
+        candidate.generation !== lease.generation) {
+        return false;
+    }
+    let fingerprintBefore;
+    try {
+        fingerprintBefore = await evidenceFingerprint(candidate.handoffPath);
+    }
+    catch (error) {
+        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    if (fingerprintBefore !== candidate.evidenceFingerprint) {
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    try {
+        if (candidate.bindings &&
+            (await gitSourceTreeDigest(candidate.projectPath)) !== candidate.bindings.sourceDigest) {
+            invalidateValidationFreshness(lease);
+            return false;
+        }
+    }
+    catch (error) {
+        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    // A generation change invalidates the lease synchronously. Do not wait for
+    // the durable receipt cleanup when the in-memory barrier already fails
+    // closed; under database contention that cleanup can legitimately be slow.
+    const state = await readStableState(lease, lease.generation);
+    let fingerprintAfter;
+    try {
+        fingerprintAfter = state ? await evidenceFingerprint(state.handoffPath) : undefined;
+    }
+    catch (error) {
+        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+        fingerprintAfter = undefined;
+    }
+    if (!state || fingerprintAfter !== fingerprintBefore) {
+        invalidateValidationFreshness(lease);
+        return false;
+    }
+    if (state.generation !== lease.generation) {
+        return false;
+    }
+    if (Date.now() >= state.expiresAt) {
+        return false;
+    }
+    return bindings === undefined || JSON.stringify(state.bindings) === JSON.stringify(bindings);
+}
+export async function captureValidationFreshnessLease(identity, bindings) {
+    const state = active.get(key(identity.projectId, identity.specId));
+    if (!state) {
+        return undefined;
+    }
+    const lease = { ...identity, epoch: state.epoch, generation: state.generation };
+    return (await assertValidationFreshnessBarrier(lease, bindings)) ? lease : undefined;
+}
+/** Accept validation-generated filesystem activity only after an exact full recomputation. */
+export async function rebaselineValidationFreshnessLeaseAfterRecompute(input) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const before = await readStableState(input.lease);
+        if (!before || Date.now() >= before.expiresAt) {
+            return undefined;
+        }
+        let fingerprintBefore;
+        let observedBindings;
+        let fingerprintAfter;
+        try {
+            fingerprintBefore = await evidenceFingerprint(before.handoffPath);
+            observedBindings = await input.recompute();
+            fingerprintAfter = await evidenceFingerprint(before.handoffPath);
+        }
+        catch (error) {
+            reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+            invalidateValidationFreshness(input.lease);
+            return undefined;
+        }
+        const after = await readStableState(input.lease);
+        if (after?.generation !== before.generation || fingerprintBefore !== fingerprintAfter) {
+            continue;
+        }
+        if (JSON.stringify(input.expectedBindings) !== JSON.stringify(observedBindings)) {
+            return undefined;
+        }
+        const confirmed = await readStableState(input.lease);
+        if (confirmed?.generation !== after.generation) {
+            continue;
+        }
+        active.set(key(input.lease.projectId, input.lease.specId), {
+            ...confirmed,
+            bindings: structuredClone(observedBindings),
+            evidenceFingerprint: fingerprintAfter,
+        });
+        return { ...input.lease, generation: confirmed.generation };
+    }
+    return undefined;
+}
+export function resetValidationFreshnessForTests() {
+    for (const state of active.values()) {
+        state.watchers.forEach((watcher) => {
+            watcher.close();
+        });
+    }
+    active.clear();
+}
+//# sourceMappingURL=validation-freshness.js.map

package/dist/engine/validation/validation-receipt-codec.d.ts

@@ -0,0 +1,13 @@
+import type { ValidationCommandInput, ValidationReceipt, ValidationReceiptBindings, ValidationReceiptIssueInput } from '../../types/validation-receipt.js';
+export declare const DIGEST: RegExp;
+export declare const PROJECT_ID: RegExp;
+export declare const SPEC_ID: RegExp;
+export declare const ISSUER_ID: RegExp;
+export declare function sha256(value: string | Buffer): string;
+export declare function canonicalize(value: unknown): string;
+export declare function normalizeValidationCommand(command: ValidationCommandInput): string;
+export declare function validBindings(value: unknown): value is ValidationReceiptBindings;
+export declare function safeProof(receipt: ValidationReceipt, key: string): boolean;
+export declare function receiptCore(input: ValidationReceiptIssueInput, issuer: string, logDigest: string): Omit<ValidationReceipt, 'receiptId' | 'authenticity'>;
+export declare function validReceiptShape(value: unknown): value is ValidationReceipt;
+//# sourceMappingURL=validation-receipt-codec.d.ts.map

package/dist/engine/validation/validation-receipt-codec.js

@@ -0,0 +1,182 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+export const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+export const PROJECT_ID = /^[a-f0-9]{32}$/u;
+export const SPEC_ID = /^SPEC-[1-9]\d*$/u;
+export const ISSUER_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const ARTIFACT_KEYS = [
+    'approvedSpec',
+    'discovery',
+    'taskPlan',
+    'traceability',
+    'contractValidation',
+];
+export function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+export function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error('[Planu] Receipt values must be finite');
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalize).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`)
+            .join(',')}}`;
+    }
+    throw new Error('[Planu] Receipt values must be JSON serializable');
+}
+function normalizedPart(value, label) {
+    const normalized = value.normalize('NFC').trim();
+    if (!normalized || normalized.includes('\0')) {
+        throw new Error(`[Planu] Invalid validation ${label}`);
+    }
+    return normalized;
+}
+export function normalizeValidationCommand(command) {
+    const executable = normalizedPart(command.executable, 'command');
+    const args = (command.args ?? []).map((arg) => normalizedPart(arg, 'command argument'));
+    const hasCwd = command.cwd !== undefined;
+    if (hasCwd) {
+        normalizedPart(command.cwd ?? '', 'working directory');
+    }
+    return JSON.stringify(hasCwd ? [executable, ...args, '<project>'] : [executable, ...args]);
+}
+export function validBindings(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    const artifacts = candidate.artifactDigests;
+    return (Object.keys(candidate).length === 7 &&
+        typeof candidate.projectId === 'string' &&
+        PROJECT_ID.test(candidate.projectId) &&
+        typeof candidate.specId === 'string' &&
+        SPEC_ID.test(candidate.specId) &&
+        ['sourceDigest', 'specDigest', 'policyDigest', 'toolchainDigest'].every((key) => typeof candidate[key] === 'string' && DIGEST.test(candidate[key])) &&
+        artifacts !== null &&
+        typeof artifacts === 'object' &&
+        Object.keys(artifacts).length === ARTIFACT_KEYS.length &&
+        ARTIFACT_KEYS.every((key) => {
+            const digest = artifacts[key];
+            return typeof digest === 'string' && DIGEST.test(digest);
+        }));
+}
+function normalizeVersions(versions) {
+    const entries = Object.entries(versions);
+    if (entries.length === 0) {
+        throw new Error('[Planu] Validation toolchain versions are required');
+    }
+    return Object.fromEntries(entries
+        .map(([name, version]) => [normalizedPart(name, 'version name'), normalizedPart(version, 'version')])
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+function normalizeGates(gates) {
+    if (gates.length === 0 || gates.some((gate) => gate.status !== 'passed')) {
+        throw new Error('[Planu] A receipt requires passing validation gates');
+    }
+    const names = new Set();
+    return gates.map((gate) => {
+        const name = normalizedPart(gate.gate, 'gate');
+        if (names.has(name) || !Number.isSafeInteger(gate.durationMs) || gate.durationMs < 0) {
+            throw new Error('[Planu] Validation gate results are invalid');
+        }
+        names.add(name);
+        return { gate: name, status: 'passed', durationMs: gate.durationMs };
+    });
+}
+function unsignedReceipt(receipt) {
+    const { authenticity: _authenticity, ...unsigned } = receipt;
+    return unsigned;
+}
+function proofFor(receipt, key) {
+    return createHmac('sha256', key)
+        .update(canonicalize(unsignedReceipt(receipt)))
+        .digest();
+}
+export function safeProof(receipt, key) {
+    try {
+        const received = Buffer.from(receipt.authenticity.proof, 'base64url');
+        const expected = proofFor(receipt, key);
+        return received.length === expected.length && timingSafeEqual(received, expected);
+    }
+    catch (error) {
+        /* reliability-optional: RECEIPT_SIGNATURE_INVALID — false is the fail-closed result */
+        reportClassifiedDegradation('RECEIPT_SIGNATURE_INVALID', error);
+        return false;
+    }
+}
+export function receiptCore(input, issuer, logDigest) {
+    if (!validBindings(input.bindings)) {
+        throw new Error('[Planu] Validation bindings require a canonical projectId and complete digests');
+    }
+    if (input.exitCode !== 0 || !Number.isSafeInteger(input.durationMs) || input.durationMs < 0) {
+        throw new Error('[Planu] A receipt requires passing validation with valid duration');
+    }
+    const issuedAt = input.issuedAt ?? new Date().toISOString();
+    if (new Date(issuedAt).toISOString() !== issuedAt) {
+        throw new Error('[Planu] Receipt issuedAt must be canonical ISO-8601');
+    }
+    return {
+        schemaVersion: 1,
+        issuer,
+        issuedAt,
+        bindings: structuredClone(input.bindings),
+        normalizedCommand: normalizeValidationCommand(input.command),
+        versions: normalizeVersions(input.versions),
+        exitCode: 0,
+        durationMs: input.durationMs,
+        logDigest,
+        gates: normalizeGates(input.gates),
+    };
+}
+function hasReceiptIdentity(candidate) {
+    return (candidate.schemaVersion === 1 &&
+        typeof candidate.receiptId === 'string' &&
+        DIGEST.test(candidate.receiptId) &&
+        typeof candidate.issuer === 'string' &&
+        ISSUER_ID.test(candidate.issuer) &&
+        typeof candidate.issuedAt === 'string' &&
+        Number.isFinite(Date.parse(candidate.issuedAt)));
+}
+function hasReceiptExecution(candidate) {
+    return (validBindings(candidate.bindings) &&
+        typeof candidate.normalizedCommand === 'string' &&
+        candidate.normalizedCommand.length > 0 &&
+        candidate.versions !== null &&
+        typeof candidate.versions === 'object' &&
+        candidate.exitCode === 0 &&
+        Number.isSafeInteger(candidate.durationMs) &&
+        candidate.durationMs >= 0 &&
+        typeof candidate.logDigest === 'string' &&
+        DIGEST.test(candidate.logDigest) &&
+        Array.isArray(candidate.gates) &&
+        candidate.gates.length > 0);
+}
+function hasReceiptAuthenticity(candidate) {
+    if (!candidate.authenticity || typeof candidate.authenticity !== 'object') {
+        return false;
+    }
+    const authenticity = candidate.authenticity;
+    return authenticity.algorithm === 'hmac-sha256' && typeof authenticity.proof === 'string';
+}
+export function validReceiptShape(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (hasReceiptIdentity(candidate) &&
+        hasReceiptExecution(candidate) &&
+        hasReceiptAuthenticity(candidate));
+}
+//# sourceMappingURL=validation-receipt-codec.js.map

package/dist/engine/validation/validation-receipt.d.ts

@@ -0,0 +1,59 @@
+import type { ValidationReceipt, ValidationReceiptBindings, ValidationReceiptIssueInput, ValidationReceiptIssuerOptions, ValidationReceiptPersistence, ValidationReceiptVerification, ValidationReceiptVerificationOptions } from '../../types/validation-receipt.js';
+import type { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { type StorageCatalogContext } from '../../storage/storage-catalog.js';
+export { normalizeValidationCommand } from './validation-receipt-codec.js';
+export declare const LOCAL_VALIDATION_RECEIPT_ISSUER = "planu-local-validator";
+export declare class ValidationIssuerKeyError extends Error {
+    readonly code: 'VALIDATION_ISSUER_KEY_NOT_CONFIGURED';
+    constructor();
+}
+export declare class ValidationReceiptStore implements ValidationReceiptPersistence {
+    private readonly options;
+    private readonly logDirectory;
+    constructor(options: {
+        readonly database: RuntimeDatabase;
+        readonly workspaceId: string;
+        readonly catalogContext?: StorageCatalogContext;
+    });
+    logPath(logDigest: string): string;
+    persist(receipt: ValidationReceipt, log: Buffer): Promise<void>;
+    readReceipt(projectId: string, receiptId: string): Promise<ValidationReceipt | undefined>;
+    readCurrent(projectId: string, specId: string): Promise<ValidationReceipt | undefined>;
+    readCurrentBindings(projectId: string, specId: string): Promise<ValidationReceiptBindings | undefined>;
+    projectCurrentBindings(bindings: ValidationReceiptBindings): Promise<void>;
+    invalidateCurrentBindings(projectId: string, specId: string): Promise<void>;
+    readLog(logDigest: string): Promise<Buffer | undefined>;
+    private writeLog;
+}
+export declare function issueValidationReceipt(input: ValidationReceiptIssueInput, options: ValidationReceiptIssuerOptions): Promise<ValidationReceipt>;
+export declare function verifyValidationReceipt(value: unknown, options: ValidationReceiptVerificationOptions): Promise<ValidationReceiptVerification>;
+export declare function validationLogPath(store: ValidationReceiptPersistence, logDigest: string): string;
+export declare function readCurrentValidationReceipt(store: ValidationReceiptPersistence, identity: {
+    readonly projectId: string;
+    readonly specId: string;
+}): Promise<ValidationReceipt | undefined>;
+/** Trust bootstrap is explicit: construct once with locally provisioned opaque issuer references. */
+export declare class ValidationReceiptAuthority {
+    private readonly store;
+    private readonly trustedIssuers;
+    constructor(store: ValidationReceiptPersistence, trustedIssuers: Readonly<Record<string, string>>);
+    verifyCurrent(bindings: ValidationReceiptBindings): Promise<ValidationReceiptVerification>;
+}
+/** Construct the production verifier from runtime/catalog context without exposing key material. */
+export declare function createValidationReceiptAuthority(options: {
+    readonly database: RuntimeDatabase;
+    readonly workspaceId: string;
+    readonly projectId: string;
+    readonly issuerId: string;
+    readonly catalogContext?: StorageCatalogContext;
+}): {
+    readonly authority: ValidationReceiptAuthority;
+    readonly store: ValidationReceiptStore;
+    readonly signingKeyReference: string;
+};
+/** Provision or resolve a machine-local issuer key without exposing raw key material. */
+export declare function ensureValidationIssuerKey(identity: {
+    readonly projectId: string;
+    readonly issuerId: string;
+}): Promise<string>;
+//# sourceMappingURL=validation-receipt.d.ts.map