@llblab/pi-actors 0.43.1 → 0.45.0

package/dist/lib/runtime-notifier.js

@@ -1,138 +0,0 @@
-/**
- * Runtime wake notifications for actor state.
- * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
- * Owns best-effort live wake signals while durable Run state remains canonical.
- */
-import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, watch, } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { readJsonlFileResilient } from "./state-readers.js";
-const DEFAULT_POLL_INTERVAL_MS = 1000;
-export function runtimeWakeFile(stateDir) {
-    return join(stateDir, "wake.jsonl");
-}
-function normalizeWakeEvent(stateDir, event) {
-    const actor = event.actor.trim();
-    const reason = event.reason.trim();
-    if (!actor)
-        throw new Error("Runtime wake event requires actor.");
-    if (!reason)
-        throw new Error("Runtime wake event requires reason.");
-    return {
-        actor,
-        id: randomUUID(),
-        ...(event.metadata ? { metadata: event.metadata } : {}),
-        reason,
-        state_dir: stateDir,
-        ts: new Date().toISOString(),
-    };
-}
-export function notifyRuntimeWake(stateDir, event) {
-    const normalized = normalizeWakeEvent(stateDir, event);
-    const file = runtimeWakeFile(stateDir);
-    mkdirSync(dirname(file), { recursive: true });
-    appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
-    return normalized;
-}
-export function parseRuntimeWakeEventLine(line) {
-    try {
-        const record = JSON.parse(line);
-        if (typeof record.actor !== "string" ||
-            typeof record.id !== "string" ||
-            typeof record.reason !== "string" ||
-            typeof record.state_dir !== "string" ||
-            typeof record.ts !== "string") {
-            return undefined;
-        }
-        return {
-            actor: record.actor,
-            id: record.id,
-            ...(record.metadata &&
-                typeof record.metadata === "object" &&
-                !Array.isArray(record.metadata)
-                ? { metadata: record.metadata }
-                : {}),
-            reason: record.reason,
-            state_dir: record.state_dir,
-            ts: record.ts,
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-export function readRuntimeWakeEvents(stateDir) {
-    return readJsonlFileResilient(runtimeWakeFile(stateDir))
-        .records.map((record) => parseRuntimeWakeEventLine(JSON.stringify(record)))
-        .filter((event) => Boolean(event));
-}
-export function createFileRuntimeNotifier(stateDir, options = {}) {
-    const file = runtimeWakeFile(stateDir);
-    const pollIntervalMs = Math.max(25, Number(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS));
-    return {
-        notify: (event) => notifyRuntimeWake(stateDir, event),
-        subscribe: (actor, onWake, subscribeOptions = {}) => {
-            mkdirSync(dirname(file), { recursive: true });
-            let position = options.replay || !existsSync(file) ? 0 : statSync(file).size;
-            let pending = "";
-            let closed = false;
-            const reconcile = (reason) => {
-                if (closed)
-                    return;
-                subscribeOptions.onReconcile?.({
-                    actor,
-                    reason,
-                    state_dir: stateDir,
-                    ts: new Date().toISOString(),
-                });
-            };
-            const drain = () => {
-                if (closed || !existsSync(file))
-                    return;
-                const buffer = readFileSync(file);
-                if (position > buffer.length) {
-                    position = 0;
-                    pending = "";
-                }
-                const chunk = pending + buffer.subarray(position).toString("utf8");
-                position = buffer.length;
-                const lines = chunk.split("\n");
-                pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
-                for (const line of lines) {
-                    if (!line.trim())
-                        continue;
-                    const event = parseRuntimeWakeEventLine(line);
-                    if (event && event.actor === actor) {
-                        onWake(event);
-                        reconcile("wake");
-                    }
-                }
-            };
-            let watcher;
-            if (options.watch !== false) {
-                try {
-                    watcher = watch(dirname(file), { persistent: false }, (_eventType, changedFile) => {
-                        if (!changedFile || String(changedFile) === basename(file))
-                            drain();
-                    });
-                }
-                catch {
-                    // fs.watch availability varies by platform/filesystem; polling below is the fallback.
-                }
-            }
-            reconcile("initial");
-            const timer = setInterval(() => {
-                drain();
-                reconcile("poll");
-            }, pollIntervalMs);
-            timer.unref?.();
-            return {
-                close: () => {
-                    closed = true;
-                    clearInterval(timer);
-                    watcher?.close();
-                },
-            };
-        },
-    };
-}

package/docs/0.43-baseline.md

@@ -1,39 +0,0 @@
-# Released 0.43 Baseline
-
-Release `0.43.0` is frozen at commit `0d6db30cd2e070c1d03ed1e60bef70538a3083c1`. Local and remote `main`, immutable tag `v0.43.0`, the GitHub Release, and `@llblab/pi-actors@0.43.0` all resolve to that commit. The npm artifact records the same `gitHead`, shasum `64b5982bc1cda5723ce2f80f4ed15476b6016d62`, and `latest` dist-tag.
-
-The continuing `dev` line descends from release parent `f4e4e78891e0c3d570b31c35572aeaa226af6f91`, whose tree exactly matches the tagged merge tree. This preserves content equivalence without copying the content-neutral merge wrapper into `dev`.
-
-## Reproduced Evidence
-
-An isolated detached `v0.43.0` worktree produced this evidence on 2026-08-11:
-
-- `npm ci` succeeded with 147 installed packages. Its generic audit summary included three peer-tree findings; the package-owned `--omit=peer` audit passed with zero vulnerabilities.
-- `npm run test:preservation` passed 91 of 91 tests.
-- `npm run release:validate` passed 525 tests with 5 platform skips, 106 conformance tests, 58 Recipe QA files, package dry-run, removed-surface checks, strict Domain DAG, and ABCd context validation.
-- GitHub reported no open issue or pull request requiring post-release scope changes.
-
-## Shipped-Line Ratchet
-
-The released tree contains exactly **28,853** lines under the surfaces measured by `scripts/release-gates.mjs`:
-
-- `lib/`
-- `scripts/`
-- `recipes/`
-- `docs/`
-- `skills/`
-
-Release validation requires every retained post-`0.43.0` tree to remain strictly below 28,853 lines. Tests, fixtures, and workflows remain outside this existing metric. The ratchet prevents deleted communication-plane code from funding replacement bloat; it does not grant removed behavior preservation status.
-
-## Retained Invariants
-
-The preservation suite covers owner-filtered Run discovery, immutable generation fencing, process identity, lifecycle locking, shutdown and parent teardown, terminal reconciliation, bounded complete captures, Pi session provenance, path containment, redaction, review recovery, generation-bound Control, and canonical Trace. Rooms, routing, addressed messages, mailboxes, and communication topology are not retained.
-
-## Validation
-
-```bash
-npm run test:preservation
-npm run release:validate
-```
-
-Release gates also reject removed-surface residue, Domain DAG violations, ABCd context drift, stale package contents, and shipped-line growth at or above the released baseline.

package/lib/runtime-notifier.ts

@@ -1,211 +0,0 @@
-/**
- * Runtime wake notifications for actor state.
- * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
- * Owns best-effort live wake signals while durable Run state remains canonical.
- */
-
-import { randomUUID } from "node:crypto";
-import {
-  appendFileSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  statSync,
-  watch,
-  type FSWatcher,
-} from "node:fs";
-import { basename, dirname, join } from "node:path";
-
-import { readJsonlFileResilient } from "./state-readers.ts";
-
-export interface RuntimeWakeEvent {
-  actor: string;
-  id: string;
-  metadata?: Record<string, unknown>;
-  reason: string;
-  state_dir: string;
-  ts: string;
-}
-
-export interface RuntimeNotifierSubscription {
-  close(): void;
-}
-
-export type RuntimeReconcileReason = "initial" | "poll" | "wake";
-
-export interface RuntimeReconcileEvent {
-  actor: string;
-  reason: RuntimeReconcileReason;
-  state_dir: string;
-  ts: string;
-}
-
-export interface RuntimeNotifierSubscribeOptions {
-  onReconcile?: (event: RuntimeReconcileEvent) => void;
-}
-
-export interface FileRuntimeNotifierOptions {
-  pollIntervalMs?: number;
-  replay?: boolean;
-  watch?: boolean;
-}
-
-export interface RuntimeNotifier {
-  notify(event: { actor: string; metadata?: Record<string, unknown>; reason: string }): RuntimeWakeEvent;
-  subscribe(
-    actor: string,
-    onWake: (event: RuntimeWakeEvent) => void,
-    options?: RuntimeNotifierSubscribeOptions,
-  ): RuntimeNotifierSubscription;
-}
-
-const DEFAULT_POLL_INTERVAL_MS = 1000;
-
-export function runtimeWakeFile(stateDir: string): string {
-  return join(stateDir, "wake.jsonl");
-}
-
-function normalizeWakeEvent(
-  stateDir: string,
-  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
-): RuntimeWakeEvent {
-  const actor = event.actor.trim();
-  const reason = event.reason.trim();
-  if (!actor) throw new Error("Runtime wake event requires actor.");
-  if (!reason) throw new Error("Runtime wake event requires reason.");
-  return {
-    actor,
-    id: randomUUID(),
-    ...(event.metadata ? { metadata: event.metadata } : {}),
-    reason,
-    state_dir: stateDir,
-    ts: new Date().toISOString(),
-  };
-}
-
-export function notifyRuntimeWake(
-  stateDir: string,
-  event: { actor: string; metadata?: Record<string, unknown>; reason: string },
-): RuntimeWakeEvent {
-  const normalized = normalizeWakeEvent(stateDir, event);
-  const file = runtimeWakeFile(stateDir);
-  mkdirSync(dirname(file), { recursive: true });
-  appendFileSync(file, `${JSON.stringify(normalized)}\n`, "utf8");
-  return normalized;
-}
-
-export function parseRuntimeWakeEventLine(
-  line: string,
-): RuntimeWakeEvent | undefined {
-  try {
-    const record = JSON.parse(line) as Record<string, unknown>;
-    if (
-      typeof record.actor !== "string" ||
-      typeof record.id !== "string" ||
-      typeof record.reason !== "string" ||
-      typeof record.state_dir !== "string" ||
-      typeof record.ts !== "string"
-    ) {
-      return undefined;
-    }
-    return {
-      actor: record.actor,
-      id: record.id,
-      ...(record.metadata &&
-      typeof record.metadata === "object" &&
-      !Array.isArray(record.metadata)
-        ? { metadata: record.metadata as Record<string, unknown> }
-        : {}),
-      reason: record.reason,
-      state_dir: record.state_dir,
-      ts: record.ts,
-    };
-  } catch {
-    return undefined;
-  }
-}
-
-export function readRuntimeWakeEvents(stateDir: string): RuntimeWakeEvent[] {
-  return readJsonlFileResilient<Record<string, unknown>>(runtimeWakeFile(stateDir))
-    .records.map((record) => parseRuntimeWakeEventLine(JSON.stringify(record)))
-    .filter((event): event is RuntimeWakeEvent => Boolean(event));
-}
-
-export function createFileRuntimeNotifier(
-  stateDir: string,
-  options: FileRuntimeNotifierOptions = {},
-): RuntimeNotifier {
-  const file = runtimeWakeFile(stateDir);
-  const pollIntervalMs = Math.max(
-    25,
-    Number(options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS),
-  );
-
-  return {
-    notify: (event) => notifyRuntimeWake(stateDir, event),
-    subscribe: (actor, onWake, subscribeOptions = {}) => {
-      mkdirSync(dirname(file), { recursive: true });
-      let position =
-        options.replay || !existsSync(file) ? 0 : statSync(file).size;
-      let pending = "";
-      let closed = false;
-      const reconcile = (reason: RuntimeReconcileReason): void => {
-        if (closed) return;
-        subscribeOptions.onReconcile?.({
-          actor,
-          reason,
-          state_dir: stateDir,
-          ts: new Date().toISOString(),
-        });
-      };
-      const drain = (): void => {
-        if (closed || !existsSync(file)) return;
-        const buffer = readFileSync(file);
-        if (position > buffer.length) {
-          position = 0;
-          pending = "";
-        }
-        const chunk = pending + buffer.subarray(position).toString("utf8");
-        position = buffer.length;
-        const lines = chunk.split("\n");
-        pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
-        for (const line of lines) {
-          if (!line.trim()) continue;
-          const event = parseRuntimeWakeEventLine(line);
-          if (event && event.actor === actor) {
-            onWake(event);
-            reconcile("wake");
-          }
-        }
-      };
-
-      let watcher: FSWatcher | undefined;
-      if (options.watch !== false) {
-        try {
-          watcher = watch(
-            dirname(file),
-            { persistent: false },
-            (_eventType, changedFile) => {
-              if (!changedFile || String(changedFile) === basename(file)) drain();
-            },
-          );
-        } catch {
-          // fs.watch availability varies by platform/filesystem; polling below is the fallback.
-        }
-      }
-      reconcile("initial");
-      const timer = setInterval(() => {
-        drain();
-        reconcile("poll");
-      }, pollIntervalMs);
-      timer.unref?.();
-      return {
-        close: () => {
-          closed = true;
-          clearInterval(timer);
-          watcher?.close();
-        },
-      };
-    },
-  };
-}