@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/decision/compile-cache/file-store.js

@@ -0,0 +1,280 @@
+import { mkdir, open, readFile, rename, stat, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { compileCacheKey, validateCompileIdentity } from './identity.js';
+import { activeCompileCacheHold, buildCompileCacheEntry, compileCacheLifecycleRule, compileCacheReference, compileCacheScopeAllowed, compileCacheTombstoneRecord, CompileCacheRejectedError, isCompileCacheTombstone, mayRestoreCompileCacheEntry, revalidateCompileCacheEntry, validateCompileCacheHold, } from './records.js';
+const isTombstone = (record) => record.schemaVersion === 'decision-compile-cache-tombstone/v1';
+const DEFAULT_LOCK_POLL_MS = 25;
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+/**
+ * Durable, atomic filesystem cache. Files are named only by one-way key digests.
+ * Out-of-scope or unauthorized lifecycle calls return the same result as an
+ * absent key, decided before the filesystem is touched.
+ */
+export class FileCompileCache {
+    directory;
+    fills = new Map();
+    lockPollMs;
+    lockTimeoutMs;
+    policy;
+    rule;
+    journal;
+    constructor(directory, options) {
+        this.directory = directory;
+        this.lockPollMs = this.positiveInteger(options.lockPollMs ?? DEFAULT_LOCK_POLL_MS, 'lockPollMs');
+        this.lockTimeoutMs = this.positiveInteger(options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, 'lockTimeoutMs');
+        this.rule = compileCacheLifecycleRule(options.lifecyclePolicy);
+        this.policy = structuredClone(options.lifecyclePolicy);
+        this.journal = options.lifecycleJournal;
+    }
+    async getOrCompile(identity, context, ttlMs, compile, options = {}) {
+        validateCompileIdentity(identity);
+        const key = compileCacheKey(identity);
+        if (!compileCacheScopeAllowed(identity, context))
+            throw new CompileCacheRejectedError();
+        if (options.bypass)
+            return { outcome: 'bypass', key, entry: await buildCompileCacheEntry(identity, key, context, ttlMs, this.rule, compile) };
+        const existing = await this.readExisting(identity, context, true);
+        if (existing)
+            return { outcome: 'hit', key, entry: existing };
+        const active = this.fills.get(key);
+        if (active)
+            return { outcome: 'hit', key, entry: revalidateCompileCacheEntry(await active, identity, context) };
+        const fill = this.buildWithFileLock(identity, key, context, ttlMs, compile);
+        const shared = fill.then(result => result.entry);
+        void shared.catch(() => undefined);
+        this.fills.set(key, shared);
+        try {
+            const result = await fill;
+            return { outcome: result.filled ? 'miss' : 'hit', key, entry: structuredClone(result.entry) };
+        }
+        finally {
+            this.fills.delete(key);
+        }
+    }
+    async read(identity, context) {
+        if (!compileCacheScopeAllowed(identity, context))
+            return null;
+        return this.readExisting(identity, context, false);
+    }
+    async readExisting(identity, context, refreshExpired) {
+        // Validate integrity, identity, scope and authorization before deciding
+        // whether an expired entry can be treated as a cache miss for a fill.
+        const record = await this.readRecord(compileCacheKey(identity));
+        if (!record)
+            return null;
+        if (isTombstone(record))
+            throw new CompileCacheRejectedError();
+        const entry = revalidateCompileCacheEntry(record, identity, context, true);
+        if (context.nowEpochMs >= entry.expiresAtEpochMs) {
+            if (refreshExpired)
+                return null;
+            throw new CompileCacheRejectedError();
+        }
+        return entry;
+    }
+    /** Erase the body and leave a persistent tombstone; the key never fills or restores again. */
+    async tombstone(identity, context) {
+        return this.retire(identity, context);
+    }
+    /** D10 deletion: the same body-free tombstone; false when absent, held or already erased. */
+    async delete(identity, context) {
+        return this.retire(identity, context);
+    }
+    /** Place (or with `null`, release) a D10 hold scoped to the `cache` surface. */
+    async setLegalHold(identity, context, hold) {
+        const entry = await this.readLifecycleEntry(identity, context);
+        if (entry)
+            await this.publish({ ...entry, legalHold: hold === null ? null : validateCompileCacheHold(hold, context.nowEpochMs) });
+    }
+    async retire(identity, context) {
+        // Retirement works after expiry, but still authenticates the stored
+        // identity and integrity before erasing anything.
+        const entry = await this.readLifecycleEntry(identity, context);
+        if (!entry || activeCompileCacheHold(entry, context.nowEpochMs))
+            return false;
+        const record = compileCacheTombstoneRecord(entry.key, context.nowEpochMs);
+        // Journal first so a failed local write cannot leave a restorable gap.
+        if (this.journal)
+            await this.journal.tombstone(structuredClone(record.tombstone));
+        await this.publish(record);
+        return true;
+    }
+    /** Authorized live or expired entry; null when absent, out of scope or already tombstoned. */
+    async readLifecycleEntry(identity, context) {
+        if (!compileCacheScopeAllowed(identity, context))
+            return null;
+        const record = await this.readRecord(compileCacheKey(identity));
+        if (!record || isTombstone(record))
+            return null;
+        return revalidateCompileCacheEntry(record, identity, context, true);
+    }
+    async readRecord(key) {
+        let raw;
+        try {
+            raw = await readFile(this.path(key), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw new CompileCacheRejectedError();
+        }
+        let record;
+        try {
+            record = JSON.parse(raw);
+        }
+        catch {
+            throw new CompileCacheRejectedError();
+        }
+        if (record?.schemaVersion === 'decision-compile-cache-tombstone/v1' && !isCompileCacheTombstone(record, key)) {
+            throw new CompileCacheRejectedError();
+        }
+        return record;
+    }
+    /** Export is explicit, scope-authorized, and allowed only when the lifecycle rule persists backups. */
+    async backup(identity, context) {
+        if (this.rule.backup === 'not-persisted')
+            throw new CompileCacheRejectedError();
+        return this.read(identity, context);
+    }
+    async restore(entry, context) {
+        // Restored backups must still be live at the point of import; old copies
+        // cannot resurrect deleted/tombstoned or expired compiler artifacts.
+        const restored = revalidateCompileCacheEntry(entry, entry.identity, context);
+        const existing = await this.readRecord(restored.key);
+        // A backup cannot replace an existing immutable entry or undo any tombstone,
+        // whether it is kept locally or in the independent lifecycle journal.
+        if (existing && !isTombstone(existing))
+            throw new CompileCacheRejectedError();
+        const tombstones = existing ? [existing.tombstone] : [];
+        if (this.journal) {
+            try {
+                tombstones.push(...await this.journal.tombstones(compileCacheReference(restored.key).opaqueId));
+            }
+            catch {
+                throw new CompileCacheRejectedError();
+            }
+        }
+        if (!mayRestoreCompileCacheEntry(restored, context.nowEpochMs, this.policy, tombstones))
+            throw new CompileCacheRejectedError();
+        await this.publish(restored);
+    }
+    async buildWithFileLock(identity, key, context, ttlMs, compile) {
+        const owner = await this.acquireFillLock(key);
+        try {
+            const existing = await this.readExisting(identity, context, true);
+            if (existing)
+                return { entry: existing, filled: false };
+            const entry = await buildCompileCacheEntry(identity, key, context, ttlMs, this.rule, compile);
+            await this.publish(entry);
+            return { entry, filled: true };
+        }
+        finally {
+            await this.releaseFillLock(key, owner);
+        }
+    }
+    async acquireFillLock(key) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const owner = { version: 1, pid: process.pid, token: randomUUID(), createdAtEpochMs: Date.now() };
+        const path = this.lockPath(key);
+        const started = Date.now();
+        while (true) {
+            try {
+                const handle = await open(path, 'wx', 0o600);
+                try {
+                    await handle.writeFile(canonicalJson(owner), 'utf8');
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                return owner;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                if (!await this.lockOwnerAlive(path)) {
+                    await unlink(path).catch(unlinkError => {
+                        if (unlinkError.code !== 'ENOENT')
+                            throw unlinkError;
+                    });
+                    continue;
+                }
+                if (Date.now() - started >= this.lockTimeoutMs)
+                    throw new CompileCacheRejectedError();
+                await new Promise(resolve => setTimeout(resolve, this.lockPollMs));
+            }
+        }
+    }
+    async lockOwnerAlive(path) {
+        try {
+            const owner = JSON.parse(await readFile(path, 'utf8'));
+            if (owner.version !== 1 || !Number.isSafeInteger(owner.pid) || owner.pid < 1 || typeof owner.token !== 'string') {
+                return this.lockRecordRecentlyCreated(path);
+            }
+            try {
+                process.kill(owner.pid, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code !== 'ESRCH';
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return true;
+            return this.lockRecordRecentlyCreated(path);
+        }
+    }
+    async lockRecordRecentlyCreated(path) {
+        try {
+            // Exclusive creation precedes the synced owner record. Both truncated and
+            // parseable-but-incomplete metadata must remain owned during that window.
+            return Date.now() - (await stat(path)).mtimeMs < Math.max(DEFAULT_LOCK_TIMEOUT_MS, this.lockTimeoutMs * 2);
+        }
+        catch (error) {
+            return error.code === 'ENOENT';
+        }
+    }
+    async releaseFillLock(key, owner) {
+        const path = this.lockPath(key);
+        try {
+            const current = JSON.parse(await readFile(path, 'utf8'));
+            if (current.token === owner.token && current.pid === owner.pid)
+                await unlink(path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    positiveInteger(value, label) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new TypeError(`${label} must be a positive integer`);
+        return value;
+    }
+    path(key) { return join(this.directory, `${key.slice('sha256:'.length)}.json`); }
+    lockPath(key) { return join(this.directory, `${key.slice('sha256:'.length)}.lock`); }
+    async publish(entry) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const path = this.path(entry.key);
+        const temporary = join(dirname(path), `.compile-cache-${randomUUID()}.tmp`);
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(canonicalJson(entry), 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(temporary, path);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=file-store.js.map

package/dist/src/decision/compile-cache/identity.js

@@ -0,0 +1,26 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../../security/artifact-trust.js';
+export function sha256(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+export function compileCacheKey(identity) {
+    validateCompileIdentity(identity);
+    return sha256(identity);
+}
+export function providerPrefixKey(identity) {
+    if (identity.policy.ttlMs <= 0 || !Number.isSafeInteger(identity.policy.ttlMs))
+        throw new Error('invalid provider prefix TTL');
+    return sha256(identity);
+}
+export function validateCompileIdentity(identity) {
+    if (!identity.sourceArtifactDigests.length || identity.sourceArtifactDigests.some(value => !/^sha256:[0-9a-f]{64}$/.test(value))) {
+        throw new Error('compile identity requires valid pinned source digests');
+    }
+    const required = [identity.compiler.id, identity.compiler.version, identity.runtimeVersion, identity.schemaVersion,
+        identity.canonicalizer.id, identity.canonicalizer.version, identity.adapter.id, identity.adapter.version,
+        identity.adapter.promptVersion, identity.backendCapabilityMode, identity.modelPolicy.requested,
+        identity.tenantId, identity.projectId, identity.dataClass];
+    if (required.some(value => !value))
+        throw new Error('compile identity contains an empty semantic dimension');
+}
+//# sourceMappingURL=identity.js.map

package/dist/src/decision/compile-cache/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './identity.js';
+export * from './store.js';
+export * from './file-store.js';
+export * from './prefix.js';
+export * from './benchmark.js';
+export * from './runtime.js';
+export * from './compatibility.js';
+//# sourceMappingURL=index.js.map

package/dist/src/decision/compile-cache/prefix.js

@@ -0,0 +1,21 @@
+import { providerPrefixKey } from './identity.js';
+/** Provider status is derived exclusively from an explicit report/capability declaration. */
+export function providerPrefixEvidence(identity, report, observedAtEpochMs = Date.now()) {
+    const base = { schemaVersion: 'decision-provider-prefix-evidence/v1', identityDigest: providerPrefixKey(identity) };
+    if (report.kind === 'reported' && validReportedEvidence(report)
+        && Number.isSafeInteger(observedAtEpochMs) && observedAtEpochMs >= 0
+        && (report.expiresAtEpochMs === null || report.expiresAtEpochMs > observedAtEpochMs))
+        return { ...base, status: report.hit ? 'hit' : 'miss', source: 'provider-report',
+            cacheVersion: report.cacheVersion, savedInputTokens: report.savedInputTokens, expiresAtEpochMs: report.expiresAtEpochMs };
+    if (report.kind === 'unsupported')
+        return { ...base, status: 'unsupported', source: 'documented-unsupported', cacheVersion: null, savedInputTokens: null, expiresAtEpochMs: null };
+    if (report.kind === 'bypass')
+        return { ...base, status: 'bypass', source: 'policy-bypass', cacheVersion: null, savedInputTokens: null, expiresAtEpochMs: null };
+    return { ...base, status: 'unknown', source: 'unreported', cacheVersion: null, savedInputTokens: null, expiresAtEpochMs: null };
+}
+function validReportedEvidence(report) {
+    return report.cacheVersion.length > 0 && report.cacheVersion.length <= 128
+        && (report.savedInputTokens === null || (Number.isSafeInteger(report.savedInputTokens) && report.savedInputTokens >= 0))
+        && (report.expiresAtEpochMs === null || (Number.isSafeInteger(report.expiresAtEpochMs) && report.expiresAtEpochMs >= 0));
+}
+//# sourceMappingURL=prefix.js.map

package/dist/src/decision/compile-cache/records.js

@@ -0,0 +1,86 @@
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { DECISION_LIFECYCLE_SURFACES, mayRestoreDecisionReference, validateDecisionLifecyclePolicy, } from '../lifecycle.js';
+import { compileCacheKey, sha256 } from './identity.js';
+export class CompileCacheRejectedError extends Error {
+    constructor() { super('compile cache entry unavailable'); this.name = 'CompileCacheRejectedError'; }
+}
+/** The D10 `cache` surface rule that governs retention, backup and hold handling. */
+export function compileCacheLifecycleRule(policy) {
+    validateDecisionLifecyclePolicy(policy);
+    return structuredClone(policy.surfaces.cache);
+}
+export function compileCacheReference(key) {
+    return { surface: 'cache', opaqueId: key.slice('sha256:'.length) };
+}
+/**
+ * Scope and authorization are decided on the requested identity before any
+ * storage lookup, so a denied caller cannot tell a present entry from an absent one.
+ */
+export function compileCacheScopeAllowed(identity, context) {
+    try {
+        return identity.tenantId === context.tenantId && identity.projectId === context.projectId
+            && context.authorize(identity) === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function activeCompileCacheHold(entry, nowEpochMs) {
+    return entry.legalHold !== null && entry.legalHold.expiresAt > nowEpochMs;
+}
+export function validateCompileCacheHold(hold, nowEpochMs) {
+    if (!hold?.subject || !hold.reason || !hold.authorizedBy || !Array.isArray(hold.scope) || !hold.scope.includes('cache')
+        || hold.scope.some(surface => !DECISION_LIFECYCLE_SURFACES.includes(surface))
+        || !Number.isSafeInteger(hold.expiresAt) || hold.expiresAt <= nowEpochMs)
+        throw new Error('Decision lifecycle hold denied');
+    return structuredClone(hold);
+}
+export function compileCacheTombstoneRecord(key, nowEpochMs) {
+    const reference = compileCacheReference(key);
+    return { schemaVersion: 'decision-compile-cache-tombstone/v1', key,
+        tombstone: { subject: reference.opaqueId, reference, deletedAt: nowEpochMs } };
+}
+export function isCompileCacheTombstone(record, key) {
+    const value = record;
+    const reference = compileCacheReference(key);
+    return value?.schemaVersion === 'decision-compile-cache-tombstone/v1' && value.key === key
+        && Object.keys(value).length === 3 && value.tombstone?.subject === reference.opaqueId
+        && value.tombstone.reference?.surface === 'cache' && value.tombstone.reference.opaqueId === reference.opaqueId
+        && Number.isSafeInteger(value.tombstone.deletedAt) && value.tombstone.deletedAt >= 0;
+}
+export async function buildCompileCacheEntry(identity, key, context, ttlMs, rule, compile) {
+    // Entry lifetime can never exceed the lifecycle retention for the cache surface.
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > rule.retentionMs
+        || !compileCacheScopeAllowed(identity, context))
+        throw new CompileCacheRejectedError();
+    const value = await compile();
+    if (value === undefined || canonicalJson(value) === undefined)
+        throw new Error('compiler returned malformed output');
+    return { schemaVersion: 'decision-compile-cache-entry/v1', key, identity: structuredClone(identity),
+        value: structuredClone(value), valueDigest: sha256(value), createdAtEpochMs: context.nowEpochMs,
+        expiresAtEpochMs: context.nowEpochMs + ttlMs, legalHold: null };
+}
+/** Revalidate integrity, identity, scope, authorization and (unless allowed) expiry. */
+export function revalidateCompileCacheEntry(entry, identity, context, allowExpired = false) {
+    let valid = false;
+    try {
+        valid = entry?.schemaVersion === 'decision-compile-cache-entry/v1'
+            && entry.key === compileCacheKey(entry.identity) && entry.key === compileCacheKey(identity)
+            && canonicalJson(entry.identity) === canonicalJson(identity) && entry.valueDigest === sha256(entry.value)
+            && Number.isSafeInteger(entry.createdAtEpochMs) && Number.isSafeInteger(entry.expiresAtEpochMs)
+            && (entry.legalHold === null || (typeof entry.legalHold === 'object' && Number.isSafeInteger(entry.legalHold.expiresAt)))
+            && compileCacheScopeAllowed(entry.identity, context)
+            && (allowExpired || context.nowEpochMs < entry.expiresAtEpochMs);
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        throw new CompileCacheRejectedError();
+    return structuredClone(entry);
+}
+/** D10 restore gate: any tombstone for the key, or elapsed retention, refuses the backup. */
+export function mayRestoreCompileCacheEntry(entry, nowEpochMs, policy, tombstones) {
+    return mayRestoreDecisionReference(compileCacheReference(entry.key), entry.createdAtEpochMs, nowEpochMs, policy, tombstones);
+}
+//# sourceMappingURL=records.js.map

package/dist/src/decision/compile-cache/runtime.js

@@ -0,0 +1,68 @@
+import { sanitizeOpaqueValue } from '../telemetry/redaction.js';
+const REASONS = {
+    hit: 'verified-hit', miss: 'cold-fill', bypass: 'cache-disabled', rejected: 'store-rejected',
+};
+/** Metadata-only compile-layer telemetry: no alias, key, identity or artifact content. */
+export function compileCacheTelemetry(identity, outcome, preparationLatencyMs, expiresAtEpochMs) {
+    return { schemaVersion: 'decision-cache-telemetry/v1', layer: identity?.layer ?? 'definition-compilation', outcome,
+        reason: REASONS[outcome], version: identity ? sanitizeOpaqueValue(identity.compiler.version, 64) : null, savedTokens: null,
+        preparationLatencyMs: Math.max(0, preparationLatencyMs), expiresAtEpochMs,
+        invalidationReason: outcome === 'rejected' ? 'revalidation-failed' : null };
+}
+/**
+ * Compile the stable adapter material through one semantic path. Caching only
+ * selects where that exact artifact comes from; it never changes the request
+ * passed to the compiler or permits stale fallback.
+ */
+export async function prepareCompiledArtifact(input) {
+    if (!input.adapter.compile)
+        return undefined;
+    const compile = async () => input.adapter.compile({
+        definition: structuredClone(input.definition),
+        target: structuredClone(input.target),
+    });
+    const policy = input.policy;
+    if (!policy)
+        return compile();
+    const started = performance.now();
+    const emit = (identity, outcome, expiresAtEpochMs) => {
+        try {
+            policy.onTelemetry?.(compileCacheTelemetry(identity, outcome, performance.now() - started, expiresAtEpochMs));
+        }
+        catch { /* telemetry is observability-only */ }
+    };
+    if (!policy.enabled) {
+        const value = await compile();
+        emit(null, 'bypass', null);
+        return value;
+    }
+    const identity = policy.identityFor(input);
+    const context = typeof policy.context === 'function' ? policy.context() : policy.context;
+    try {
+        const result = await policy.store.getOrCompile(identity, context, policy.ttlMs, compile);
+        policy.onResult?.({ alias: input.alias, outcome: result.outcome });
+        emit(identity, result.outcome, result.entry.expiresAtEpochMs);
+        return structuredClone(result.entry.value);
+    }
+    catch (error) {
+        if (policy.failureMode === 'fail') {
+            emit(identity, 'rejected', null);
+            throw error;
+        }
+        policy.onResult?.({ alias: input.alias, outcome: 'rejected' });
+        const value = await compile();
+        emit(identity, 'rejected', null);
+        return value;
+    }
+}
+export async function prepareAdapterRequest(request, adapter, policy) {
+    const compiledArtifact = await prepareCompiledArtifact({
+        alias: request.alias,
+        definition: request.definition,
+        target: request.target,
+        adapter,
+        policy,
+    });
+    return compiledArtifact === undefined ? request : { ...request, compiledArtifact };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/decision/compile-cache/store.js

@@ -0,0 +1,108 @@
+import { compileCacheKey, validateCompileIdentity } from './identity.js';
+import { activeCompileCacheHold, buildCompileCacheEntry, compileCacheLifecycleRule, compileCacheScopeAllowed, compileCacheTombstoneRecord, CompileCacheRejectedError, mayRestoreCompileCacheEntry, revalidateCompileCacheEntry, validateCompileCacheHold, } from './records.js';
+export { CompileCacheRejectedError } from './records.js';
+const isTombstone = (record) => record.schemaVersion === 'decision-compile-cache-tombstone/v1';
+/**
+ * In-memory reference store. Entries are immutable and concurrent fills share one promise.
+ * Out-of-scope or unauthorized lifecycle calls return the same result as an absent key.
+ */
+export class MemoryCompileCache {
+    records = new Map();
+    fills = new Map();
+    policy;
+    rule;
+    constructor(options) {
+        this.rule = compileCacheLifecycleRule(options.lifecyclePolicy);
+        this.policy = structuredClone(options.lifecyclePolicy);
+    }
+    async getOrCompile(identity, context, ttlMs, compile, options = {}) {
+        validateCompileIdentity(identity);
+        const key = compileCacheKey(identity);
+        if (!compileCacheScopeAllowed(identity, context))
+            throw new CompileCacheRejectedError();
+        if (options.bypass)
+            return { outcome: 'bypass', key, entry: await buildCompileCacheEntry(identity, key, context, ttlMs, this.rule, compile) };
+        const existing = this.records.get(key);
+        if (existing) {
+            // Authenticate the old entry before allowing an expiry refresh. A
+            // tombstone or tamper is never silently converted into a cache miss.
+            if (isTombstone(existing))
+                throw new CompileCacheRejectedError();
+            revalidateCompileCacheEntry(existing, identity, context, true);
+            if (context.nowEpochMs < existing.expiresAtEpochMs) {
+                return { outcome: 'hit', key, entry: revalidateCompileCacheEntry(existing, identity, context) };
+            }
+        }
+        const active = this.fills.get(key);
+        if (active)
+            return { outcome: 'hit', key, entry: revalidateCompileCacheEntry(await active, identity, context) };
+        const fill = buildCompileCacheEntry(identity, key, context, ttlMs, this.rule, compile);
+        this.fills.set(key, fill);
+        try {
+            const entry = await fill;
+            if (this.records.get(key) && isTombstone(this.records.get(key)))
+                throw new CompileCacheRejectedError();
+            this.records.set(key, entry);
+            return { outcome: 'miss', key, entry: structuredClone(entry) };
+        }
+        finally {
+            this.fills.delete(key);
+        }
+    }
+    read(identity, context) {
+        const record = this.lookup(identity, context);
+        if (!record)
+            return null;
+        if (isTombstone(record))
+            throw new CompileCacheRejectedError();
+        return revalidateCompileCacheEntry(record, identity, context);
+    }
+    /** Erase the body and leave a persistent tombstone; the key never fills or restores again. */
+    tombstone(identity, context) {
+        return this.retire(identity, context);
+    }
+    /** D10 deletion: same body-free tombstone as `tombstone`; false when absent, held or already erased. */
+    delete(identity, context) {
+        return this.retire(identity, context);
+    }
+    /** Place (or with `null`, release) a D10 hold scoped to the `cache` surface. */
+    setLegalHold(identity, context, hold) {
+        const record = this.lookup(identity, context);
+        if (!record)
+            return;
+        if (isTombstone(record))
+            throw new CompileCacheRejectedError();
+        const entry = revalidateCompileCacheEntry(record, identity, context, true);
+        this.records.set(entry.key, { ...entry, legalHold: hold === null ? null : validateCompileCacheHold(hold, context.nowEpochMs) });
+    }
+    /** Export an authorized live entry when the lifecycle rule persists backups. */
+    backup(identity, context) {
+        if (this.rule.backup === 'not-persisted')
+            throw new CompileCacheRejectedError();
+        return this.read(identity, context);
+    }
+    /** Import a backup only while live, in retention, and never over a tombstone or live entry. */
+    restore(entry, context) {
+        const restored = revalidateCompileCacheEntry(entry, entry.identity, context);
+        const existing = this.records.get(restored.key);
+        if ((existing && !isTombstone(existing)) || !mayRestoreCompileCacheEntry(restored, context.nowEpochMs, this.policy, existing ? [existing.tombstone] : []))
+            throw new CompileCacheRejectedError();
+        this.records.set(restored.key, restored);
+    }
+    lookup(identity, context) {
+        if (!compileCacheScopeAllowed(identity, context))
+            return null;
+        return this.records.get(compileCacheKey(identity)) ?? null;
+    }
+    retire(identity, context) {
+        const record = this.lookup(identity, context);
+        if (!record || isTombstone(record))
+            return false;
+        const entry = revalidateCompileCacheEntry(record, identity, context, true);
+        if (activeCompileCacheHold(entry, context.nowEpochMs))
+            return false;
+        this.records.set(entry.key, compileCacheTombstoneRecord(entry.key, context.nowEpochMs));
+        return true;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/decision/compile-cache/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map