agentic-workflow-manager 9.17.0 → 9.19.0

package/dist/src/core/admission/index.js

@@ -101,6 +101,16 @@ function currentness(report, consumedRegistryComponents) {
     return { status, cli, diagnostics: [diagnostic('ADMISSION_CURRENTNESS_BLOCKED', `Consumed contract currentness is ${status}: ${names}.`)] };
 }
 function sensorVerdict(report) { return report.overall === 'not_certified' ? 'not-certified' : report.overall === 'pass' ? 'pass' : 'fail'; }
+/** A not-certified verdict alone does not say what to fix; carry the run's own cause. */
+function sensorBlockedMessage(report, verdict) {
+    // The diagnostic code must stay the message's only ADMISSION_ token (recovery classification counts them); echoed text may carry user-chosen ones.
+    const plain = (text) => text.trim().replace(/ADMISSION_/g, 'ADMISSION-');
+    const reason = verdict === 'not-certified' && typeof report.reason === 'string' ? plain(report.reason) : '';
+    if (!reason)
+        return `Sensor verdict is ${verdict}.`;
+    const remedy = typeof report.remedy === 'string' ? plain(report.remedy).replace(/\.+$/, '') : '';
+    return remedy ? `Sensor verdict is ${verdict} (${reason}): ${remedy}.` : `Sensor verdict is ${verdict} (${reason}).`;
+}
 function journalStatus(input, plan) {
     if (input.journalCorrupt)
         return 'corrupt';
@@ -237,7 +247,7 @@ async function admitPlan(input) {
         const sensors = sensorVerdict(input.sensors);
         const registryOptOut = sensors === 'not-certified' && input.sensorClosurePolicy === 'r8-registry-opt-out' && input.sensors.mode === 'opt-out';
         if (sensors !== 'pass' && !registryOptOut)
-            return blocked(input, [diagnostic('ADMISSION_SENSORS_BLOCKED', `Sensor verdict is ${sensors}.`)], { planDigest: plan.planDigest, provider, executionMode: mode, currentness: input.requireCurrent ? 'current' : 'not-checked', cliCurrentness, sensors });
+            return blocked(input, [diagnostic('ADMISSION_SENSORS_BLOCKED', sensorBlockedMessage(input.sensors, sensors))], { planDigest: plan.planDigest, provider, executionMode: mode, currentness: input.requireCurrent ? 'current' : 'not-checked', cliCurrentness, sensors });
         sensorsReported = sensors;
         if (registryOptOut)
             sensorEvidence = { sensorEvidence: 'r8-registry-opt-out' };

package/dist/src/core/currentness/check.js

@@ -162,12 +162,15 @@ async function registryComponent(registry, git, prefs, checkedAt) {
     if (!authorizedSource)
         return fail('Configured registry remote is not an authoritative HTTPS or SSH source.', 'Configure an authoritative registry remote and rerun strict preflight.');
     const [originResult, headResult, tagResult, remoteResult] = await Promise.allSettled([
-        deadline(git(registry.contentRoot, ['remote', 'get-url', 'origin'], { timeoutMs: TIMEOUT_MS, maxOutputBytes: MAX_OUTPUT_BYTES })),
+        // The literal stored value of THIS checkout: `git remote get-url` applies url.*.insteadOf, and
+        // cloud environments (AWM's own D-7 recipe) rewrite to a token-bearing URL; without
+        // `--local`, a global/system `remote.origin.url` could stand in for a missing origin.
+        deadline(git(registry.contentRoot, ['config', '--local', '--get', 'remote.origin.url'], { timeoutMs: TIMEOUT_MS, maxOutputBytes: MAX_OUTPUT_BYTES })),
         deadline(git(registry.contentRoot, ['rev-parse', 'HEAD'], { timeoutMs: TIMEOUT_MS, maxOutputBytes: MAX_OUTPUT_BYTES })),
         deadline(git(registry.contentRoot, ['describe', '--tags', '--exact-match', 'HEAD'], { timeoutMs: TIMEOUT_MS, maxOutputBytes: MAX_OUTPUT_BYTES })),
         deadline(git(registry.contentRoot, ['ls-remote', '--tags', registry.remote], { timeoutMs: TIMEOUT_MS, maxOutputBytes: MAX_OUTPUT_BYTES })),
     ]);
-    if (originResult.status === 'rejected')
+    if (originResult.status === 'rejected' || originResult.value.trim() === '')
         return fail('Could not read local registry origin.', 'Inspect the local registry checkout and its origin remote.');
     if (headResult.status === 'rejected')
         return fail('Could not read local registry HEAD.', 'Inspect or repair the local registry checkout.');

package/dist/src/core/environments/resolve.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXT_INJECT_MAX_CHARS = void 0;
+exports.statusFor = statusFor;
+exports.buildInjection = buildInjection;
+/** Fixed budget for `inject: context` fresh values (RF-3.2). */
+exports.CONTEXT_INJECT_MAX_CHARS = 2048;
+function assertValidNow(now) {
+    if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+        throw new Error('now must be a Date with a finite getTime()');
+    }
+}
+function effectiveStatus(definitionDurability, stored, now) {
+    if (!stored)
+        return 'missing';
+    if (stored.status === 'missing')
+        return 'missing';
+    if (stored.status === 'stale')
+        return 'stale';
+    // Durable never time-stales (RF-2.3).
+    if (definitionDurability === 'durable') {
+        return stored.status === 'fresh' ? 'fresh' : stored.status;
+    }
+    // Volatile: fail closed — missing/invalid expiresAt or now >= expiresAt → stale (RF-2.4).
+    if (typeof stored.expiresAt !== 'string' || stored.expiresAt.trim() === '') {
+        return 'stale';
+    }
+    const expiresMs = Date.parse(stored.expiresAt);
+    if (!Number.isFinite(expiresMs) || now.getTime() >= expiresMs) {
+        return 'stale';
+    }
+    return stored.status === 'fresh' ? 'fresh' : stored.status;
+}
+/**
+ * Per-catalog-id status against the store. Missing → `missing` with no default (RF-2.5).
+ */
+function statusFor(catalog, store, now = new Date()) {
+    if (!catalog || typeof catalog !== 'object' || !catalog.facts) {
+        throw new Error('statusFor: catalog with facts is required');
+    }
+    if (!store || typeof store !== 'object') {
+        throw new Error('statusFor: store must be an object');
+    }
+    assertValidNow(now);
+    const out = {};
+    for (const [id, def] of Object.entries(catalog.facts)) {
+        out[id] = effectiveStatus(def.durability, store[id], now);
+    }
+    return out;
+}
+/**
+ * Build injection payload. Default / explicit `reference` exposes path + ids only (RF-3.1).
+ * `context` includes fresh `inject: context` values under budget; overflow degrades (RF-3.2).
+ */
+function buildInjection(opts) {
+    if (!opts || typeof opts !== 'object') {
+        throw new Error('buildInjection: options object is required');
+    }
+    if (!opts.catalog?.facts) {
+        throw new Error('buildInjection: catalog with facts is required');
+    }
+    if (typeof opts.storePath !== 'string' || opts.storePath.trim() === '') {
+        throw new Error('buildInjection: storePath must be a non-empty string');
+    }
+    if (!opts.store || typeof opts.store !== 'object') {
+        throw new Error('buildInjection: store must be an object');
+    }
+    const rawInject = opts.inject ?? 'reference';
+    // Unknown/typo must not fall through into context (fail-open). Prefer reference (RNF-2).
+    const inject = rawInject === 'reference' || rawInject === 'context' ? rawInject : 'reference';
+    const maxChars = opts.maxChars ?? exports.CONTEXT_INJECT_MAX_CHARS;
+    if (typeof maxChars !== 'number' || !Number.isFinite(maxChars) || maxChars < 0) {
+        throw new Error('buildInjection: maxChars must be a non-negative finite number');
+    }
+    const now = opts.now ?? new Date();
+    assertValidNow(now);
+    if (opts.factIds !== undefined) {
+        if (!Array.isArray(opts.factIds) || opts.factIds.some((id) => typeof id !== 'string' || id === '')) {
+            throw new Error('buildInjection: factIds must be an array of non-empty strings');
+        }
+    }
+    const factIds = opts.factIds ?? Object.keys(opts.catalog.facts);
+    const statuses = statusFor(opts.catalog, opts.store, now);
+    const referenceResult = () => ({
+        mode: 'reference',
+        storePath: opts.storePath,
+        factIds: [...factIds],
+    });
+    if (inject !== 'context') {
+        return referenceResult();
+    }
+    // Context mode: only fresh values whose catalog inject is `context` (RF-3.2).
+    const contextValues = {};
+    let totalChars = 0;
+    for (const id of factIds) {
+        const def = opts.catalog.facts[id];
+        if (!def || def.inject !== 'context')
+            continue;
+        if (statuses[id] !== 'fresh')
+            continue;
+        const stored = opts.store[id];
+        if (!stored || typeof stored.value !== 'string')
+            continue;
+        totalChars += stored.value.length;
+        contextValues[id] = stored.value;
+    }
+    if (Object.keys(contextValues).length === 0) {
+        return referenceResult();
+    }
+    if (totalChars > maxChars) {
+        return {
+            ...referenceResult(),
+            warning: `Context inject budget exceeded (${totalChars} > ${maxChars} chars); degraded to reference`,
+        };
+    }
+    return {
+        mode: 'context',
+        storePath: opts.storePath,
+        factIds: [...factIds],
+        values: contextValues,
+    };
+}

package/dist/src/core/environments/store.js

@@ -0,0 +1,323 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentStoreError = void 0;
+exports.environmentsRoot = environmentsRoot;
+exports.envDir = envDir;
+exports.valuesPath = valuesPath;
+exports.getActiveEnvironmentName = getActiveEnvironmentName;
+exports.setActiveEnvironmentName = setActiveEnvironmentName;
+exports.readValues = readValues;
+exports.isInsideRegistryTree = isInsideRegistryTree;
+exports.assertNotInsideRegistryTree = assertNotInsideRegistryTree;
+exports.writeEnvValue = writeEnvValue;
+exports.writeFact = writeFact;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const atomic_file_1 = require("../atomic-file");
+const paths_1 = require("../paths");
+const registries_1 = require("../registries");
+class EnvironmentStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvironmentStoreError';
+    }
+}
+exports.EnvironmentStoreError = EnvironmentStoreError;
+const DEFAULT_ENV_NAME = 'default';
+const META_FILE = 'meta.json';
+const VALUES_FILE = 'values.json';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Root of machine-local environment stores: `AWM_HOME/environments`. */
+function environmentsRoot() {
+    return path_1.default.join((0, paths_1.awmHome)(), 'environments');
+}
+function envDir(name) {
+    assertEnvName(name);
+    return path_1.default.join(environmentsRoot(), name);
+}
+function valuesPath(name) {
+    return path_1.default.join(envDir(name), VALUES_FILE);
+}
+function metaPath() {
+    return path_1.default.join(environmentsRoot(), META_FILE);
+}
+function assertEnvName(name) {
+    if (typeof name !== 'string' || name.trim() === '') {
+        throw new EnvironmentStoreError('environment name must be a non-empty string');
+    }
+    if (name.includes('\0')) {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}: NUL byte`);
+    }
+    const lower = name.toLowerCase();
+    if (lower === META_FILE.toLowerCase() || lower === VALUES_FILE.toLowerCase()) {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}: reserved store filename`);
+    }
+    if (name.includes('/') || name.includes('\\') || name.includes('..') || name === '.' || name === '..') {
+        throw new EnvironmentStoreError(`Invalid environment name ${JSON.stringify(name)}`);
+    }
+}
+function readMeta() {
+    const file = metaPath();
+    if (!fs_1.default.existsSync(file))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new EnvironmentStoreError(`Invalid environments meta at ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(raw) || typeof raw.active !== 'string' || raw.active.trim() === '') {
+        throw new EnvironmentStoreError(`Invalid environments meta at ${file}: expected { active: string }`);
+    }
+    return { active: raw.active };
+}
+function writeMeta(meta) {
+    const file = metaPath();
+    assertNotInsideRegistryTree(file);
+    (0, atomic_file_1.writeFileAtomic)(file, JSON.stringify(meta, null, 2) + '\n');
+}
+/** Exactly one active environment per machine; default name `default` (RF-2.2). */
+function getActiveEnvironmentName() {
+    const meta = readMeta();
+    if (!meta)
+        return DEFAULT_ENV_NAME;
+    assertEnvName(meta.active);
+    return meta.active;
+}
+function setActiveEnvironmentName(name) {
+    assertEnvName(name);
+    writeMeta({ active: name });
+}
+function parseStoredEntry(id, raw) {
+    if (!isRecord(raw)) {
+        throw new EnvironmentStoreError(`values.${id} must be an object`);
+    }
+    if (typeof raw.value !== 'string') {
+        throw new EnvironmentStoreError(`values.${id}.value must be a string`);
+    }
+    if (raw.status !== 'fresh' && raw.status !== 'stale' && raw.status !== 'missing') {
+        throw new EnvironmentStoreError(`values.${id}.status must be fresh|stale|missing`);
+    }
+    if (typeof raw.updatedAt !== 'string') {
+        throw new EnvironmentStoreError(`values.${id}.updatedAt must be a string`);
+    }
+    const entry = {
+        value: raw.value,
+        status: raw.status,
+        updatedAt: raw.updatedAt,
+    };
+    if (raw.expiresAt !== undefined) {
+        if (typeof raw.expiresAt !== 'string') {
+            throw new EnvironmentStoreError(`values.${id}.expiresAt must be a string`);
+        }
+        entry.expiresAt = raw.expiresAt;
+    }
+    return entry;
+}
+function readValues(name) {
+    const file = valuesPath(name);
+    if (!fs_1.default.existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        throw new EnvironmentStoreError(`Invalid values.json at ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(raw)) {
+        throw new EnvironmentStoreError(`values.json at ${file} must be a JSON object`);
+    }
+    const out = Object.create(null);
+    for (const [id, entry] of Object.entries(raw)) {
+        if (id === '__proto__' || id === 'constructor' || id === 'prototype') {
+            throw new EnvironmentStoreError(`values.json at ${file}: forbidden fact id ${JSON.stringify(id)}`);
+        }
+        out[id] = parseStoredEntry(id, entry);
+    }
+    return out;
+}
+/**
+ * Resolve a path through any intermediate symlinks (including when the leaf does
+ * not exist yet). Walks up to the nearest existing ancestor, realpaths it, then
+ * re-appends missing segments — same spirit as sensors/ledger realpath containment.
+ */
+function resolvePathForContainment(targetPath) {
+    const absolute = path_1.default.resolve(targetPath);
+    const missing = [];
+    let cursor = absolute;
+    while (!fs_1.default.existsSync(cursor)) {
+        const parent = path_1.default.dirname(cursor);
+        if (parent === cursor)
+            break;
+        missing.unshift(path_1.default.basename(cursor));
+        cursor = parent;
+    }
+    let realBase;
+    try {
+        realBase = fs_1.default.realpathSync.native(cursor);
+    }
+    catch {
+        realBase = cursor;
+    }
+    return missing.length === 0 ? realBase : path_1.default.join(realBase, ...missing);
+}
+function isPathInsideRoot(candidate, root) {
+    if ((0, paths_1.sameExistingPath)(candidate, root))
+        return true;
+    const rel = path_1.default.relative(root, candidate);
+    if (rel === '')
+        return true;
+    if (rel === '..')
+        return false;
+    if (!rel.startsWith(`..${path_1.default.sep}`) && !rel.startsWith('..') && !path_1.default.isAbsolute(rel))
+        return true;
+    const prefix = root.endsWith(path_1.default.sep) ? root : root + path_1.default.sep;
+    return candidate === root || candidate.startsWith(prefix);
+}
+/**
+ * True when `targetPath` (after resolving symlinks) is the same as or nested under
+ * any registry content root. Catches AWM_HOME/environments → registry symlink (RNF-1).
+ *
+ * Always unions `contentRoots()` with any explicit `registryRoots`. An empty
+ * explicit array no longer disables checks — callers that need extra roots pass
+ * them; they cannot opt out of installed content roots.
+ */
+function isInsideRegistryTree(targetPath, registryRoots) {
+    if (typeof targetPath !== 'string' || targetPath.trim() === '') {
+        throw new EnvironmentStoreError('target path must be a non-empty string');
+    }
+    const lexicalTarget = path_1.default.resolve(targetPath);
+    const realTarget = resolvePathForContainment(targetPath);
+    const roots = [...(0, registries_1.contentRoots)(), ...(registryRoots ?? [])];
+    for (const root of roots) {
+        if (typeof root !== 'string' || root.trim() === '')
+            continue;
+        const lexicalRoot = path_1.default.resolve(root);
+        const realRoot = resolvePathForContainment(root);
+        if (isPathInsideRoot(realTarget, realRoot))
+            return true;
+        // Also check lexical forms so non-existent trees still refuse obvious nesting.
+        if (isPathInsideRoot(lexicalTarget, lexicalRoot))
+            return true;
+    }
+    return false;
+}
+function assertNotInsideRegistryTree(targetPath, registryRoots) {
+    if (isInsideRegistryTree(targetPath, registryRoots)) {
+        throw new EnvironmentStoreError(`Refusing to write environment store inside a registry tree: ${targetPath} (RNF-1)`);
+    }
+}
+/**
+ * Atomic write of a values.json document. Refuses targets under registry roots (RNF-1).
+ */
+function writeEnvValue(targetPath, values, opts = {}) {
+    if (typeof targetPath !== 'string' || targetPath.trim() === '') {
+        throw new EnvironmentStoreError('target path must be a non-empty string');
+    }
+    if (!isRecord(values)) {
+        throw new EnvironmentStoreError('values must be an object');
+    }
+    for (const [id, entry] of Object.entries(values)) {
+        parseStoredEntry(id, entry);
+    }
+    // RNF-1: refuse registry-tree targets. Callers that need environmentsRoot placement
+    // (writeFact) pass valuesPath(name); this helper does not re-check environmentsRoot.
+    assertNotInsideRegistryTree(targetPath, opts.registryRoots);
+    (0, atomic_file_1.writeFileAtomic)(targetPath, JSON.stringify(values, null, 2) + '\n');
+}
+function validateValue(definition, value) {
+    if (definition.valueType === 'path') {
+        if (value.trim() === '') {
+            throw new EnvironmentStoreError('path value must be a non-empty string');
+        }
+    }
+    if (definition.valueType === 'enum') {
+        const allowed = definition.values ?? [];
+        if (!allowed.includes(value)) {
+            throw new EnvironmentStoreError(`enum value ${JSON.stringify(value)} is not one of: ${allowed.join(', ')}`);
+        }
+    }
+}
+function withExpiresAt(entry, definition) {
+    if (!definition || definition.durability !== 'volatile') {
+        return {
+            value: entry.value,
+            status: entry.status,
+            updatedAt: entry.updatedAt,
+        };
+    }
+    if (typeof definition.ttl !== 'number' || !Number.isFinite(definition.ttl) || definition.ttl <= 0) {
+        throw new EnvironmentStoreError('volatile fact definition requires a finite ttl > 0');
+    }
+    const ttlSeconds = definition.ttl;
+    const updatedMs = Date.parse(entry.updatedAt);
+    if (!Number.isFinite(updatedMs)) {
+        throw new EnvironmentStoreError(`updatedAt must be a valid ISO timestamp, got ${JSON.stringify(entry.updatedAt)}`);
+    }
+    let expiresAt;
+    try {
+        expiresAt = new Date(updatedMs + ttlSeconds * 1000).toISOString();
+    }
+    catch (e) {
+        if (e instanceof RangeError) {
+            throw new EnvironmentStoreError(`volatile expiresAt out of range for updatedAt=${JSON.stringify(entry.updatedAt)} ttl=${ttlSeconds}`);
+        }
+        throw e;
+    }
+    return { ...entry, expiresAt };
+}
+/**
+ * Write one fact into `environments/<name>/values.json` (RF-2.1). Atomic rename.
+ * When `catalog` is provided, unknown ids error and list `consultedRoots`.
+ */
+function writeFact(name, id, entry, opts = {}) {
+    assertEnvName(name);
+    if (typeof id !== 'string' || id.trim() === '') {
+        throw new EnvironmentStoreError('fact id must be a non-empty string');
+    }
+    if (!isRecord(entry) || typeof entry.value !== 'string') {
+        throw new EnvironmentStoreError('fact entry.value must be a string');
+    }
+    if (entry.status !== 'fresh' && entry.status !== 'stale' && entry.status !== 'missing') {
+        throw new EnvironmentStoreError('fact entry.status must be fresh|stale|missing');
+    }
+    if (typeof entry.updatedAt !== 'string') {
+        throw new EnvironmentStoreError('fact entry.updatedAt must be a string');
+    }
+    let definition = opts.definition;
+    if (opts.catalog) {
+        // Own keys only — prototype members (toString, …) are not catalog facts.
+        if (!Object.hasOwn(opts.catalog.facts, id)) {
+            const roots = opts.consultedRoots?.length
+                ? opts.consultedRoots.join(', ')
+                : '(no catalog roots)';
+            throw new EnvironmentStoreError(`Unknown fact id ${JSON.stringify(id)}; consulted: ${roots}`);
+        }
+        definition = definition ?? opts.catalog.facts[id];
+    }
+    if (definition) {
+        validateValue(definition, entry.value);
+    }
+    const nextEntry = withExpiresAt({
+        value: entry.value,
+        status: entry.status,
+        updatedAt: entry.updatedAt,
+        ...(entry.expiresAt !== undefined ? { expiresAt: entry.expiresAt } : {}),
+    }, definition);
+    const file = valuesPath(name);
+    assertNotInsideRegistryTree(file, opts.registryRoots);
+    const current = readValues(name);
+    const next = { ...current, [id]: nextEntry };
+    writeEnvValue(file, next, { registryRoots: opts.registryRoots });
+    // First write materializes the single active env as the env being written (RF-2.2).
+    if (!readMeta()) {
+        writeMeta({ active: name });
+    }
+}

package/dist/src/core/facts/catalog.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VOLATILE_TTL_SECONDS = void 0;
+exports.parseFactsCatalog = parseFactsCatalog;
+const fs_1 = __importDefault(require("fs"));
+const registries_1 = require("../registries");
+const types_1 = require("./types");
+const VALUE_TYPES = ['string', 'path', 'enum'];
+const RESOLUTIONS = ['prompt'];
+const DURABILITIES = ['durable', 'volatile'];
+const INJECTS = ['reference', 'context'];
+/** Max volatile ttl (seconds) so updatedMs + ttl*1000 stays in a safe Date range. */
+exports.MAX_VOLATILE_TTL_SECONDS = 365 * 24 * 3600;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseFactEntry(id, raw) {
+    if (!types_1.FACT_ID_RE.test(id)) {
+        throw new types_1.FactsCatalogError(`Invalid fact id ${JSON.stringify(id)}: must match ${types_1.FACT_ID_RE}`);
+    }
+    if (!isRecord(raw)) {
+        throw new types_1.FactsCatalogError(`facts.${id} must be an object`);
+    }
+    if (typeof raw.valueType !== 'string' || !VALUE_TYPES.includes(raw.valueType)) {
+        throw new types_1.FactsCatalogError(`facts.${id}.valueType must be one of ${VALUE_TYPES.join(', ')}`);
+    }
+    const valueType = raw.valueType;
+    if (raw.resolution === 'command') {
+        throw new types_1.FactsCatalogError(`facts.${id}: resolution: command is not supported in v1 (use prompt / --value / editable store)`);
+    }
+    if (raw.resolution !== undefined) {
+        if (typeof raw.resolution !== 'string' || !RESOLUTIONS.includes(raw.resolution)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.resolution must be "prompt" in v1`);
+        }
+    }
+    if (raw.durability !== undefined) {
+        if (typeof raw.durability !== 'string' || !DURABILITIES.includes(raw.durability)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.durability must be durable|volatile`);
+        }
+    }
+    if (raw.inject !== undefined) {
+        if (typeof raw.inject !== 'string' || !INJECTS.includes(raw.inject)) {
+            throw new types_1.FactsCatalogError(`facts.${id}.inject must be reference|context`);
+        }
+    }
+    const def = {
+        valueType,
+        resolution: raw.resolution ?? 'prompt',
+        durability: raw.durability ?? 'durable',
+        inject: raw.inject ?? 'reference',
+    };
+    if (raw.description !== undefined) {
+        if (typeof raw.description !== 'string') {
+            throw new types_1.FactsCatalogError(`facts.${id}.description must be a string`);
+        }
+        def.description = raw.description;
+    }
+    if (valueType === 'enum') {
+        if (!Array.isArray(raw.values) || raw.values.length === 0 || raw.values.some((v) => typeof v !== 'string')) {
+            throw new types_1.FactsCatalogError(`facts.${id}.values must be a non-empty string array when valueType is enum`);
+        }
+        def.values = raw.values;
+    }
+    else if (raw.values !== undefined) {
+        throw new types_1.FactsCatalogError(`facts.${id}.values is only allowed when valueType is enum`);
+    }
+    if (raw.ttl !== undefined) {
+        if (typeof raw.ttl !== 'number' || !Number.isFinite(raw.ttl) || raw.ttl < 0) {
+            throw new types_1.FactsCatalogError(`facts.${id}.ttl must be a non-negative number`);
+        }
+        def.ttl = raw.ttl;
+    }
+    if (def.durability === 'volatile') {
+        if (typeof def.ttl !== 'number' ||
+            !Number.isFinite(def.ttl) ||
+            def.ttl <= 0 ||
+            def.ttl > exports.MAX_VOLATILE_TTL_SECONDS) {
+            throw new types_1.FactsCatalogError(`facts.${id}: durability volatile requires finite ttl in (0, ${exports.MAX_VOLATILE_TTL_SECONDS}] seconds`);
+        }
+    }
+    return def;
+}
+function parseObject(raw) {
+    if (!isRecord(raw)) {
+        throw new types_1.FactsCatalogError('facts catalog must be a JSON object');
+    }
+    if (raw.schemaVersion !== 1) {
+        throw new types_1.FactsCatalogError(`facts catalog schemaVersion must be 1, got ${JSON.stringify(raw.schemaVersion)}`);
+    }
+    if (!isRecord(raw.facts)) {
+        throw new types_1.FactsCatalogError('facts catalog must include a facts object');
+    }
+    const facts = {};
+    for (const [id, entry] of Object.entries(raw.facts)) {
+        if (id === '') {
+            throw new types_1.FactsCatalogError('fact id must be non-empty');
+        }
+        facts[id] = parseFactEntry(id, entry);
+    }
+    return { schemaVersion: 1, facts };
+}
+/**
+ * Parse a facts catalog from an in-memory object or from a file path string.
+ * Named errors: {@link FactsCatalogError}.
+ */
+function parseFactsCatalog(rawOrPath) {
+    if (typeof rawOrPath === 'string') {
+        try {
+            if (!(0, registries_1.assertRegularRegistryFile)(rawOrPath)) {
+                throw new types_1.FactsCatalogError(`facts catalog not found at ${rawOrPath}`);
+            }
+        }
+        catch (e) {
+            if (e instanceof types_1.FactsCatalogError)
+                throw e;
+            throw new types_1.FactsCatalogError(e instanceof Error ? e.message : `Cannot inspect facts catalog at ${rawOrPath}: ${String(e)}`);
+        }
+        let text;
+        try {
+            text = fs_1.default.readFileSync(rawOrPath, 'utf-8');
+        }
+        catch (e) {
+            throw new types_1.FactsCatalogError(`Cannot read facts catalog at ${rawOrPath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (e) {
+            throw new types_1.FactsCatalogError(`Invalid JSON in facts catalog at ${rawOrPath}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return parseObject(parsed);
+    }
+    return parseObject(rawOrPath);
+}