@vincemakes/kiso-tools-node 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -109,11 +109,17 @@ export declare function searchTextTool(opts: WorkspaceToolsOptions): Tool<{
 export declare function writeFileTool(opts: WorkspaceToolsOptions): Tool<{
     path: string;
     content: string;
+    expectedRevision?: string;
 }>;
 export declare function editFileTool(opts: WorkspaceToolsOptions): Tool<{
     path: string;
-    search: string;
-    replace: string;
+    search?: string;
+    replace?: string;
+    edits?: readonly {
+        search: string;
+        replace: string;
+    }[];
+    expectedRevision?: string;
 }>;
 export declare function shellTool(opts: WorkspaceToolsOptions): Tool<{
     command: string;

package/dist/wr1.d.ts

@@ -0,0 +1,59 @@
+/**
+ * WR-1 — the observed-revision stale-write guard's primitives, extracted
+ * so the classification rules are unit-testable (WR-1A).
+ *
+ * The revision is a CONTENT-STATE WITNESS, never an epistemic proof: it
+ * answers "has this file changed since the citation was issued", not
+ * "did the model read this exact file" (no path binding — two files
+ * with identical bytes share a token, harmlessly: the current bytes ARE
+ * the cited state). The guard is against accidents, not adversaries.
+ */
+import type { ToolResult } from "@vincemakes/kiso-core";
+/** sha256 over RAW bytes (never the decoded string — UTF-8 replacement
+ *  semantics would lie about the world), truncated to a 64-bit citation
+ *  token. Truncation loses nothing the full digest would keep here: a
+ *  non-cooperating writer wins the conditional-write window without
+ *  ever touching the hash. */
+export declare function contentRevision(bytes: Buffer): string;
+/** The stale-write refusal: work refused BEFORE it starts — exactly what
+ *  the `precondition` kind exists to say (and the reason the kernel's
+ *  partial-effects note never rides one). */
+export declare function precondition(content: string): ToolResult;
+/**
+ * WR-1-F2 — citation normalization (found by the rel-0140 blocking
+ * bench): the old trailer `[rev: rev:X]` double-labeled the token, and
+ * DeepSeek-class models flailed between citing `rev:rev:X` and bare
+ * `X` — every first edit refused, 2–7 wasted rounds per file. The
+ * trailer is now `[rev:X]`, and EVERY plausible copy of the token
+ * normalizes to the same citation: tolerance in the reader,
+ * strictness in the comparison — never a bypass (a wrong token stays
+ * wrong in every form).
+ */
+export declare function normalizeRevision(cited: string): string;
+/**
+ * WR-1A ①: a POST-EFFECT verification failure is FATAL — the rename
+ * already happened, so `precondition` ("nothing ran") would make the
+ * durable receipt lie about the world. The copy says the effect may
+ * already have applied, and the kernel's non-idempotent note rides it.
+ */
+export declare function postEffectEscape(action: "write" | "edit", path: string): ToolResult;
+/**
+ * WR-1A ②: the CREATION publish — link(2) or refusal, never a fallback.
+ * link is atomic no-clobber: target absent → the entry appears; target
+ * present → EEXIST, the loser is told LOUDLY. Any other failure refuses
+ * too (fail closed): a platform that cannot give the atomic primitive
+ * does not get to degrade "absent" into a clobber-capable rename — a
+ * semantic guarantee that is unavailable is an honest refusal, never a
+ * silent downgrade. Returns null on success; the temp is consumed
+ * (linked then unlinked) or cleaned on every failure path.
+ */
+export declare function publishNewFile(tmp: string, full: string, path: string): ToolResult | null;
+/**
+ * WR-1A ③: the immediate pre-rename revalidation — after staging, right
+ * before the replacement commits, the target must STILL hash to the
+ * cited revision. This shrinks the conditional-write window from
+ * validate→stage→chmod→rename to check→rename (POSIX offers no
+ * rename-if-content-equals, so the residual window is the narrowed
+ * claim, stated as such). Returns null when the world still matches.
+ */
+export declare function revalidateBeforeRename(full: string, expectedRevision: string, tool: "write_file" | "edit_file", path: string): ToolResult | null;

package/dist/wr1.js

@@ -0,0 +1,109 @@
+/**
+ * WR-1 — the observed-revision stale-write guard's primitives, extracted
+ * so the classification rules are unit-testable (WR-1A).
+ *
+ * The revision is a CONTENT-STATE WITNESS, never an epistemic proof: it
+ * answers "has this file changed since the citation was issued", not
+ * "did the model read this exact file" (no path binding — two files
+ * with identical bytes share a token, harmlessly: the current bytes ARE
+ * the cited state). The guard is against accidents, not adversaries.
+ */
+import { createHash } from "node:crypto";
+import { linkSync, readFileSync, unlinkSync } from "node:fs";
+/** sha256 over RAW bytes (never the decoded string — UTF-8 replacement
+ *  semantics would lie about the world), truncated to a 64-bit citation
+ *  token. Truncation loses nothing the full digest would keep here: a
+ *  non-cooperating writer wins the conditional-write window without
+ *  ever touching the hash. */
+export function contentRevision(bytes) {
+    return `rev:${createHash("sha256").update(bytes).digest("hex").slice(0, 16)}`;
+}
+/** The stale-write refusal: work refused BEFORE it starts — exactly what
+ *  the `precondition` kind exists to say (and the reason the kernel's
+ *  partial-effects note never rides one). */
+export function precondition(content) {
+    return { content, isError: true, errorKind: "precondition" };
+}
+/**
+ * WR-1-F2 — citation normalization (found by the rel-0140 blocking
+ * bench): the old trailer `[rev: rev:X]` double-labeled the token, and
+ * DeepSeek-class models flailed between citing `rev:rev:X` and bare
+ * `X` — every first edit refused, 2–7 wasted rounds per file. The
+ * trailer is now `[rev:X]`, and EVERY plausible copy of the token
+ * normalizes to the same citation: tolerance in the reader,
+ * strictness in the comparison — never a bypass (a wrong token stays
+ * wrong in every form).
+ */
+export function normalizeRevision(cited) {
+    const t = cited.trim();
+    if (t === "absent")
+        return t;
+    if (/^rev:rev:[0-9a-f]{16}$/.test(t))
+        return t.slice(4);
+    if (/^[0-9a-f]{16}$/.test(t))
+        return `rev:${t}`;
+    return t;
+}
+/**
+ * WR-1A ①: a POST-EFFECT verification failure is FATAL — the rename
+ * already happened, so `precondition` ("nothing ran") would make the
+ * durable receipt lie about the world. The copy says the effect may
+ * already have applied, and the kernel's non-idempotent note rides it.
+ */
+export function postEffectEscape(action, path) {
+    return {
+        content: `${action}_file failed: ${path} escaped the workspace after replacement — the ${action} may already have applied`,
+        isError: true,
+        errorKind: "fatal",
+    };
+}
+/**
+ * WR-1A ②: the CREATION publish — link(2) or refusal, never a fallback.
+ * link is atomic no-clobber: target absent → the entry appears; target
+ * present → EEXIST, the loser is told LOUDLY. Any other failure refuses
+ * too (fail closed): a platform that cannot give the atomic primitive
+ * does not get to degrade "absent" into a clobber-capable rename — a
+ * semantic guarantee that is unavailable is an honest refusal, never a
+ * silent downgrade. Returns null on success; the temp is consumed
+ * (linked then unlinked) or cleaned on every failure path.
+ */
+export function publishNewFile(tmp, full, path) {
+    try {
+        linkSync(tmp, full);
+        unlinkSync(tmp);
+        return null;
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // already gone
+        }
+        if (err.code === "EEXIST") {
+            return precondition(`write_file: ${path} already exists — read it and pass its revision to replace it`);
+        }
+        return precondition(`write_file: cannot publish ${path} atomically on this filesystem (${err.code ?? "link failed"}) — the no-clobber creation guarantee cannot be honored here`);
+    }
+}
+/**
+ * WR-1A ③: the immediate pre-rename revalidation — after staging, right
+ * before the replacement commits, the target must STILL hash to the
+ * cited revision. This shrinks the conditional-write window from
+ * validate→stage→chmod→rename to check→rename (POSIX offers no
+ * rename-if-content-equals, so the residual window is the narrowed
+ * claim, stated as such). Returns null when the world still matches.
+ */
+export function revalidateBeforeRename(full, expectedRevision, tool, path) {
+    let current;
+    try {
+        current = contentRevision(readFileSync(full));
+    }
+    catch {
+        return precondition(`${tool}: ${path} no longer exists — it changed after validation; read it again`);
+    }
+    if (current !== expectedRevision) {
+        return precondition(`${tool}: ${path} changed since ${expectedRevision} — read it again and cite its [rev:…] line, then re-apply the change`);
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-tools-node",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "kiso coding tools for Node hosts — read file, list directory, search text, write/edit file, shell command.",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.13.0"
+    "@vincemakes/kiso-core": "0.14.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",