agentic-workflow-manager 6.5.2 → 8.1.0

package/dist/src/commands/sensors/status.js

@@ -7,6 +7,8 @@ exports.computeSensorStatus = computeSensorStatus;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const paths_1 = require("../../core/paths");
+const manifest_1 = require("./compatibility/manifest");
+const live_1 = require("./compatibility/live");
 /** First non-flag token after `npx` — the tool the command actually runs. */
 function npxTool(parts) {
     for (let i = 1; i < parts.length; i++) {
@@ -53,16 +55,57 @@ function checkCmd(cmd, cwd) {
     }
     return configCheck(parts, cwd) ?? { ok: true, detail: bin };
 }
-function computeSensorStatus(cwd = process.cwd()) {
+async function computeSensorStatus(cwd = process.cwd()) {
     const manifestPath = path_1.default.join(cwd, '.awm', 'sensors.json');
     if (!fs_1.default.existsSync(manifestPath)) {
         return { overall: 'NOT_CONFIGURED', pack: null, checks: {} };
     }
     let manifest;
     try {
-        manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+        const raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+        const parsed = (0, manifest_1.parseSensorManifest)(raw, manifestPath);
+        if (parsed.kind === 'v2') {
+            const checks = {};
+            let live;
+            try {
+                live = await (0, live_1.resolveLiveCompatibility)(cwd, parsed.pack.pack, parsed.pack.registryRoot, { packSelection: parsed.pack.packSelection });
+            }
+            catch (error) {
+                const detail = `compatibility revalidation failed: ${error instanceof Error ? error.message : String(error)}`;
+                for (const [name, sensor] of Object.entries(parsed.pack.sensors)) {
+                    checks[name] = sensor.enabled === false ? { ok: true, detail: 'disabled' } : { ok: false, detail };
+                }
+                return { overall: 'DEGRADED', pack: parsed.pack.pack, checks };
+            }
+            for (const [name, sensor] of Object.entries(parsed.pack.sensors)) {
+                const state = live.sensors[name];
+                checks[name] = sensor.enabled === false
+                    ? { ok: true, detail: 'disabled' }
+                    : !state
+                        ? { ok: false, detail: 'variant-drift: sensor no longer exists in the live pack; run `awm sensors init`' }
+                        : state.variantId !== sensor.variantId
+                            ? { ok: false, detail: `variant-drift: manifest ${sensor.variantId}, live ${state.variantId ?? 'none'}; run \`awm sensors init\`` }
+                            : state.state === 'certified'
+                                ? { ok: true, detail: `certified (${state.variantId})` }
+                                : state.state === 'not-applicable'
+                                    ? { ok: true, detail: 'not applicable' }
+                                    : { ok: false, detail: `${state.state}: ${state.reason}` };
+            }
+            return { overall: Object.keys(checks).length > 0 && Object.values(checks).every(check => check.ok) ? 'HEALTHY' : 'DEGRADED', pack: parsed.pack.pack, checks };
+        }
+        manifest = parsed.pack;
     }
     catch {
+        // Preserve the historic diagnostic path for a hand-edited legacy manifest:
+        // malformed v2 is fail-closed, while a legacy `sensors:null` is surfaced as
+        // degraded rather than crashing the status command.
+        try {
+            const raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+            if (raw && typeof raw === 'object' && !Array.isArray(raw) && !('schemaVersion' in raw) && typeof raw.pack === 'string') {
+                return { overall: 'DEGRADED', pack: raw.pack, checks: {} };
+            }
+        }
+        catch { /* malformed JSON is not configured */ }
         return { overall: 'NOT_CONFIGURED', pack: null, checks: {} };
     }
     const checks = {};
@@ -84,6 +127,7 @@ function computeSensorStatus(cwd = process.cwd()) {
     if (Object.keys(manifest.sensors ?? {}).length === 0) {
         return { overall: 'DEGRADED', pack: manifest.pack, checks };
     }
-    const allOk = Object.values(checks).every(c => c.ok);
-    return { overall: allOk ? 'HEALTHY' : 'DEGRADED', pack: manifest.pack, checks };
+    // A legacy manifest may be operational (the checks are still useful), but it
+    // has no versioned/structured contract and must never present as certified.
+    return { overall: 'DEGRADED', pack: manifest.pack, checks };
 }

package/dist/src/commands/sync.js

@@ -77,6 +77,13 @@ async function runSyncCore(options, deps = {}) {
         if (r.action === 'error')
             console.warn(picocolors_1.default.yellow(`  ⚠  registry ${r.name}: ${r.error}`));
     }
+    try {
+        (0, registries_1.assertSyncedRegistriesUsable)(syncResults);
+    }
+    catch (e) {
+        console.error(picocolors_1.default.red(e.message));
+        return { code: 1, selectedAgents };
+    }
     // Gate minCliVersion (WS-4) before pins (contract gates first — CONSTITUTION).
     try {
         (0, registries_1.assertRegistryGates)(d.verifyMinCliVersions());

package/dist/src/core/bundles.js

@@ -16,6 +16,41 @@ const registries_1 = require("./registries");
 function catalogPath(contentDir) {
     return path_1.default.join(contentDir, 'catalog.json');
 }
+function bundleManifestPath(contentDir, source) {
+    const root = path_1.default.resolve(contentDir);
+    const manifest = path_1.default.resolve(root, source, 'bundle.json');
+    const relative = path_1.default.relative(root, manifest);
+    if (relative === '..' || relative.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(relative)) {
+        throw new Error(`Invalid bundle source "${source}" in ${catalogPath(contentDir)}: it must remain inside the registry content root.`);
+    }
+    let rootStat;
+    try {
+        rootStat = fs_1.default.lstatSync(root);
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect registry content root ${root}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`Registry content root ${root} must be a regular directory`);
+    }
+    let current = root;
+    for (const segment of relative.split(path_1.default.sep)) {
+        current = path_1.default.join(current, segment);
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(current);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                break;
+            throw new Error(`Cannot inspect registry bundle path ${current}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Registry bundle path ${current} must not be a symbolic link`);
+        }
+    }
+    return manifest;
+}
 /** Lee `catalog.json` de un registry.
  *
  *  El contenido de un registry es INPUT NO CONFIABLE (un registry de equipo,
@@ -28,7 +63,7 @@ function catalogPath(contentDir) {
  *  dos eran los que faltaban. */
 function readCatalog(contentDir) {
     const file = catalogPath(contentDir);
-    if (!fs_1.default.existsSync(file))
+    if (!(0, registries_1.assertRegularRegistryFile)(file))
         return [];
     let parsed;
     try {
@@ -74,8 +109,8 @@ function discoverBundles(contentDir) {
     const entries = readCatalog(contentDir);
     const bundles = [];
     for (const entry of entries) {
-        const manifestPath = path_1.default.join(contentDir, entry.source, 'bundle.json');
-        if (!fs_1.default.existsSync(manifestPath))
+        const manifestPath = bundleManifestPath(contentDir, entry.source);
+        if (!(0, registries_1.assertRegularRegistryFile)(manifestPath))
             continue;
         let raw;
         try {

package/dist/src/core/init/steps.js

@@ -65,8 +65,8 @@ exports.defaultActions = {
         method: o.method,
         contentDir: o.contentDir,
     }),
-    initSensors: (o) => {
-        const result = (0, init_1.initSensors)({ cwd: o.cwd, registryRoot: o.registryRoot, configure: o.configure });
+    initSensors: async (o) => {
+        const result = await (0, init_1.initSensors)({ cwd: o.cwd, registryRoot: o.registryRoot, configure: o.configure });
         // `unavailablePack`/`manifest` viajan a proposito: `stepSensors` los reporta.
         // Este wrapper proyectaba solo `detection`, asi que cualquier hallazgo nuevo de
         // initSensors moria aca en silencio antes de llegar al step que lo muestra.
@@ -216,6 +216,9 @@ function stepDevCore(d) {
     // `awm doctor` decia `healthy`. Su propio `globalUnsupportedReason` ya dice
     // que hay que instalar por proyecto, asi que eso es lo que se hace.
     const localOnly = (0, providers_1.providerFor)(d.agent).skill.global === null;
+    if (localOnly && d.machineOnly) {
+        return ok('machine.devCore', 'machine', 'skipped', `${(0, providers_1.providerFor)(d.agent).label} provides skills at project scope — deferred until project initialization`);
+    }
     for (const bundleName of toInstall) {
         d.actions.installBundle({
             bundleName,
@@ -316,13 +319,13 @@ function stepActivation(d) {
     return ok('project.activation', 'project', 'applied');
 }
 /** Step 7 – Initialize the sensor manifest if absent. */
-function stepSensors(d) {
+async function stepSensors(d) {
     const proj = d.ctx.project;
     if (!proj)
         return ok('project.sensors', 'project', 'skipped', 'no project');
     if (proj.sensors.present)
         return ok('project.sensors', 'project', 'skipped');
-    const res = d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
+    const res = await d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
     // A registry without the detected pack yields a fallback (or empty) manifest. The
     // step still succeeded — a manifest was written — but reporting a bare 'applied'
     // would let `awm init` hand back a quality gate that measures less than the

package/dist/src/core/ledger/scan.js

@@ -0,0 +1,228 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LEDGER_SCAN_LIMITS = void 0;
+exports.scanProjectLedgers = scanProjectLedgers;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+exports.DEFAULT_LEDGER_SCAN_LIMITS = {
+    maxFiles: 256,
+    maxFileBytes: 4 * 1024 * 1024,
+    maxEntries: 20_000,
+    maxLineBytes: 64 * 1024,
+    maxJsonDepth: 16,
+    maxRefsPerClass: 128,
+};
+function isWithin(root, candidate) {
+    const relative = path_1.default.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative));
+}
+function assertDirectoryInside(root, directory) {
+    if (!fs_1.default.existsSync(directory))
+        return false;
+    const stat = fs_1.default.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`ledger directory is unsafe: ${directory}`);
+    return isWithin(root, fs_1.default.realpathSync(directory));
+}
+function isJsonDepthWithinLimit(raw, maxDepth) {
+    let depth = 0;
+    let quoted = false;
+    let escaped = false;
+    for (const char of raw) {
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"')
+            quoted = true;
+        else if (char === '{' || char === '[') {
+            depth += 1;
+            if (depth > maxDepth)
+                return false;
+        }
+        else if (char === '}' || char === ']')
+            depth -= 1;
+    }
+    return true;
+}
+function boundedLimits(overrides) {
+    if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+        throw new Error('ledger scan limits must be an object');
+    }
+    const limits = { ...exports.DEFAULT_LEDGER_SCAN_LIMITS, ...overrides };
+    for (const value of Object.values(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error('ledger scan limits must be positive safe integers');
+    }
+    return limits;
+}
+function relativeSource(root, target, line) {
+    return `${relativePath(root, target)}:${line}`;
+}
+function relativePath(root, target) {
+    return path_1.default.relative(root, target).split(path_1.default.sep).join('/');
+}
+function compareCandidates(a, b) {
+    return a.sourcePath < b.sourcePath ? -1 : a.sourcePath > b.sourcePath ? 1 : 0;
+}
+/**
+ * Reads one global bounded window across the direct ledger directories, then
+ * sorts only the retained candidates. This deliberately does not claim to
+ * find a globally lexical prefix in an unbounded directory: the extra
+ * candidate is a truncation witness, and no later candidate is opened or
+ * retained from either active or archive storage.
+ */
+function collectBoundedCandidates(root, directories, maxFiles) {
+    const candidates = [];
+    const capacity = maxFiles + 1;
+    let truncated = false;
+    for (const { directory, archive } of directories) {
+        if (candidates.length >= capacity)
+            break;
+        const handle = fs_1.default.opendirSync(directory);
+        try {
+            let item;
+            while ((item = handle.readSync()) !== null) {
+                if (!item.name.endsWith('.jsonl'))
+                    continue;
+                const target = path_1.default.join(directory, item.name);
+                candidates.push({ isArchive: archive, target, sourcePath: relativePath(root, target) });
+                if (candidates.length === capacity) {
+                    truncated = true;
+                    break;
+                }
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+    }
+    candidates.sort(compareCandidates);
+    return { candidates, truncated: truncated || candidates.length > maxFiles };
+}
+/** Reads only direct .jsonl children of active/archive ledger roots; never follows links. */
+function scanProjectLedgers(projectRoot, overrides = {}) {
+    if (typeof projectRoot !== 'string' || !path_1.default.isAbsolute(projectRoot))
+        throw new Error('projectRoot must be an absolute path');
+    const limits = boundedLimits(overrides);
+    const root = fs_1.default.realpathSync(projectRoot);
+    const ledgerRoot = path_1.default.join(root, '.awm', 'ledger');
+    const sources = {
+        activeFiles: 0, archivedFiles: 0, validEntries: 0, validFindings: 0, skippedFindings: 0, skippedByReason: {},
+    };
+    const entries = [];
+    const skip = (reason) => {
+        sources.skippedFindings += 1;
+        sources.skippedByReason[reason] = (sources.skippedByReason[reason] ?? 0) + 1;
+    };
+    if (!fs_1.default.existsSync(ledgerRoot))
+        return { entries, sources, omittedEvidenceRefs: 0 };
+    if (!assertDirectoryInside(root, path_1.default.join(root, '.awm')) || !assertDirectoryInside(root, ledgerRoot)) {
+        throw new Error('ledger directory escapes project root');
+    }
+    const directories = [{ directory: ledgerRoot, archive: false }];
+    const archive = path_1.default.join(ledgerRoot, 'archive');
+    if (fs_1.default.existsSync(archive)) {
+        if (!assertDirectoryInside(root, archive))
+            throw new Error('ledger archive directory escapes project root');
+        directories.push({ directory: archive, archive: true });
+    }
+    let filesSeen = 0;
+    let linesSeen = 0;
+    let entryLimitReached = false;
+    let omittedEvidenceRefs = 0;
+    const evidenceRefsByClass = new Map();
+    const collected = collectBoundedCandidates(root, directories, limits.maxFiles);
+    for (const { isArchive, target } of collected.candidates.slice(0, limits.maxFiles)) {
+        if (entryLimitReached)
+            break;
+        filesSeen += 1;
+        const stat = fs_1.default.lstatSync(target);
+        if (stat.isSymbolicLink()) {
+            skip('symlink-entry');
+            continue;
+        }
+        if (!stat.isFile()) {
+            skip('nonregular-entry');
+            continue;
+        }
+        const real = fs_1.default.realpathSync(target);
+        if (!isWithin(root, real)) {
+            skip('path-escape');
+            continue;
+        }
+        if (stat.size > limits.maxFileBytes) {
+            skip('file-too-large');
+            continue;
+        }
+        if (isArchive)
+            sources.archivedFiles += 1;
+        else
+            sources.activeFiles += 1;
+        const lines = fs_1.default.readFileSync(target, 'utf-8').split('\n');
+        for (let index = 0; index < lines.length; index += 1) {
+            const raw = lines[index];
+            if (!raw.trim())
+                continue;
+            if (linesSeen >= limits.maxEntries) {
+                skip('entry-limit');
+                entryLimitReached = true;
+                break;
+            }
+            linesSeen += 1;
+            if (Buffer.byteLength(raw, 'utf-8') > limits.maxLineBytes) {
+                skip('line-too-large');
+                continue;
+            }
+            if (!isJsonDepthWithinLimit(raw, limits.maxJsonDepth)) {
+                skip('json-too-deep');
+                continue;
+            }
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                skip('invalid-json');
+                continue;
+            }
+            const source = relativeSource(root, target, index + 1);
+            const parsed = (0, types_1.parseLedgerEntry)(value, source);
+            if (!parsed.ok) {
+                skip(parsed.reason);
+                continue;
+            }
+            sources.validEntries += 1;
+            if (parsed.entry.polarity === 'finding') {
+                sources.validFindings += 1;
+                const defectClass = parsed.entry.defectClass ?? 'unclassified';
+                const count = evidenceRefsByClass.get(defectClass) ?? 0;
+                const evidenceRef = count < limits.maxRefsPerClass ? source : null;
+                if (evidenceRef === null) {
+                    omittedEvidenceRefs += 1;
+                    // The finding remains available for recurrence analysis, but
+                    // its public evidence is deliberately omitted. Record the
+                    // truncation through the same typed source contract as every
+                    // other scan bound so downstream renderers cannot call it a
+                    // complete report.
+                    skip('evidence-ref-limit');
+                }
+                else
+                    evidenceRefsByClass.set(defectClass, count + 1);
+                entries.push({ entry: parsed.entry, source, evidenceRef });
+            }
+        }
+    }
+    if (!entryLimitReached && collected.truncated)
+        skip('file-limit');
+    return { entries, sources, omittedEvidenceRefs };
+}

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

@@ -12,8 +12,75 @@ exports.archiveLedger = archiveLedger;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const types_1 = require("./types");
 const cluster_1 = require("./cluster");
 const LEDGER_DIR = path_1.default.join('.awm', 'ledger');
+function isWithin(root, candidate) {
+    const relative = path_1.default.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative));
+}
+function assertSafeDirectory(directory, root, name) {
+    const stat = fs_1.default.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`unsafe ledger ${name} directory`);
+    const real = fs_1.default.realpathSync(directory);
+    if (!isWithin(root, real))
+        throw new Error(`ledger ${name} directory escapes its root`);
+    return real;
+}
+function sourceExists(source) {
+    try {
+        fs_1.default.lstatSync(source);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function assertSafeLedgerSource(source, ledgerRoot) {
+    const stat = fs_1.default.lstatSync(source);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error('unsafe ledger source');
+    const real = fs_1.default.realpathSync(source);
+    if (!isWithin(ledgerRoot, real))
+        throw new Error('ledger source escapes ledger directory');
+}
+function ledgerFilename(branch) {
+    if (typeof branch !== 'string'
+        || branch.length === 0
+        || branch.includes('\\')
+        || path_1.default.posix.isAbsolute(branch)
+        || path_1.default.win32.isAbsolute(branch)
+        || branch.split('/').some(segment => segment === '.' || segment === '..')) {
+        throw new Error('invalid ledger branch');
+    }
+    return branch.replace(/\//g, '__');
+}
+function archiveLabel(label) {
+    if (typeof label !== 'string'
+        || label.length === 0
+        || label === '.'
+        || label.includes('..')
+        || /[/\\]/.test(label)
+        || path_1.default.posix.isAbsolute(label)
+        || path_1.default.win32.isAbsolute(label)) {
+        throw new Error('invalid ledger label');
+    }
+    return label;
+}
+function destinationExists(destination) {
+    try {
+        fs_1.default.lstatSync(destination);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
 function detectBranch(cwd) {
     try {
         const b = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
@@ -26,28 +93,15 @@ function detectBranch(cwd) {
     }
 }
 function ledgerPath(cwd, branch) {
-    const safe = branch.replace(/\//g, '__');
-    return path_1.default.join(cwd, LEDGER_DIR, `${safe}.jsonl`);
+    return path_1.default.join(cwd, LEDGER_DIR, `${ledgerFilename(branch)}.jsonl`);
 }
 function addEntry(cwd, entry) {
+    const parsed = (0, types_1.parseLedgerEntry)(entry, 'ledger entry');
+    if (!parsed.ok)
+        throw new Error(`invalid ledger entry: ${parsed.reason}`);
     const p = ledgerPath(cwd, entry.branch);
     fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
-    fs_1.default.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
-}
-/** Required LedgerEntry fields that `cluster.ts` reads unconditionally
- * (`signature`, `desc`, `ref` when present). A JSONL line can be syntactically
- * valid JSON while still being shape-invalid (e.g. missing `desc`) — that's
- * not a parse error, so it needs its own check, extending the same "skip
- * malformed line" policy this function already applies to JSON syntax errors. */
-function isWellFormedEntry(x) {
-    if (!x || typeof x !== 'object')
-        return false;
-    const e = x;
-    return typeof e.signature === 'string'
-        && typeof e.desc === 'string'
-        && typeof e.branch === 'string'
-        && typeof e.polarity === 'string'
-        && (e.ref === undefined || typeof e.ref === 'string');
+    fs_1.default.appendFileSync(p, JSON.stringify(parsed.entry) + '\n', 'utf-8');
 }
 function listEntries(cwd, branch) {
     const p = ledgerPath(cwd, branch);
@@ -59,9 +113,9 @@ function listEntries(cwd, branch) {
         if (!trimmed)
             continue;
         try {
-            const parsed = JSON.parse(trimmed);
-            if (isWellFormedEntry(parsed))
-                out.push(parsed);
+            const parsed = (0, types_1.parseLedgerEntry)(JSON.parse(trimmed), p);
+            if (parsed.ok)
+                out.push(parsed.entry);
         }
         catch { /* skip malformed line */ }
     }
@@ -71,12 +125,22 @@ function recurring(cwd, branch, min) {
     return (0, cluster_1.clusterEntries)(listEntries(cwd, branch), min);
 }
 function archiveLedger(cwd, branch, label) {
+    const safeLabel = archiveLabel(label);
     const src = ledgerPath(cwd, branch);
-    if (!fs_1.default.existsSync(src))
+    if (!sourceExists(src))
         return false;
-    const safe = branch.replace(/\//g, '__');
-    const dst = path_1.default.join(cwd, LEDGER_DIR, 'archive', `${safe}-${label}.jsonl`);
-    fs_1.default.mkdirSync(path_1.default.dirname(dst), { recursive: true });
+    const safe = ledgerFilename(branch);
+    const projectRoot = fs_1.default.realpathSync(cwd);
+    const ledgerRoot = path_1.default.join(projectRoot, LEDGER_DIR);
+    const safeLedgerRoot = assertSafeDirectory(ledgerRoot, projectRoot, 'root');
+    assertSafeLedgerSource(src, safeLedgerRoot);
+    const archiveRoot = path_1.default.join(ledgerRoot, 'archive');
+    if (!sourceExists(archiveRoot))
+        fs_1.default.mkdirSync(archiveRoot);
+    const safeArchiveRoot = assertSafeDirectory(archiveRoot, safeLedgerRoot, 'archive');
+    const dst = path_1.default.join(safeArchiveRoot, `${safe}-${safeLabel}.jsonl`);
+    if (destinationExists(dst))
+        throw new Error(`ledger archive already exists: ${dst}`);
     fs_1.default.renameSync(src, dst);
     return true;
 }

package/dist/src/core/ledger/types.js

@@ -1,2 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFECT_CLASS = void 0;
+exports.parseLedgerEntry = parseLedgerEntry;
+exports.DEFECT_CLASS = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isPolarity(value) {
+    return value === 'win' || value === 'finding';
+}
+function isLedgerClass(value) {
+    return value === 'structural' || value === 'logica' || value === 'proceso' || value === 'seguridad';
+}
+function isSeverity(value) {
+    return value === 'blocker' || value === 'important' || value === 'minor' || value === 'info';
+}
+/** Validates the durable JSONL boundary. Missing defectClass is deliberately legacy-valid. */
+function parseLedgerEntry(input, source) {
+    if (typeof source !== 'string')
+        throw new Error('ledger parse source must be a string');
+    if (!isRecord(input))
+        return { ok: false, source, reason: 'not-object' };
+    if (!isPolarity(input.polarity) || !isLedgerClass(input.class) || !isSeverity(input.severity)) {
+        return { ok: false, source, reason: 'invalid-enum' };
+    }
+    for (const field of ['ts', 'branch', 'phase', 'source_skill', 'signature', 'desc']) {
+        if (typeof input[field] !== 'string')
+            return { ok: false, source, reason: 'invalid-fields' };
+    }
+    if ('ref' in input && input.ref !== undefined && typeof input.ref !== 'string') {
+        return { ok: false, source, reason: 'invalid-ref' };
+    }
+    if ('defectClass' in input && input.defectClass !== undefined
+        && (typeof input.defectClass !== 'string' || !exports.DEFECT_CLASS.test(input.defectClass))) {
+        return { ok: false, source, reason: 'invalid-defect-class' };
+    }
+    return {
+        ok: true,
+        entry: {
+            ts: input.ts,
+            branch: input.branch,
+            phase: input.phase,
+            source_skill: input.source_skill,
+            polarity: input.polarity,
+            class: input.class,
+            signature: input.signature,
+            severity: input.severity,
+            desc: input.desc,
+            ...(typeof input.ref === 'string' ? { ref: input.ref } : {}),
+            // Keep the durable legacy distinction visible to consumers: an older
+            // entry is valid, but has no reusable classification yet.
+            defectClass: typeof input.defectClass === 'string' ? input.defectClass : undefined,
+        },
+    };
+}

package/dist/src/core/paths.js

@@ -174,10 +174,11 @@ function resolveOnPath(bin) {
  * cohorte no llegaba nunca ni a `SERIAL` ni a `ACTIVE`. Un solo bug de comparación, quince
  * tests en cascada.
  *
- * La identidad se toma del filesystem — `(dev, ino)` — que es agnóstica a separadores, a
- * mayúsculas y a nombres cortos. Cuando el volumen no expone inode (`ino === 0`, posible en
- * algunos filesystems de Windows) se cae a `realpathSync.native` — que sí resuelve 8.3 vía
- * la API del SO — normalizando separadores y capitalización.
+ * La identidad se toma primero de `realpathSync.native`, que resuelve la ruta con la API
+ * del SO (incluyendo nombres cortos 8.3) antes de normalizar separadores y capitalización.
+ * En POSIX, dos hard links de archivo conservan el mismo `(dev, ino)` aunque el realpath
+ * mantenga sus nombres distintos; ese fallback preserva su identidad. En Windows no se usa:
+ * dos directorios temporales distintos pueden reportar el mismo par de metadatos.
  *
  * Cualquier fallo de `stat` significa que al menos una no existe: `false`. La identidad
  * nunca se afirma sin prueba.
@@ -192,10 +193,6 @@ function sameExistingPath(a, b) {
     catch {
         return false;
     }
-    // `ino === 0` en AMBOS lados no prueba identidad: probaría que el filesystem no la
-    // reporta. Tratarlo como match haría coincidir dos rutas cualesquiera del mismo volumen.
-    if (sa.ino !== 0 && sb.ino !== 0)
-        return sa.dev === sb.dev && sa.ino === sb.ino;
     const canonical = (p) => {
         try {
             const real = fs_1.default.realpathSync.native(p).replaceAll('\\', '/');
@@ -207,5 +204,9 @@ function sameExistingPath(a, b) {
     };
     const ca = canonical(a);
     const cb = canonical(b);
-    return ca !== null && ca === cb;
+    if (ca === null || cb === null)
+        return false;
+    if (ca === cb)
+        return true;
+    return !isWindowsNative() && sa.ino !== 0 && sb.ino !== 0 && sa.dev === sb.dev && sa.ino === sb.ino;
 }