feat: path regions, recovery, and agent instruction channels (v0.2.0)

Adds the path-region model that lets Pathrule own a bounded section of an
existing agent instruction file and restore it if it is edited or removed
by hand, so opening a brownfield project no longer rewrites files the
project already had.

Also declares the better-sqlite3 major the engine is actually built and
tested against, and takes plain `vitest run` for the contract suite.

Signed-off-by: Sertan Helvacı <sertanhelvaci@icloud.com>

Author: sertanhelvaci

packages/cli-local/src/hook-script-install.ts

@@ -94,7 +94,7 @@ export async function installCliHookScript(
   env: NodeJS.ProcessEnv = process.env,
   opts: HookScriptInstallOptions = {},
 ): Promise<HookScriptInstallResult> {
-  const { binDir, scriptPath, shimPath, hookCommandPath, embedHelperPath } =
+  const { scriptPath, shimPath, hookCommandPath, embedHelperPath } =
     resolveCliHookScriptPaths(env);
   const platform = cliPlatform(env);
   const source = opts.scriptSource ?? EMBEDDED_HOOK_SCRIPT;

packages/core/package.json

@@ -10,7 +10,8 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./backend/knowledge-compiler.js": "./src/backend/knowledge-compiler.ts"
+    "./backend/knowledge-compiler.js": "./src/backend/knowledge-compiler.ts",
+    "./paths/*.js": "./src/paths/*.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -24,7 +25,7 @@
   },
   "dependencies": {
     "@pathrule/shared": "workspace:*",
-    "better-sqlite3": "^11"
+    "better-sqlite3": "^12"
   },
   "repository": {
     "type": "git",

packages/core/src/backend/contract-suite.ts

@@ -86,6 +86,19 @@ export function runKnowledgeBackendContract(
         expect((await b.deleteMemory({ id: "nope" })).status).toBe("rejected");
       });
 
+      it("updateMemory refuses a stale optimistic version", async () => {
+        const b = makeBackend();
+        const m = await b.writeMemory({ workspaceId: WS, title: "t", content: "c" });
+        await expect(
+          b.updateMemory({
+            id: m.id,
+            content: "must not overwrite",
+            expectedVersionId: "stale-version",
+          }),
+        ).rejects.toThrow("content_version_conflict");
+        expect((await b.readMemory(m.id))?.content).toBe("c");
+      });
+
       it("scopes lists by workspace", async () => {
         const b = makeBackend();
         await b.writeMemory({ workspaceId: WS, title: "a", content: "x" });
@@ -175,6 +188,38 @@ export function runKnowledgeBackendContract(
         const cleared = await b.updateSkill({ id: s.id, description: null });
         expect(cleared.description).toBeNull();
       });
+
+      it("rule and skill updates refuse stale optimistic versions", async () => {
+        const b = makeBackend();
+        const rule = await b.writeRule({
+          workspaceId: WS,
+          name: "rule",
+          content: "original",
+          scopeType: "project",
+        });
+        await expect(
+          b.updateRule({
+            id: rule.id,
+            content: "must not overwrite",
+            expectedVersionId: "stale-version",
+          }),
+        ).rejects.toThrow("content_version_conflict");
+        expect((await b.readRule(rule.id))?.content).toBe("original");
+
+        const skill = await b.writeSkill({
+          workspaceId: WS,
+          name: "skill",
+          content: "original",
+        });
+        await expect(
+          b.updateSkill({
+            id: skill.id,
+            content: "must not overwrite",
+            expectedVersionId: "stale-version",
+          }),
+        ).rejects.toThrow("content_version_conflict");
+        expect((await b.readSkill(skill.id))?.content).toBe("original");
+      });
     });
 
     describe("tree", () => {

packages/core/src/backend/delta-delivery.test.ts

@@ -86,7 +86,6 @@ describe("delta delivery (engine-level efficiency)", () => {
 
   it("re-injects only the edited item on a later turn", () => {
     const inp = input();
-    const warehouse = assembleWarehouse(inp);
     let ledger = applyDelta([], computeDelta(selectedFrom(inp), []).emit);
 
     // edit m2's body → new warehouse + new hash

packages/core/src/backend/in-memory-backend.ts

@@ -354,6 +354,9 @@ export class InMemoryKnowledgeBackend implements KnowledgeBackend {
   async updateMemory(input: UpdateMemoryInput): Promise<Memory> {
     const existing = this.memories.get(input.id);
     if (!existing) throw new Error(`memory ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
     const next: Memory = {
       ...existing,
@@ -450,9 +453,12 @@ export class InMemoryKnowledgeBackend implements KnowledgeBackend {
     return Promise.resolve(rule);
   }
 
-  updateRule(input: UpdateRuleInput): Promise<Rule> {
+  async updateRule(input: UpdateRuleInput): Promise<Rule> {
     const existing = this.rules.get(input.id);
     if (!existing) throw new Error(`rule ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
     const next: Rule = {
       ...existing,
@@ -468,7 +474,7 @@ export class InMemoryKnowledgeBackend implements KnowledgeBackend {
     };
     this.rules.set(next.id, next);
     if (input.nodeId) this.ruleNodes.set(next.id, input.nodeId);
-    return Promise.resolve(next);
+    return next;
   }
 
   deleteRule(input: DeleteContentInput): Promise<DeleteContentResult> {
@@ -550,9 +556,12 @@ export class InMemoryKnowledgeBackend implements KnowledgeBackend {
     return Promise.resolve(skill);
   }
 
-  updateSkill(input: UpdateSkillInput): Promise<Skill> {
+  async updateSkill(input: UpdateSkillInput): Promise<Skill> {
     const existing = this.skills.get(input.id);
     if (!existing) throw new Error(`skill ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
     const effectiveSource = input.source ?? existing.source;
     const next: Skill = {
@@ -575,7 +584,7 @@ export class InMemoryKnowledgeBackend implements KnowledgeBackend {
     };
     this.skills.set(next.id, next);
     if (input.nodeId) this.skillNodes.set(next.id, input.nodeId);
-    return Promise.resolve(next);
+    return next;
   }
 
   deleteSkill(input: DeleteContentInput): Promise<DeleteContentResult> {

packages/core/src/backend/inputs.ts

@@ -46,6 +46,8 @@ export interface WriteMemoryInput {
 }
 export interface UpdateMemoryInput {
   id: string;
+  /** Optional optimistic guard. A mismatched current version must not be overwritten. */
+  expectedVersionId?: string;
   title?: string;
   content?: string;
   /** Re-home the memory to a different node (the move_to_path target, already resolved). */
@@ -90,6 +92,8 @@ export interface WriteRuleInput {
 }
 export interface UpdateRuleInput {
   id: string;
+  /** Optional optimistic guard. A mismatched current version must not be overwritten. */
+  expectedVersionId?: string;
   name?: string;
   content?: string;
   scopeType?: "folder" | "file_type" | "project";
@@ -116,6 +120,8 @@ export interface WriteSkillInput {
 }
 export interface UpdateSkillInput {
   id: string;
+  /** Optional optimistic guard. A mismatched current version must not be overwritten. */
+  expectedVersionId?: string;
   name?: string;
   content?: string;
   /** null clears the description; undefined keeps it. */
@@ -149,6 +155,23 @@ export interface ActivityFriction {
   toolFailureCount?: number;
   toolFailureCodes?: string[];
 }
+export interface ActivityTeamIntelligenceSignal {
+  score: number;
+  category:
+    | "architecture"
+    | "coding_style"
+    | "debugging"
+    | "design"
+    | "testing"
+    | "review"
+    | "planning"
+    | "release"
+    | "security"
+    | "collaboration"
+    | "ai_usage"
+    | "other";
+  surface: "chat" | "tasks" | "design";
+}
 export interface LogActivityInput {
   workspaceId: string;
   nodePath?: string;
@@ -169,6 +192,22 @@ export interface LogActivityInput {
    * (the affinity model is a hosted-only curation surface).
    */
   appliedMemoryIds?: string[];
+  /**
+   * Exploration-suppression signal (observational). Read-only discovery
+   * calls (Grep/Glob/Read/...), file-writing calls, and the derived sufficiency
+   * verdict for this turn. The hosted edition persists them on the activity row;
+   * LocalBackend ignores (the measurement surface is hosted-only). Omit for a turn
+   * with no tool stream (then the row stays `unknown` / NULL).
+   */
+  exploreCalls?: number;
+  editCalls?: number;
+  contextSufficiency?: "sufficient" | "explored" | "unknown";
+  /**
+   * Studio Team Intelligence signal derived from an explicit prompt preference.
+   * Hosted-only, compact, and absent for ordinary activities. The raw prompt is
+   * never carried here.
+   */
+  teamIntelligenceSignal?: ActivityTeamIntelligenceSignal;
 }
 /** The persisted activity row, returned by `logActivity` so callers can echo id/created_at. */
 export interface ActivityRecord {
@@ -189,6 +228,13 @@ export interface ActivityRecord {
   toolCallCount?: number;
   toolFailureCount?: number;
   toolFailureCodes?: string[];
+  /** Exploration-suppression signal (hosted-only; undefined on LocalBackend / legacy rows). */
+  exploreCalls?: number;
+  editCalls?: number;
+  contextSufficiency?: "sufficient" | "explored" | "unknown";
+  teamIntelligenceScore?: number;
+  teamIntelligenceCategory?: ActivityTeamIntelligenceSignal["category"];
+  teamIntelligenceSurface?: ActivityTeamIntelligenceSignal["surface"];
 }
 /** Lean activity projection for `recentActivities` / context assembly. */
 export interface Activity {

packages/core/src/backend/knowledge-backend.ts

@@ -32,7 +32,6 @@ import type {
 import type { TreeNode } from "@pathrule/shared/node-types.js";
 import type {
   RoutingResult,
-  SubtreeMemoryIndexEntry,
   SubtreeMemoryIndexResult,
 } from "@pathrule/shared/routing-types.js";
 import type { DedupCheckArgs, DedupCheckResult } from "@pathrule/shared/tools/dedup-types.js";

packages/core/src/backend/knowledge-compiler.ts

@@ -15,6 +15,7 @@
  * Pure and deterministic: same input, same bytes. No I/O, no clock.
  */
 import type { HookIndexInput } from "./hook-index.js";
+import { isDirectoryLeafName } from "../paths/leaf-type.js";
 
 /** Per-directory budget for compiled knowledge (chars ≈ tokens × 4). */
 const DIR_BUDGET_CHARS = 12_000;
@@ -69,7 +70,7 @@ const PRIORITY_RANK: Record<string, number> = { high: 0, medium: 1, low: 2 };
 function toDirPath(nodePath: string): { dir: string; leaf?: string } {
   const clean = nodePath === "" ? "/" : nodePath;
   const last = clean.split("/").filter(Boolean).pop() ?? "";
-  const looksLikeFile = /\.[A-Za-z0-9]{1,8}$/.test(last);
+  const looksLikeFile = !isDirectoryLeafName(last);
   if (!looksLikeFile) return { dir: clean || "/" };
   const idx = clean.lastIndexOf("/");
   const dir = idx <= 0 ? "/" : clean.slice(0, idx);

packages/core/src/backend/local/bootstrap.test.ts

@@ -7,6 +7,21 @@ import { join } from "node:path";
 import { LocalBackend } from "./local-backend.js";
 import { SCHEMA_VERSION } from "./schema.js";
 import { resolveLocalPrincipal } from "./identity.js";
+import { resolveSqliteNativeBinding } from "./native-binding.js";
+
+/**
+ * Open a DB the way LocalBackend itself does.
+ *
+ * The white-box `user_version` probes below construct `Database` directly, so
+ * they must honour the same PATHRULE_SQLITE_NATIVE_DIR override the backend
+ * applies. Without it they load better-sqlite3's default binding, which in this
+ * monorepo is the ELECTRON-ABI copy that packages/app rebuilds in node_modules,
+ * and the probe dies on NODE_MODULE_VERSION while the backend beside it works.
+ */
+function openRaw(path: string): Database.Database {
+  const nativeBinding = resolveSqliteNativeBinding();
+  return new Database(path, nativeBinding ? { nativeBinding } : {});
+}
 
 // The canonical-store bootstrap + numbered-migration runner.
 describe("LocalBackend bootstrap", () => {
@@ -51,7 +66,7 @@ describe("LocalBackend bootstrap", () => {
     }
 
     // White-box: user_version reflects the latest applied migration.
-    const raw = new Database(dbPath);
+    const raw = openRaw(dbPath);
     expect(raw.pragma("user_version", { simple: true })).toBe(SCHEMA_VERSION);
     raw.close();
 
@@ -93,7 +108,7 @@ describe("LocalBackend bootstrap", () => {
     // Second open re-runs runMigrations(); must not throw or downgrade user_version.
     const b = LocalBackend.openForWorkspace("ws-y", env);
     b.close();
-    const raw = new Database(join(home, "ws-y", "pathrule.db"));
+    const raw = openRaw(join(home, "ws-y", "pathrule.db"));
     expect(raw.pragma("user_version", { simple: true })).toBe(SCHEMA_VERSION);
     raw.close();
   });

packages/core/src/backend/local/local-backend.ts

@@ -540,23 +540,30 @@ export class LocalBackend implements KnowledgeBackend {
   async updateMemory(input: UpdateMemoryInput): Promise<Memory> {
     const existing = await this.readMemory(input.id);
     if (!existing) throw new Error(`memory ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
-    this.db
+    const nextVersionId = this.genId();
+    const result = this.db
       .prepare(
         `UPDATE memories SET title = ?, content = ?, node_id = ?, version_id = ?, version_number = ?,
-          last_edited_by = ?, last_edited_at = ?, updated_at = ? WHERE id = ?`,
+          last_edited_by = ?, last_edited_at = ?, updated_at = ?
+          WHERE id = ? AND version_id = ?`,
       )
       .run(
         input.title ?? existing.title,
         input.content ?? existing.content,
         input.nodeId ?? existing.nodeId,
-        this.genId(),
+        nextVersionId,
         existing.versionNumber + 1,
         this.principal,
         ts,
         ts,
         input.id,
+        input.expectedVersionId ?? existing.versionId,
       );
+    if (result.changes !== 1) throw new Error("content_version_conflict");
     const updated = await this.readMemory(input.id);
     if (!updated) throw new Error(`memory ${input.id} vanished after update`);
     // Re-embed only when the embedded text actually changed. A node-only re-home
@@ -734,24 +741,31 @@ export class LocalBackend implements KnowledgeBackend {
   async updateRule(input: UpdateRuleInput): Promise<Rule> {
     const existing = await this.readRule(input.id);
     if (!existing) throw new Error(`rule ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
-    this.db
+    const nextVersionId = this.genId();
+    const result = this.db
       .prepare(
         `UPDATE rules SET name = ?, content = ?, scope_type = ?, priority = ?, version_id = ?,
-          version_number = ?, last_edited_by = ?, last_edited_at = ?, updated_at = ? WHERE id = ?`,
+          version_number = ?, last_edited_by = ?, last_edited_at = ?, updated_at = ?
+          WHERE id = ? AND version_id = ?`,
       )
       .run(
         input.name ?? existing.name,
         input.content ?? existing.content,
         input.scopeType ?? existing.scopeType,
         input.priority ?? existing.priority,
-        this.genId(),
+        nextVersionId,
         existing.versionNumber + 1,
         this.principal,
         ts,
         ts,
         input.id,
+        input.expectedVersionId ?? existing.versionId,
       );
+    if (result.changes !== 1) throw new Error("content_version_conflict");
     if (input.nodeId) {
       // Re-home: replace any existing attachments with one pointing at the new node.
       this.db.prepare("DELETE FROM node_rules WHERE rule_id = ?").run(input.id);
@@ -858,6 +872,9 @@ export class LocalBackend implements KnowledgeBackend {
   async updateSkill(input: UpdateSkillInput): Promise<Skill> {
     const existing = await this.readSkill(input.id);
     if (!existing) throw new Error(`skill ${input.id} not found`);
+    if (input.expectedVersionId && input.expectedVersionId !== existing.versionId) {
+      throw new Error("content_version_conflict");
+    }
     const ts = this.now();
     // Patch only supplied fields (null clears description/github_url; never reorder).
     const sets = [
@@ -880,8 +897,11 @@ export class LocalBackend implements KnowledgeBackend {
       sets.push("content_fetched_at = ?");
       vals.push(ts);
     }
-    vals.push(input.id);
-    this.db.prepare(`UPDATE skills SET ${sets.join(", ")} WHERE id = ?`).run(...vals);
+    vals.push(input.id, input.expectedVersionId ?? existing.versionId);
+    const result = this.db
+      .prepare(`UPDATE skills SET ${sets.join(", ")} WHERE id = ? AND version_id = ?`)
+      .run(...vals);
+    if (result.changes !== 1) throw new Error("content_version_conflict");
     if (input.nodeId) {
       this.db.prepare("DELETE FROM node_skills WHERE skill_id = ?").run(input.id);
       this.db