@kognai/orchestrator-core 0.1.1 → 0.1.3

package/dist/lib/plumber/patcher.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyPatches = applyPatches;
+exports.writeFileAtomic = writeFileAtomic;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Count non-overlapping occurrences of `needle` in `haystack`.
+ * Uses indexOf to avoid regex pitfalls (no special-char escaping needed).
+ */
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let from = 0;
+    // Non-overlapping scan: advance past the full match each hit.
+    while (from <= haystack.length) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx === -1)
+            break;
+        count += 1;
+        from = idx + needle.length;
+    }
+    return count;
+}
+/**
+ * Replace the first (and, by precondition, only) occurrence of `needle`
+ * with `replacement` in `haystack`. Returns the resulting string.
+ * If the needle is not found, returns the original string unchanged.
+ */
+function replaceOnce(haystack, needle, replacement) {
+    const idx = haystack.indexOf(needle);
+    if (idx === -1)
+        return haystack;
+    return (haystack.slice(0, idx) + replacement + haystack.slice(idx + needle.length));
+}
+/**
+ * Truncate a string for inclusion in human-readable failure messages.
+ * Keeps logs scannable when anchors are large.
+ */
+function previewAnchor(text, max = 80) {
+    const collapsed = text.replace(/\r?\n/g, "\\n");
+    if (collapsed.length <= max)
+        return collapsed;
+    return collapsed.slice(0, max) + "…";
+}
+/**
+ * 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.
+ */
+function applyPatches(source, patches) {
+    if (typeof source !== "string") {
+        return {
+            ok: false,
+            applied: 0,
+            failures: ["source must be a string"],
+        };
+    }
+    if (!Array.isArray(patches)) {
+        return {
+            ok: false,
+            applied: 0,
+            failures: ["patches must be an array"],
+        };
+    }
+    // Empty patch list is a no-op success: nothing to do, source unchanged.
+    if (patches.length === 0) {
+        return {
+            ok: true,
+            content: source,
+            applied: 0,
+            failures: [],
+        };
+    }
+    const failures = [];
+    // ---- Phase 1: validate every patch against the ORIGINAL source. ----
+    // We do not mutate anything yet. This guarantees all-or-nothing semantics
+    // and avoids the trap where applying patch[0] could change the occurrence
+    // count of patch[1]'s anchor mid-flight.
+    for (let i = 0; i < patches.length; i += 1) {
+        const patch = patches[i];
+        if (!patch || typeof patch !== "object") {
+            failures.push(`patch[${i}]: must be an object with { old, new }`);
+            continue;
+        }
+        if (typeof patch.old !== "string") {
+            failures.push(`patch[${i}]: \`old\` must be a string`);
+            continue;
+        }
+        if (typeof patch.new !== "string") {
+            failures.push(`patch[${i}]: \`new\` must be a string`);
+            continue;
+        }
+        if (patch.old.length === 0) {
+            failures.push(`patch[${i}]: \`old\` must be non-empty`);
+            continue;
+        }
+        const occurrences = countOccurrences(source, patch.old);
+        if (occurrences === 0) {
+            failures.push(`patch[${i}]: anchor not found (\`${previewAnchor(patch.old)}\`)`);
+        }
+        else if (occurrences > 1) {
+            failures.push(`patch[${i}]: anchor matches ${occurrences} times, must be exactly 1 (\`${previewAnchor(patch.old)}\`)`);
+        }
+    }
+    if (failures.length > 0) {
+        // All-or-nothing: abort with NO mutation.
+        return {
+            ok: false,
+            applied: 0,
+            failures,
+        };
+    }
+    // ---- Phase 2: apply patches in order against a working buffer. ----
+    // Defensive: each step re-checks that its anchor is still uniquely present
+    // in the in-progress buffer. If a previous patch's `new` text happens to
+    // collide with a later patch's `old`, we refuse rather than guessing.
+    let working = source;
+    let applied = 0;
+    for (let i = 0; i < patches.length; i += 1) {
+        const patch = patches[i]; // validated above
+        const occurrences = countOccurrences(working, patch.old);
+        if (occurrences !== 1) {
+            // Anchor collision introduced by an earlier replacement. Abort entirely.
+            return {
+                ok: false,
+                applied: 0,
+                failures: [
+                    `patch[${i}]: anchor became ambiguous after earlier patches (now matches ${occurrences} times)`,
+                ],
+            };
+        }
+        working = replaceOnce(working, patch.old, patch.new);
+        applied += 1;
+    }
+    return {
+        ok: true,
+        content: working,
+        applied,
+        failures: [],
+    };
+}
+/**
+ * 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.
+ */
+function writeFileAtomic(path, content) {
+    if (typeof path !== "string" || path.length === 0) {
+        throw new TypeError("writeFileAtomic: path must be a non-empty string");
+    }
+    if (typeof content !== "string") {
+        throw new TypeError("writeFileAtomic: content must be a string");
+    }
+    const absolute = (0, node_path_1.resolve)(path);
+    const dir = (0, node_path_1.dirname)(absolute);
+    const base = (0, node_path_1.basename)(absolute);
+    // mkdir -p the parent directory if missing.
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    // Unique temp filename in the SAME directory so rename(2) is atomic.
+    const suffix = (0, node_crypto_1.randomBytes)(8).toString("hex");
+    const tempPath = `${dir}/.${base}.${process.pid}.${suffix}.tmp`;
+    try {
+        // fsync-equivalent durability is not guaranteed without an explicit
+        // flush, but rename atomicity protects readers from torn writes which
+        // is the contract Plumber relies on.
+        (0, node_fs_1.writeFileSync)(tempPath, content, { encoding: "utf8", mode: 0o644 });
+        (0, node_fs_1.renameSync)(tempPath, absolute);
+    }
+    catch (err) {
+        // Best-effort cleanup; swallow cleanup errors so we surface the real one.
+        try {
+            // Lazy import to avoid pulling unlinkSync into the hot path above.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { unlinkSync, existsSync: exists } = require("node:fs");
+            if (exists(tempPath))
+                unlinkSync(tempPath);
+        }
+        catch {
+            // intentionally ignored
+        }
+        throw err;
+    }
+}

package/dist/lib/preamble-provider-registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Constitutional-preamble provider seam — TICKET-226 Phase A1.
+ *
+ * The "you are a Kognai citizen" constitutional preamble is Kognai polity, not
+ * engine-generic. This seam lets a consuming template supply its own preamble (or
+ * none). OPTIONAL override: if no provider is set the engine keeps its existing
+ * inline behavior — NON-BREAKING. Phase A2 wires Kognai's provider; Phase A3
+ * removes the engine's inline default so core ships no Kognai-specific preamble.
+ */
+export type PreambleProvider = () => string;
+export declare function setPreambleProvider(fn: PreambleProvider): void;
+export declare function getPreambleProvider(): PreambleProvider | null;

package/dist/lib/preamble-provider-registry.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPreambleProvider = setPreambleProvider;
+exports.getPreambleProvider = getPreambleProvider;
+let _provider = null;
+function setPreambleProvider(fn) { _provider = fn; }
+function getPreambleProvider() { return _provider; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kognai/orchestrator-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Kognai sovereign orchestrator — core engine (template-agnostic). Shared by all products (Kognai/coding, Voxight/market-intel, Invoica/fin-compliance); each supplies only its template. Replaces per-repo forks of orchestrate-agents-v2 / sprint-runner / lib.",
   "license": "MIT",
   "author": "SkinGem",