pi-pier 0.3.0 → 0.4.1

package/src/efficiency-store.ts

@@ -1,15 +1,7 @@
 /**
- * D101-D103 Efficiency Storage & I/O Adapter.
- *
- * Implements safe, content-addressed storage for ObservationPack and
- * Evidence-Preserving Reducer, along with telemetry log appending and
- * secure bash un-truncated output reading.
- *
- * Security & Integrity:
- *  - Mode 0700 for directories, 0600 for object and log files.
- *  - O_NOFOLLOW to forbid symlinks.
- *  - Safe sessionId regex validation.
- *  - EEXIST integrity verification (rejects corrupted collisions).
+ * D101-D103 efficiency storage: content-addressed objects (ObservationPack / EPR), telemetry appends
+ * and the un-truncated bash log reader. Integrity: directories 0700, files 0600, O_NOFOLLOW everywhere,
+ * session ids regex-validated, and an EEXIST collision is re-verified (size + sha256) instead of trusted.
  */
 
 import { constants } from 'node:fs';
@@ -23,8 +15,8 @@ import {
   type RecallSliceResult,
 } from './observation-core.ts';
 
-export const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
-export const BASH_LOG_NAME_RE = /^pi-bash-.*\.log$/;
+const SAFE_SESSION_ID_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+const BASH_LOG_NAME_RE = /^pi-bash-.*\.log$/;
 
 const READ_OBJECT_FLAGS = constants.O_RDONLY | constants.O_NOFOLLOW;
 const CREATE_OBJECT_FLAGS =
@@ -66,15 +58,15 @@ export function reducerObjectPath(root: string, sha256: string): string {
 
 export function efficiencyLogPath(
   root: string,
-  mechanism: 'compact' | 'observation' | 'reducer' | 'jev',
+  mechanism: 'compact' | 'observation' | 'reducer' | 'jev' | 'routing' | 'tools',
   customPath?: string,
 ): string {
   if (customPath && typeof customPath === 'string') return resolve(customPath);
   return join(root, 'efficiency-logs', `${mechanism}.jsonl`);
 }
 
-export const MAX_OBJECTS_PER_DIR = 300;
-export const MAX_OBJECTS_TOTAL_BYTES = 50 * 1024 * 1024; // 50MB
+const MAX_OBJECTS_PER_DIR = 300;
+const MAX_OBJECTS_TOTAL_BYTES = 50 * 1024 * 1024;
 
 export async function pruneObjectsDirectory(
   dir: string,
@@ -98,7 +90,6 @@ export async function pruneObjectsDirectory(
           totalBytes += s.size;
         }
       } catch {
-        /* ignore stat errors */
       }
     }
 
@@ -106,7 +97,6 @@ export async function pruneObjectsDirectory(
       return 0;
     }
 
-    // Sort by mtime ascending (oldest first)
     files.sort((a, b) => a.mtimeMs - b.mtimeMs);
 
     let removedCount = 0;
@@ -122,7 +112,6 @@ export async function pruneObjectsDirectory(
           if (k.startsWith(f.path)) verifiedObjectCache.delete(k);
         }
       } catch {
-        /* ignore unlink errors */
       }
     }
     return removedCount;
@@ -131,7 +120,6 @@ export async function pruneObjectsDirectory(
   }
 }
 
-/** Prune both content-addressed object dirs of one session root; returns total removed files. */
 export async function pruneSessionObjects(
   sessionRoot: string,
   limits: { maxFiles?: number; maxTotalBytes?: number } = {},
@@ -173,7 +161,6 @@ export async function storeContentAddressedObject(
     verifiedObjectCache.add(`${filePath}:${contentBytes}:${writtenStat.mtimeMs}:${hash}`);
   } catch (err) {
     if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
-      // Verify existing file integrity
       const existingHandle = await open(filePath, READ_OBJECT_FLAGS);
       try {
         const existingStat = await existingHandle.stat();
@@ -234,13 +221,18 @@ export async function readStoredObjectChunk(
     const available = Math.max(0, fileStat.size - offset);
     const buffer = Buffer.alloc(Math.min(available, limits.maxBytes + 4));
     const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
-    return sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
+    const sliced = sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
+    // sliceBufferChunk's nextOffset is relative to the window it was given (offset 0). Callers page
+    // with the absolute file offset from the header, so add the seek back.
+    const nextOffset = offset + sliced.nextOffset;
+    return { ...sliced, nextOffset, eof: nextOffset >= fileStat.size };
   } finally {
     await handle?.close();
   }
 }
 
-export const MAX_EFFICIENCY_LOG_BYTES = 5 * 1024 * 1024; // 5MB rotation ceiling
+/** Rotation ceiling: rename to `<log>.old` past this size so a log can never grow unbounded. */
+const MAX_EFFICIENCY_LOG_BYTES = 5 * 1024 * 1024;
 
 export async function appendEfficiencyLog(
   logPath: string,
@@ -250,7 +242,6 @@ export async function appendEfficiencyLog(
   const dir = dirname(logPath);
   await mkdir(dir, { recursive: true, mode: 0o700 });
 
-  // Rotate log if exceeds maximum size to prevent unbounded disk growth
   try {
     const s = await stat(logPath);
     if (s.size > MAX_EFFICIENCY_LOG_BYTES) {
@@ -259,7 +250,6 @@ export async function appendEfficiencyLog(
       await rename(logPath, oldPath);
     }
   } catch {
-    /* file may not exist yet, continue */
   }
 
   let handle;
@@ -271,9 +261,7 @@ export async function appendEfficiencyLog(
   }
 }
 
-/**
- * Safely reads Pi's untruncated bash output from temporary file.
- */
+/** Safely reads Pi's untruncated bash output from temporary file. */
 export async function readBashFullOutput(
   rawPath: string | null | undefined,
   maxChars: number,
@@ -292,7 +280,6 @@ export async function readBashFullOutput(
     const fileStat = await stat(realFile);
     if (!fileStat.isFile() || fileStat.isSymbolicLink()) return null;
 
-    // Check size within reasonable limit
     if (fileStat.size > maxChars * 4) return null;
 
     let handle = await open(realFile, READ_OBJECT_FLAGS);

package/src/gc-core.ts

@@ -1,7 +1,4 @@
-/**
- * Task-tab GC decisions (D29 rules as a pure function; M22 dropped resident exemption).
- * No I/O, no pi/herdr — unit-testable.
- */
+/** Task-tab GC decisions (D29 rules as a pure function; no I/O, no pi/herdr). */
 export type GcEntryKind = string;
 export type GcEntryStatus = 'running' | 'settled' | 'consumed' | 'closed';
 
@@ -17,14 +14,8 @@ function isFinished(status: GcEntryStatus): boolean {
   return status === 'consumed' || status === 'closed' || status === 'settled';
 }
 
-/**
- * Close a task tab only when every condition holds:
- *  - ≥1 work pane (the main tab with no delegated entries never closes);
- *  - every work pane is settled/consumed/closed (kind is not an exemption);
- *  - grace TTL elapsed (`ttlMs=0` means never auto-close);
- *  - no blocked pane (human-gate exemption);
- *  - remaining panes are idle/done/unknown (non-work panes may be unknown).
- */
+/** Close a task tab only when every work pane finished, the grace TTL elapsed (`ttlMs=0` means never
+ *  auto-close), no pane is blocked and the rest are idle/done/unknown. */
 export function shouldCloseTaskTab(opts: {
   entries: readonly GcEntryLike[];
   paneStatuses: readonly string[];
@@ -39,12 +30,8 @@ export function shouldCloseTaskTab(opts: {
   return true;
 }
 
-/**
- * Pane-level collection (orphan / compat path):
- *  - consumed before the previous turn (grace so the settlement notice is still visible);
- *  - herdr status idle/done (unknown/working/blocked retry next turn);
- *  - missing pane (status undefined) → record closed (caller handles the write).
- */
+/** Pane-level collection (orphan / compat path): consumed before the previous turn (grace so the
+ *  settlement notice is still visible); missing pane → record closed (caller handles the write). */
 export function shouldClosePane(opts: {
   consumedAt: number | null;
   herdrStatus: string | undefined;
@@ -55,18 +42,11 @@ export function shouldClosePane(opts: {
   return (opts.consumedAt ?? 0) > 0 && opts.consumedAt! < opts.prevTurnStart;
 }
 
-/* ── Isolate worktree collection (why the rules are this narrow) ──────
- * The first version treated ANY branch under `refs/heads/pier/` as pier-owned, so
- * every pier master session swept the whole namespace. A worker session lives in
- * exactly such a worktree, and its own branch is trivially an ancestor of its own
- * HEAD and clean once it commits — so the sweep deleted the worktree the process
- * was running in (observed twice: 01a06ae3-era workers and the env-hook worker).
- * Ownership must therefore be explicit: only branches registered in THIS session's
- * subagent registry are candidates, the current working directory is never a
- * candidate, and untracked `pier/*` branches require an explicit opt-in.
- */
+/* Isolate worktree collection is deliberately narrow: `refs/heads/pier/*` is NOT proof of pier
+ * ownership — a worker session lives in such a worktree, so a namespace-wide sweep deletes the
+ * worktree its own process is running in. Only THIS session's registered branches are candidates,
+ * cwd never is, and untracked `pier/*` branches need an explicit opt-in. */
 
-/** True when `path` is `parent` or lives inside it (both resolved, no I/O). */
 export function isPathInside(path: string, parent: string): boolean {
   const norm = (p: string): string => p.replace(/[\\/]+/g, '/').replace(/\/+$/, '');
   const child = norm(path);
@@ -90,20 +70,14 @@ export interface IsolateSweepPlan {
   skipped: IsolateSweepSkip[];
 }
 
-/**
- * Decide which isolate worktrees this session may collect.
- * Pure: callers pass git output, the subagent registry and the process cwd.
- */
+/** Pure: callers pass git output, the subagent registry and the process cwd. */
 export function planIsolateSweep(input: {
-  /** Every `refs/heads/pier/*` branch name. */
   branches: readonly string[];
   /** branch → worktree path, from `git worktree list --porcelain`. */
   worktreesByBranch: ReadonlyMap<string, string>;
-  /** Branches of isolate entries in this session's registry. */
   registeredBranches: ReadonlySet<string>;
   /** Branches created but not yet registered (worktree add → subs.set window). */
   pendingBranches: ReadonlySet<string>;
-  /** Session-owned isolates that may be collected, with their recorded path. */
   sessionOwned: ReadonlyArray<{ branch: string; worktreePath: string }>;
   /** Path to protect (normally process.cwd()). */
   cwd: string;

package/src/guards.ts

@@ -0,0 +1,6 @@
+/** Shared structural guards used by the *-core validators. */
+
+/** Plain JSON object: not null, not an array. */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}