agentic-workflow-manager 6.2.0 → 6.3.0

package/dist/src/core/tracks/join.js

@@ -0,0 +1,185 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrationLockBlockedError = exports.decideJoinReconciliation = void 0;
+exports.validateJoinReadiness = validateJoinReadiness;
+exports.planJoinOrder = planJoinOrder;
+exports.acquireIntegrationLock = acquireIntegrationLock;
+exports.releaseIntegrationLock = releaseIntegrationLock;
+exports.stopControllerGenerationConfirmed = stopControllerGenerationConfirmed;
+// R5.2/R5.8/R5.9/R6.3/R6.4/R6.5/C7 (Task 10): quiescencia del plan y
+// precondiciones de join. Dos familias de funciones acá:
+//   - `validateJoinReadiness`/`planJoinOrder`: PURAS, sin I/O — misma
+//     autoridad única que `protocol.ts`, pero para el momento previo al
+//     primer merge (Task 11 las consume; acá solo se construyen y prueban).
+//   - `acquireIntegrationLock`/`releaseIntegrationLock`/
+//     `stopControllerGenerationConfirmed`: efectos reales, modelados 1:1
+//     sobre `watch/lock.ts` (`acquireLock`/`releaseLock`/`LockBlockedError`)
+//     y sobre el patrón de terminación con identidad confirmada que
+//     `supervisor.ts` ya usa en su camino COMPLETE — nunca un kill crudo.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const store_1 = require("../journal/store");
+const paths_1 = require("../journal/paths");
+const process_1 = require("../journal/process");
+const atomic_file_1 = require("../atomic-file");
+const types_1 = require("../journal/types");
+// R6.8/R6.9/C7 (Task 11): `decideJoinReconciliation` YA vive en `protocol.ts`
+// desde Task 1 (`reconcileProtocol` la llama para su handler de
+// `join-observation`) — regla de autoridad única: esta task NO crea una
+// segunda copia acá. `join-reconcile.test.ts` prueba la matriz completa
+// IMPORTANDO este re-export, así que cualquier fix que la matriz descubra
+// tiene que vivir en `protocol.ts` (y volver a correr la exploración de
+// Task 1 en el mismo commit) para que el test del gate siga significando algo.
+var protocol_1 = require("./protocol");
+Object.defineProperty(exports, "decideJoinReconciliation", { enumerable: true, get: function () { return protocol_1.decideJoinReconciliation; } });
+/** Autoridad única de precondiciones de join: TODO hecho indemostrable o
+ *  adverso bloquea — nunca se descarta un dirty path del mensaje (R6.5), y
+ *  el HEAD congelado se compara byte a byte contra el HEAD real observado
+ *  (protege contra el track mutando su propio worktree después de FROZEN). */
+function validateJoinReadiness(x) {
+    const reasons = [];
+    if (x.actualHeadSha !== x.frozenHeadSha)
+        reasons.push(`HEAD cambió: esperado ${x.frozenHeadSha}, actual ${x.actualHeadSha}`);
+    if (x.dirtyPaths.length > 0)
+        reasons.push(`worktree sucio: ${[...x.dirtyPaths].sort().join(', ')}`);
+    if (!x.gatePass)
+        reasons.push('gate local rojo');
+    if (x.liveJobs > 0)
+        reasons.push(`${x.liveJobs} jobs vivos`);
+    if (x.supervisorAlive)
+        reasons.push('supervisor de track vivo');
+    if (x.lockExists)
+        reasons.push('lock de track retenido');
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+/** Ownership REAL (post-hoc, desde commits ya congelados — ver
+ *  `assessActualOwnership` en `ownership.ts`), no la declaración de T4: un
+ *  solo track con `outsideOwnership` no vacío serializa el ORDEN de los
+ *  joins restantes (R5.8/R5.9) — nunca revierte merges ya hechos. Un
+ *  `globalClasses` no vacío además invalida el paralelismo de la cohorte
+ *  entera (C5): `parallelInvalidatedBy` nombra `<trackId>:<clase>` para cada
+ *  hallazgo, para que el consumidor (T10 Step 6 en `tracks.ts`) lo persista
+ *  como `cohortParallelInvalidatedBy` y ningún `awm watch` futuro lo pierda. */
+function planJoinOrder(trackIds, assessments) {
+    const violations = {};
+    const parallelInvalidatedBy = [];
+    let serial = false;
+    for (const trackId of trackIds) {
+        const a = assessments[trackId];
+        if (a === undefined)
+            continue;
+        if (a.outsideOwnership.length > 0) {
+            violations[trackId] = [...a.outsideOwnership];
+            serial = true;
+        }
+        if (a.globalClasses.length > 0) {
+            serial = true;
+            for (const cls of a.globalClasses)
+                parallelInvalidatedBy.push(`${trackId}:${cls}`);
+        }
+    }
+    return { mode: serial ? 'serial-joins' : 'parallel-joins', order: [...trackIds], violations, parallelInvalidatedBy };
+}
+// --- Lock de integración (R5.8/R5.9/C7) -------------------------------------
+/** Identidad indemostrable en el lock: BLOQUEAR con error distinto — mismo
+ *  criterio que `LockBlockedError` de `watch/lock.ts`, nunca se reclama lo
+ *  que no se puede probar muerto. */
+class IntegrationLockBlockedError extends Error {
+    constructor(message) { super(message); this.name = 'IntegrationLockBlockedError'; }
+}
+exports.IntegrationLockBlockedError = IntegrationLockBlockedError;
+function isWellFormedIntegrationLockBody(x) {
+    return (0, types_1.isWellFormedProcessRef)(x)
+        && typeof x.planJournalId === 'string'
+        && typeof x.expectedPlanHeadSha === 'string';
+}
+/** Modelado 1:1 sobre `acquireLock` (`watch/lock.ts`): creación EXCLUSIVA
+ *  real (`wx`), 0600, fsync de archivo + directorio, identidad completa
+ *  (`ProcessRef`) más el contexto de integración (`planJournalId` +
+ *  `expectedPlanHeadSha`) para que cualquier lector externo pueda auditar
+ *  QUÉ mutación se autorizó, no solo QUIÉN la retiene. */
+function acquireIntegrationLock(planRoot, ctx) {
+    const lp = (0, paths_1.integrationLockPath)(planRoot);
+    fs_1.default.mkdirSync(path_1.default.dirname(lp), { recursive: true, mode: 0o700 });
+    const self = (0, process_1.captureSelfRef)(crypto_1.default.randomBytes(8).toString('hex'));
+    const body = { ...self, ...ctx };
+    const serialized = JSON.stringify(body, null, 2) + '\n';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs_1.default.openSync(lp, 'wx', 0o600);
+            try {
+                fs_1.default.writeFileSync(fd, serialized);
+                fs_1.default.fsyncSync(fd);
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+            (0, atomic_file_1.fsyncDirSync)(path_1.default.dirname(lp));
+            return { ref: self, path: lp };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        let prior;
+        try {
+            prior = JSON.parse(fs_1.default.readFileSync(lp, 'utf8'));
+        }
+        catch {
+            throw new IntegrationLockBlockedError(`integration.lock ilegible en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama)`);
+        }
+        if (!isWellFormedIntegrationLockBody(prior)) {
+            throw new IntegrationLockBlockedError(`integration.lock con shape inválido en ${lp}: identidad indemostrable — BLOQUEADO (no se reclama)`);
+        }
+        if ((0, process_1.refIsAlive)(prior)) {
+            throw new Error(`integración activa (pid ${prior.pid}) sobre este plan`);
+        }
+        process.stderr.write('awm watch: integration.lock previo con identidad muerta probada — reclamando\n');
+        fs_1.default.rmSync(lp, { force: true });
+    }
+    throw new Error('no se pudo adquirir integration.lock tras reintento único (carrera persistente)');
+}
+function releaseIntegrationLock(handle) {
+    try {
+        const onDisk = JSON.parse(fs_1.default.readFileSync(handle.path, 'utf8'));
+        if (onDisk.spawnNonce === handle.ref.spawnNonce)
+            fs_1.default.rmSync(handle.path);
+    }
+    catch { /* ya ausente o ilegible: no tocar lo que no es nuestro */ }
+}
+// --- Pausa de la generación del plan (R5.8/C7) ------------------------------
+/** "Ningún controller administrado sigue corriendo durante el lease" (Step 5
+ *  del plan R5-T10): a diferencia de `resolveGeneration` (generations.ts,
+ *  gobierna reemplazo POR STALL, con backoff/adapter), esto es una pausa
+ *  ADMINISTRATIVA incondicional antes de integrar — termina, con identidad
+ *  confirmada, cualquier generación del PLAN todavía activa. Sin generación
+ *  activa, es un no-op (ya está pausado). Cualquier fallo en confirmar la
+ *  terminación lanza — jamás se adquiere el lock de integración con un
+ *  controller potencialmente vivo. */
+async function stopControllerGenerationConfirmed(planRoot, branch, grace) {
+    const r = (0, store_1.readJournal)(planRoot, branch);
+    if (r.corrupt || r.state === null)
+        throw new Error('journal corrupto: no se puede pausar la generación del plan (R1.6)');
+    const s = r.state;
+    // Misma definición que `activeGeneration` (`watch/generations.ts`),
+    // reimplementada inline: `core/tracks` no depende de `commands/watch`
+    // (dirección de capas), y esto es una sola línea sin lógica propia que
+    // proteger de una duplicación real.
+    const gen = s.generations.find((g) => g.state === 'active' || g.state === 'controller-suspected-stall');
+    if (gen === undefined)
+        return;
+    for (const ref of [gen.processRef, gen.wrapperRef]) {
+        if (ref === undefined || (0, process_1.groupIsGone)(ref.processGroup))
+            continue;
+        const confirmed = await (0, process_1.terminateGroupConfirmed)(ref, grace);
+        if (!confirmed)
+            throw new Error(`no se pudo confirmar la terminación de la generación ${gen.n} del plan antes de integrar (C7)`);
+    }
+    gen.state = 'terminated';
+    (0, store_1.writeJournal)(planRoot, branch, s);
+    (0, store_1.appendEvent)(planRoot, branch, { kind: 'plan-generation-stopped', n: gen.n });
+}

package/dist/src/core/tracks/ownership.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ownershipPrefix = ownershipPrefix;
+exports.canonicalResource = canonicalResource;
+exports.assessDeclaredIndependence = assessDeclaredIndependence;
+exports.assessActualOwnership = assessActualOwnership;
+const path_1 = __importDefault(require("path"));
+const GLOBAL = [
+    { kind: 'lockfile', re: /(^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|Cargo\.lock|poetry\.lock)$/i },
+    { kind: 'manifest', re: /(^|\/)(?:package\.json|Cargo\.toml|pyproject\.toml)$/i },
+    { kind: 'migration', re: /(^|\/)(?:migrations?|schema)\//i },
+    { kind: 'snapshot', re: /(?:^|\/)(__snapshots__\/|[^/]+\.snap$)/i },
+    { kind: 'generated', re: /(^|\/)(?:dist|generated|coverage)\//i },
+];
+const canon = (p) => path_1.default.posix.normalize(p.replaceAll('\\', '/')).replace(/^\.\//, '');
+const key = (p) => canon(p).toLocaleLowerCase('en-US');
+const GLOB_CHARS = /[*?[\]{}]/;
+/**
+ * Formas soportadas: `dir/sub/file.ts`, `dir/`, `dir/*`, `dir/**`. Cualquier otro glob
+ * (intermedio, `?`, clases, llaves) se rechaza: un patrón que no sabemos expandir no puede
+ * usarse para AFIRMAR que dos tracks no se pisan.
+ */
+function ownershipPrefix(owner) {
+    const trimmed = canon(owner).replace(/\/(?:\*\*|\*)$/, '/');
+    if (GLOB_CHARS.test(trimmed))
+        throw new Error(`ownership no soporta este glob: ${owner}`);
+    return key(trimmed);
+}
+const covers = (owner, actual) => {
+    const o = ownershipPrefix(owner);
+    const a = key(actual);
+    return o.endsWith('/') ? a === o.slice(0, -1) || a.startsWith(o) : a === o;
+};
+/** Un patrón inexpandible cuenta como intersección: nunca habilita paralelismo por ignorancia. */
+const intersects = (left, right) => {
+    try {
+        return covers(left, right) || covers(right, left);
+    }
+    catch {
+        return true;
+    }
+};
+/** Simétrico del anterior: un patrón inexpandible nunca prueba propiedad. */
+const proves = (owner, actual) => {
+    try {
+        return covers(owner, actual);
+    }
+    catch {
+        return false;
+    }
+};
+function canonicalResource(raw) {
+    const match = raw.match(/^([a-z][a-z0-9-]*):(.+)$/i);
+    if (match === null || match[2].trim().length === 0)
+        throw new Error(`recurso debe usar <clase>:<valor>: ${raw}`);
+    // Case-fold el valor igual que `key()` hace con paths: sin esto, `db:Dev`
+    // y `db:dev` producen strings distintos y el Set.has() de
+    // assessDeclaredIndependence no detecta la colision (fail-open).
+    return `${match[1].toLowerCase()}:${match[2].trim().toLocaleLowerCase('en-US')}`;
+}
+function assessDeclaredIndependence(tracks) {
+    const reasons = new Set();
+    for (const t of tracks) {
+        for (const owner of t.ownership) {
+            try {
+                ownershipPrefix(owner);
+            }
+            catch {
+                reasons.add(`unsupported-glob:${canon(owner)}`);
+            }
+            const global = GLOBAL.find((g) => g.re.test(canon(owner)));
+            if (global !== undefined)
+                reasons.add(`global:${global.kind}:${canon(owner)}`);
+        }
+    }
+    for (let i = 0; i < tracks.length; i++)
+        for (let j = i + 1; j < tracks.length; j++) {
+            for (const left of tracks[i].ownership)
+                for (const right of tracks[j].ownership) {
+                    if (intersects(left, right))
+                        reasons.add(`path:${canon(right)}`);
+                }
+            const rightResources = new Set(tracks[j].sharedResources.map(canonicalResource));
+            for (const resource of tracks[i].sharedResources.map(canonicalResource)) {
+                if (rightResources.has(resource))
+                    reasons.add(`resource:${resource}`);
+            }
+        }
+    return { parallel: reasons.size === 0, reasons: [...reasons].sort() };
+}
+function assessActualOwnership(track, changes) {
+    const actual = changes.flatMap((c) => c.oldPath === undefined ? [c.path] : [c.oldPath, c.path]);
+    return {
+        outsideOwnership: actual.filter((p) => !track.ownership.some((o) => proves(o, p))).sort(),
+        globalClasses: actual.flatMap((p) => GLOBAL.filter((g) => g.re.test(canon(p))).map((g) => `${g.kind}:${canon(p)}`)).sort(),
+    };
+}

package/dist/src/core/tracks/plan-parser.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTrackPlan = parseTrackPlan;
+const path_1 = __importDefault(require("path"));
+const taskHeading = /^### Task ([^:]+):/;
+const trackLine = /^\*\*Track:\*\*\s*(.*)$/;
+const fileLine = /^- (?:Create|Modify|Test|Delete):\s+`([^`]+)`/;
+const EXACT_MATCH_ERROR = 'membresía y filas de ## Tracks requieren coincidencia exacta';
+function jsonStrings(label, raw) {
+    if (raw === undefined)
+        throw new Error(`${label} es obligatorio para paralelismo`);
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${label} debe ser JSON string[]`);
+    }
+    if (!Array.isArray(value) || value.length === 0 || value.some((x) => typeof x !== 'string' || x.length === 0)) {
+        throw new Error(`${label} debe ser JSON string[] no vacío`);
+    }
+    return value;
+}
+function canonicalFile(raw) {
+    const withoutLines = raw.replace(/:\d+(?:-\d+)?$/, '');
+    const posix = withoutLines.replaceAll('\\', '/');
+    const normalized = path_1.default.posix.normalize(posix);
+    if (path_1.default.posix.isAbsolute(normalized) || normalized === '..' || normalized.startsWith('../')) {
+        throw new Error(`Files path fuera del repo: ${raw}`);
+    }
+    return normalized.replace(/^\.\//, '');
+}
+function parseTrackPlan(source, checkRef) {
+    const lines = source.replace(/\r\n/g, '\n').split('\n');
+    const hasMembership = lines.some((line) => trackLine.test(line));
+    const tracksHeading = lines.findIndex((line) => line.trim() === '## Tracks');
+    if (!hasMembership && tracksHeading < 0)
+        return { mode: 'serial', reason: 'no-tracks' };
+    if (!hasMembership || tracksHeading < 0)
+        throw new Error('Track membership y ## Tracks deben coexistir');
+    const argvRaw = lines.find((l) => l.startsWith('**Integration argv:**'))?.slice('**Integration argv:**'.length).trim();
+    const pathsRaw = lines.find((l) => l.startsWith('**Integration paths:**'))?.slice('**Integration paths:**'.length).trim();
+    const integration = { argv: jsonStrings('Integration argv', argvRaw), paths: jsonStrings('Integration paths', pathsRaw) };
+    const declared = new Map();
+    for (const line of lines.slice(tracksHeading + 1)) {
+        if (line.startsWith('## '))
+            break;
+        const cells = line.split('|').slice(1, -1).map((x) => x.trim());
+        if (cells.length !== 3 || cells[0] === 'Track' || /^[-:]+$/.test(cells[0]))
+            continue;
+        const [id, dependsRaw, resourcesRaw] = cells;
+        if (!id || id === '.' || id === '..' || id.startsWith('-') || id.includes('/') || id.includes('\\') || !checkRef(id)) {
+            throw new Error(`track id inválido: ${JSON.stringify(id)}`);
+        }
+        if (declared.has(id))
+            throw new Error(`track duplicado: ${id}`);
+        const resources = resourcesRaw === '[]' ? [] : resourcesRaw.length === 0 ? null : resourcesRaw.split(',').map((x) => x.trim());
+        const dependsOn = dependsRaw === 'none' ? [] : dependsRaw.split(',').map((x) => x.trim());
+        declared.set(id, { trackId: id, taskIds: [], ownership: [], dependsOn, sharedResources: resources ?? [] });
+        if (resources === null)
+            return { mode: 'serial', reason: `shared-resources-missing:${id}` };
+    }
+    let taskId = null;
+    let member = null;
+    let pendingFiles = [];
+    for (const line of lines) {
+        const heading = line.match(taskHeading);
+        if (heading !== null) {
+            if (taskId !== null && pendingFiles.length > 0 && member === null)
+                throw new Error(`task ${taskId} tiene Files pero no Track`);
+            taskId = heading[1].trim();
+            member = null;
+            pendingFiles = [];
+            continue;
+        }
+        const membership = line.match(trackLine);
+        if (membership !== null) {
+            if (taskId === null || member !== null)
+                throw new Error('cada task admite exactamente un Track');
+            member = membership[1].trim();
+            const track = declared.get(member);
+            if (track === undefined)
+                throw new Error(EXACT_MATCH_ERROR);
+            track.taskIds.push(taskId);
+            track.ownership.push(...pendingFiles);
+        }
+        const file = line.match(fileLine);
+        if (file !== null) {
+            const canonical = canonicalFile(file[1]);
+            if (member === null)
+                pendingFiles.push(canonical);
+            else
+                declared.get(member).ownership.push(canonical);
+        }
+    }
+    // La última task del documento no tiene un `### Task` siguiente que dispare el chequeo del loop.
+    if (taskId !== null && pendingFiles.length > 0 && member === null)
+        throw new Error(`task ${taskId} tiene Files pero no Track`);
+    const members = new Set([...declared.values()].flatMap((t) => t.taskIds.length > 0 ? [t.trackId] : []));
+    if (members.size !== declared.size)
+        throw new Error(EXACT_MATCH_ERROR);
+    if ([...declared.values()].some((t) => t.dependsOn.length > 0))
+        return { mode: 'serial', reason: 'track-dependency' };
+    return { mode: 'parallel-candidate', tracks: Object.fromEntries(declared), integration };
+}