@kognai/orchestrator-core 0.1.1 → 0.1.3

package/dist/lib/plumber/extractor.d.ts

@@ -0,0 +1,18 @@
+export interface ExtractProposal {
+    sourceFile: string;
+    startAnchor: string;
+    endAnchor: string;
+    targetModule: string;
+    targetHeader: string;
+    sourceReplacement: string;
+}
+export interface ExtractResult {
+    extracted: boolean;
+    reverted: boolean;
+    reason: string;
+    linesMoved: number;
+}
+export declare function extractToModule(p: ExtractProposal, opts: {
+    verify?: () => boolean | Promise<boolean>;
+    root?: string;
+}): Promise<ExtractResult>;

package/dist/lib/plumber/extractor.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToModule = extractToModule;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const patcher_js_1 = require("./patcher.js");
+function resolvePath(p, root) {
+    if ((0, node_path_1.isAbsolute)(p))
+        return p;
+    return (0, node_path_1.resolve)(root ?? process.cwd(), p);
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while (true) {
+        const found = haystack.indexOf(needle, idx);
+        if (found === -1)
+            break;
+        count++;
+        idx = found + needle.length;
+    }
+    return count;
+}
+function findLineStart(content, index) {
+    if (index <= 0)
+        return 0;
+    const prevNewline = content.lastIndexOf('\n', index - 1);
+    return prevNewline === -1 ? 0 : prevNewline + 1;
+}
+function findLineEnd(content, index) {
+    const nextNewline = content.indexOf('\n', index);
+    return nextNewline === -1 ? content.length : nextNewline;
+}
+function countLines(chunk) {
+    if (chunk.length === 0)
+        return 0;
+    let count = 1;
+    for (let i = 0; i < chunk.length; i++) {
+        if (chunk.charCodeAt(i) === 10)
+            count++;
+    }
+    // If chunk ends with newline, the trailing "line" isn't a real line
+    if (chunk.charCodeAt(chunk.length - 1) === 10)
+        count--;
+    return Math.max(count, 1);
+}
+async function extractToModule(p, opts) {
+    const sourcePath = resolvePath(p.sourceFile, opts.root);
+    const targetPath = resolvePath(p.targetModule, opts.root);
+    let originalSource;
+    try {
+        originalSource = await (0, promises_1.readFile)(sourcePath, 'utf8');
+    }
+    catch (err) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: `failed to read source file: ${err.message}`,
+            linesMoved: 0,
+        };
+    }
+    if (p.startAnchor.length === 0) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: 'startAnchor must be non-empty',
+            linesMoved: 0,
+        };
+    }
+    if (p.endAnchor.length === 0) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: 'endAnchor must be non-empty',
+            linesMoved: 0,
+        };
+    }
+    const startCount = countOccurrences(originalSource, p.startAnchor);
+    if (startCount !== 1) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: `startAnchor must occur exactly once (found ${startCount})`,
+            linesMoved: 0,
+        };
+    }
+    const endCount = countOccurrences(originalSource, p.endAnchor);
+    if (endCount !== 1) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: `endAnchor must occur exactly once (found ${endCount})`,
+            linesMoved: 0,
+        };
+    }
+    const startIdx = originalSource.indexOf(p.startAnchor);
+    const endIdx = originalSource.indexOf(p.endAnchor);
+    if (endIdx < startIdx) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: 'endAnchor occurs before startAnchor',
+            linesMoved: 0,
+        };
+    }
+    const chunkStart = findLineStart(originalSource, startIdx);
+    const chunkEnd = findLineEnd(originalSource, endIdx + p.endAnchor.length - 1);
+    if (chunkEnd < chunkStart) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: 'computed chunk range is invalid',
+            linesMoved: 0,
+        };
+    }
+    const chunk = originalSource.slice(chunkStart, chunkEnd);
+    const linesMoved = countLines(chunk);
+    const newModuleContent = p.targetHeader + '\n' + chunk;
+    // Build new source: replace the chunk with sourceReplacement.
+    // chunkEnd points to the position of the trailing newline (or EOF).
+    // We replace only the chunk content (not the trailing newline) so the
+    // existing line break structure is preserved.
+    const newSourceContent = originalSource.slice(0, chunkStart) +
+        p.sourceReplacement +
+        originalSource.slice(chunkEnd);
+    // At this point, validation has passed. Begin writes.
+    // Step 1: write the new module file.
+    let targetWritten = false;
+    try {
+        await (0, patcher_js_1.writeFileAtomic)(targetPath, newModuleContent);
+        targetWritten = true;
+    }
+    catch (err) {
+        return {
+            extracted: false,
+            reverted: false,
+            reason: `failed to write target module: ${err.message}`,
+            linesMoved: 0,
+        };
+    }
+    // Step 2: rewrite the source file.
+    let sourceWritten = false;
+    try {
+        await (0, patcher_js_1.writeFileAtomic)(sourcePath, newSourceContent);
+        sourceWritten = true;
+    }
+    catch (err) {
+        // Failed to write the source; revert the target module write.
+        if (targetWritten) {
+            try {
+                await (0, promises_1.unlink)(targetPath);
+            }
+            catch {
+                // best effort; ignore
+            }
+        }
+        return {
+            extracted: false,
+            reverted: false,
+            reason: `failed to write source file: ${err.message}`,
+            linesMoved: 0,
+        };
+    }
+    // Step 3: verify.
+    let verifyOk = true;
+    let verifyError = null;
+    if (opts.verify) {
+        try {
+            const result = await opts.verify();
+            verifyOk = result !== false;
+        }
+        catch (err) {
+            verifyOk = false;
+            verifyError = err.message;
+        }
+    }
+    if (!verifyOk) {
+        // RESTORE: delete the new module and rewrite the original source from backup.
+        let revertReason = verifyError
+            ? `verify threw: ${verifyError}`
+            : 'verify returned false';
+        if (sourceWritten) {
+            try {
+                await (0, patcher_js_1.writeFileAtomic)(sourcePath, originalSource);
+            }
+            catch (err) {
+                revertReason += `; failed to restore source: ${err.message}`;
+            }
+        }
+        if (targetWritten) {
+            try {
+                await (0, promises_1.unlink)(targetPath);
+            }
+            catch (err) {
+                revertReason += `; failed to delete target: ${err.message}`;
+            }
+        }
+        return {
+            extracted: false,
+            reverted: true,
+            reason: revertReason,
+            linesMoved: 0,
+        };
+    }
+    return {
+        extracted: true,
+        reverted: false,
+        reason: 'ok',
+        linesMoved,
+    };
+}

package/dist/lib/plumber/fixer.d.ts

@@ -0,0 +1,75 @@
+import { type Patch } from "./patcher";
+/**
+ * Classification of a proposed change, per TICKET-230.
+ *
+ *  - `'ops'`      — operations / workflow changes. Safe to auto-apply through
+ *                   the deterministic, verify-gated, reversible Plumber path.
+ *  - `'contract'` — architecture / security / compliance / supervision /
+ *                   scoring changes. These touch the system's contract with
+ *                   its operators and MUST NOT be auto-applied. The fixer
+ *                   returns an escalation result; the runner is responsible
+ *                   for routing to the Council-Brief flow.
+ */
+export type ChangeClass = "ops" | "contract";
+/**
+ * A single proposed fix targeting one file.
+ *
+ * `patches` are anchored string replacements consumed by `applyPatches` from
+ * `./patcher`. `changeClass` gates whether the fix is auto-applyable.
+ * `rationale` is operator-readable context (the runner logs it; the fixer
+ * itself does not).
+ */
+export interface FixProposal {
+    file: string;
+    patches: Patch[];
+    changeClass: ChangeClass;
+    rationale: string;
+}
+/**
+ * Terminal outcome of `applyFix`.
+ *
+ *  - `applied`   — patches were written to disk AND (if a verifier was
+ *                  supplied) verify returned true. If verify failed, the
+ *                  file was restored and `applied` is false.
+ *  - `escalated` — proposal was a `'contract'`-class change; nothing was
+ *                  read, written, or executed against the filesystem.
+ *  - `reverted`  — patches were written, verify returned false, and the
+ *                  original file content was restored via atomic write.
+ *  - `reason`    — machine- and human-readable explanation of the outcome.
+ */
+export interface FixResult {
+    applied: boolean;
+    escalated: boolean;
+    reverted: boolean;
+    reason: string;
+}
+/**
+ * Apply a single fix proposal under TICKET-216 (deterministic, verify-gated,
+ * reversible) governed by TICKET-230 (change-class escalation).
+ *
+ * Flow:
+ *  1. If `changeClass === 'contract'` → escalate immediately. No I/O.
+ *  2. Otherwise (`'ops'`):
+ *     a. Read the target file's current bytes (kept in memory as the
+ *        rollback snapshot).
+ *     b. Run `applyPatches` against the snapshot. If it fails (anchor
+ *        missing / ambiguous / etc.), return `applied: false` with the
+ *        patcher's failure reasons; the file is NEVER written.
+ *     c. Atomically write the patched content.
+ *     d. If a `verify` callback was supplied, await it.
+ *          - If it returns truthy → success (`applied: true`).
+ *          - If it returns falsy → atomically restore the snapshot and
+ *            return `reverted: true, applied: false`.
+ *          - If it throws → restore the snapshot, propagate as
+ *            `reverted: true, applied: false` with the error message.
+ *     e. If no `verify` was supplied, the write itself is the success
+ *        condition.
+ *
+ * Notes:
+ *  - KSL/audit logging is the runner's responsibility, not this layer's.
+ *  - This function performs no network or process I/O of its own.
+ */
+export declare function applyFix(proposal: FixProposal, opts: {
+    verify?: () => boolean | Promise<boolean>;
+    root?: string;
+}): Promise<FixResult>;

package/dist/lib/plumber/fixer.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFix = applyFix;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const patcher_1 = require("./patcher");
+/**
+ * Resolve a proposal's file path against an optional `root`.
+ *
+ *  - Absolute paths are honored as-is (no silent rewriting under `root`).
+ *  - Relative paths are resolved against `root` if provided, else cwd.
+ *
+ * This keeps the fixer usable both in production (where the runner supplies
+ * a sandbox root) and in unit tests (where cwd is fine).
+ */
+function resolveTarget(file, root) {
+    if ((0, node_path_1.isAbsolute)(file))
+        return file;
+    if (root && root.length > 0)
+        return (0, node_path_1.resolve)(root, file);
+    return (0, node_path_1.resolve)(file);
+}
+/**
+ * Apply a single fix proposal under TICKET-216 (deterministic, verify-gated,
+ * reversible) governed by TICKET-230 (change-class escalation).
+ *
+ * Flow:
+ *  1. If `changeClass === 'contract'` → escalate immediately. No I/O.
+ *  2. Otherwise (`'ops'`):
+ *     a. Read the target file's current bytes (kept in memory as the
+ *        rollback snapshot).
+ *     b. Run `applyPatches` against the snapshot. If it fails (anchor
+ *        missing / ambiguous / etc.), return `applied: false` with the
+ *        patcher's failure reasons; the file is NEVER written.
+ *     c. Atomically write the patched content.
+ *     d. If a `verify` callback was supplied, await it.
+ *          - If it returns truthy → success (`applied: true`).
+ *          - If it returns falsy → atomically restore the snapshot and
+ *            return `reverted: true, applied: false`.
+ *          - If it throws → restore the snapshot, propagate as
+ *            `reverted: true, applied: false` with the error message.
+ *     e. If no `verify` was supplied, the write itself is the success
+ *        condition.
+ *
+ * Notes:
+ *  - KSL/audit logging is the runner's responsibility, not this layer's.
+ *  - This function performs no network or process I/O of its own.
+ */
+async function applyFix(proposal, opts) {
+    // -- TICKET-230 gate: never auto-apply contract-class changes. ----------
+    if (proposal.changeClass === "contract") {
+        return {
+            applied: false,
+            escalated: true,
+            reverted: false,
+            reason: "contract-class change requires Council-Brief escalation (TICKET-230)",
+        };
+    }
+    // From here on, the proposal is `'ops'`-class and eligible for
+    // deterministic, reversible application.
+    const targetPath = resolveTarget(proposal.file, opts.root);
+    // -- Snapshot the original bytes for rollback. -------------------------
+    // Failure to read is a hard stop: we cannot guarantee reversibility
+    // without a known-good baseline, so we refuse to touch anything.
+    let original;
+    try {
+        original = (0, node_fs_1.readFileSync)(targetPath, "utf8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            applied: false,
+            escalated: false,
+            reverted: false,
+            reason: `failed to read target file (${targetPath}): ${msg}`,
+        };
+    }
+    // -- Apply patches in memory (pure, no I/O). ---------------------------
+    const patchResult = (0, patcher_1.applyPatches)(original, proposal.patches);
+    if (!patchResult.ok || typeof patchResult.content !== "string") {
+        return {
+            applied: false,
+            escalated: false,
+            reverted: false,
+            reason: `patch application failed: ${patchResult.failures.join("; ")}`,
+        };
+    }
+    // No-op fixes (zero patches, or patches that produced identical content)
+    // are still treated as a successful application: the proposal's intent
+    // — "make the file look like X" — is satisfied.
+    const patched = patchResult.content;
+    // -- Write the patched content atomically. -----------------------------
+    try {
+        (0, patcher_1.writeFileAtomic)(targetPath, patched);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // The write failed before any bytes could replace the original on disk
+        // (writeFileAtomic does temp+rename), so there is nothing to revert.
+        return {
+            applied: false,
+            escalated: false,
+            reverted: false,
+            reason: `atomic write failed (${targetPath}): ${msg}`,
+        };
+    }
+    // -- Verify-gate. If no verifier, the write is the success condition. --
+    if (typeof opts.verify === "function") {
+        let verified;
+        try {
+            const result = await opts.verify();
+            verified = result === true;
+        }
+        catch (err) {
+            // Treat verifier exceptions as a failed verification: revert and
+            // surface the error message so the runner can log it.
+            const msg = err instanceof Error ? err.message : String(err);
+            try {
+                (0, patcher_1.writeFileAtomic)(targetPath, original);
+            }
+            catch (restoreErr) {
+                const rmsg = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+                return {
+                    applied: false,
+                    escalated: false,
+                    reverted: false,
+                    reason: `verify threw (${msg}); rollback ALSO failed (${rmsg}) — manual intervention required`,
+                };
+            }
+            return {
+                applied: false,
+                escalated: false,
+                reverted: true,
+                reason: `verify threw, reverted: ${msg}`,
+            };
+        }
+        if (!verified) {
+            // Verification rejected the patched state. Restore the snapshot.
+            try {
+                (0, patcher_1.writeFileAtomic)(targetPath, original);
+            }
+            catch (restoreErr) {
+                const rmsg = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+                return {
+                    applied: false,
+                    escalated: false,
+                    reverted: false,
+                    reason: `verify returned false; rollback ALSO failed (${rmsg}) — manual intervention required`,
+                };
+            }
+            return {
+                applied: false,
+                escalated: false,
+                reverted: true,
+                reason: "verify returned false; original content restored",
+            };
+        }
+    }
+    return {
+        applied: true,
+        escalated: false,
+        reverted: false,
+        reason: `applied ${patchResult.applied} patch(es) to ${targetPath}`,
+    };
+}

package/dist/lib/plumber/index.d.ts

@@ -7,3 +7,6 @@
 export * from './types';
 export * from './conformance';
 export * from './observer';
+export * from './patcher';
+export * from './fixer';
+export * from './extractor';

package/dist/lib/plumber/index.js

@@ -23,3 +23,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./conformance"), exports);
 __exportStar(require("./observer"), exports);
+__exportStar(require("./patcher"), exports);
+__exportStar(require("./fixer"), exports);
+__exportStar(require("./extractor"), exports);

package/dist/lib/plumber/patcher.d.ts

@@ -0,0 +1,44 @@
+export type Patch = {
+    old: string;
+    new: string;
+};
+export type PatchResult = {
+    ok: boolean;
+    content?: string;
+    applied: number;
+    failures: string[];
+};
+/**
+ * Apply a list of anchored string-replacement patches to `source`.
+ *
+ * Contract:
+ *  - Pure: does NOT touch the filesystem or any other I/O.
+ *  - For each patch, `old` MUST occur EXACTLY ONCE in `source`. If it occurs
+ *    zero times or more than once, that patch is recorded as a failure.
+ *  - All-or-nothing: if ANY patch fails, the function aborts and applies
+ *    NOTHING. `ok` is false, `content` is undefined, `applied` is 0, and
+ *    `failures` contains one entry per failing patch.
+ *  - On full success, every patch's `old` is replaced by its `new` in the
+ *    order given, and the final `content` is returned with `ok: true`.
+ *
+ * Validation is performed against the ORIGINAL source (pre-mutation) so that
+ * patch ordering cannot accidentally mask a duplicate anchor. We re-validate
+ * uniqueness against the in-progress buffer during application only as a
+ * defensive check; if that ever trips, the entire operation is aborted.
+ */
+export declare function applyPatches(source: string, patches: Patch[]): PatchResult;
+/**
+ * Atomically write `content` to `path`.
+ *
+ * Strategy:
+ *  1. Ensure the parent directory exists (mkdir -p).
+ *  2. Write to a sibling temp file (same directory, so rename is atomic
+ *     on POSIX filesystems — cross-device renames are not atomic).
+ *  3. Rename temp file over the target path.
+ *  4. On any failure after the temp write, attempt to clean up the temp
+ *     file; surface the original error to the caller.
+ *
+ * This guarantees readers never observe a partially-written file: they
+ * either see the old bytes or the new bytes, never a torn mix.
+ */
+export declare function writeFileAtomic(path: string, content: string): void;