@plurnk/plurnk-service 1.0.0

package/dist/core/env-defaults.js

@@ -0,0 +1,89 @@
+import { parseEnv } from "node:util";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import Meta from "@plurnk/plurnk-meta";
+export default class EnvDefaults {
+    static async #readDefaults(dir, owner) {
+        let text;
+        try {
+            text = await readFile(join(dir, ".env.defaults"), "utf8");
+        }
+        catch {
+            return null;
+        }
+        // parseEnv never throws — it silently mints junk keys from malformed lines. Malformed =
+        // any parsed key that isn't a valid env name; crash naming the owner — a broken defaults
+        // file is a broken package, never a silently-degraded floor.
+        const parsed = parseEnv(text);
+        const junk = Object.keys(parsed).filter((k) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(k));
+        if (junk.length > 0)
+            throw new Error(`${owner}: malformed .env.defaults — invalid key(s): ${junk.map((k) => JSON.stringify(k)).join(", ")}`);
+        return { owner, text, parsed };
+    }
+    // Enumerate installed package dirs via the shared membership primitives
+    // (@plurnk/plurnk-meta); keep ecosystem members that ship a .env.defaults.
+    static async #memberFiles(nodeModules) {
+        const dirs = await Meta.packageDirs(nodeModules);
+        const files = [];
+        for (const { dir, name } of dirs.toSorted((a, b) => a.name.localeCompare(b.name))) {
+            if (!Meta.isTrusted(name))
+                continue;
+            if (!name.startsWith("@plurnk/")) {
+                let pkg;
+                try {
+                    pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+                }
+                catch {
+                    continue;
+                }
+                if (pkg.plurnk === undefined)
+                    continue; // not an ecosystem member
+            }
+            const file = await EnvDefaults.#readDefaults(dir, name);
+            if (file !== null)
+                files.push(file);
+        }
+        return files;
+    }
+    // The host's own file first, then every installed member's, name-sorted (deterministic).
+    // The host is excluded from the member scan — a workspace checkout symlinks the daemon
+    // into node_modules as its own member, and self-vs-self is not a collision.
+    static async collect(serviceRoot, nodeModules) {
+        const own = await EnvDefaults.#readDefaults(serviceRoot, "@plurnk/plurnk-service");
+        if (own === null)
+            throw new Error("@plurnk/plurnk-service: .env.defaults missing from the package root — the shipped floor is not optional");
+        const members = await EnvDefaults.#memberFiles(nodeModules);
+        return [own, ...members.filter((m) => m.owner !== own.owner)];
+    }
+    // The ONE law: global key uniqueness. A collision names both claimants — it is also the
+    // deliberate handoff signal when a sibling adopts a section the host carried for it.
+    static merge(files) {
+        const merged = new Map();
+        for (const { owner, parsed } of files) {
+            for (const [key, value] of Object.entries(parsed)) {
+                const prior = merged.get(key);
+                if (prior !== undefined)
+                    throw new Error(`env-defaults collision: ${key} is claimed by both ${prior.owner} and ${owner} — a knob has exactly one owner`);
+                merged.set(key, { value, owner });
+            }
+        }
+        return merged;
+    }
+    // The floor: set-if-unset, under everything the operator already set.
+    static apply(merged) {
+        for (const [key, { value }] of merged)
+            process.env[key] ??= value;
+    }
+    // ~/.plurnk/.env.defaults — the operator's catalog: every member's raw file (comments are the
+    // docs), owner-labelled. Machine-owned, regenerated each boot, never read back as config.
+    static renderCatalog(files) {
+        const head = [
+            "# ⚠ MACHINE-OWNED — regenerated on every daemon boot from the installed packages'",
+            "# .env.defaults files. Do NOT edit; your config lives in ~/.plurnk/.env (yours, wins",
+            "# over this floor) or the shell env. One section per owning package.",
+            "",
+        ].join("\n");
+        return head + files.map(({ owner, text }) => `# ═══ ${owner} ═══\n${text.trimEnd()}\n`).join("\n");
+    }
+}
+//# sourceMappingURL=env-defaults.js.map

package/dist/core/env-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-defaults.js","sourceRoot":"","sources":["../../src/core/env-defaults.ts"],"names":[],"mappings":"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"}

package/dist/core/fork.d.ts

@@ -0,0 +1,6 @@
+import type { Db } from "./Db.ts";
+export default class Fork {
+    #private;
+    static fork(db: Db, parentRunId: number, name?: string): Promise<number>;
+}
+//# sourceMappingURL=fork.d.ts.map

package/dist/core/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAE9C,MAAM,CAAC,OAAO,OAAO,IAAI;;IAIrB,OAAa,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyE7E;CACJ"}

package/dist/core/fork.js

@@ -0,0 +1,84 @@
+// Fork a run — branch the log, share the session (SPEC §machine-processes).
+//
+// A fork is a NEW run in the SAME session (`parent_run_id` records the lineage),
+// holding a deep copy of the parent's log: loops → turns → entries, with their
+// fold-state (`expanded`) and attribution (`origin`/`source`) intact. It copies
+// nothing of the shared WORLD — the session's entries and overlay are shared, never
+// copied, because a run never owned them. But it DOES inherit the parent's run-scope
+// SCRATCH (§run-scheme — the run's private workspace, owner-remapped parent → branch):
+// "fork = everything-in-common-but-name, then diverges". The §env-delta reconciliation
+// snapshot is not copied; the branch first-sights its world like any fresh run.
+export default class Fork {
+    // Terminal loop statuses (§lifecycle-terms) — inherited loops outside this set are clamped to 200.
+    static #TERMINAL_LOOP = new Set([200, 413, 429, 499, 500, 504, 508]);
+    static async fork(db, parentRunId, name) {
+        const parent = await db.fork_get_run.get({ id: parentRunId });
+        if (parent === undefined)
+            throw new Error(`fork: run ${parentRunId} not found`);
+        // #248 — name the branch at instantiation (immutable after). An explicit name wins; the default
+        // is `<parent>-fork-<N>` (N = next free), so N self-forks of one parent are individually
+        // addressable instead of all colliding on a single `<parent>-fork` (§run-scheme-fork).
+        let branchName = name;
+        if (branchName === undefined) {
+            const existing = await db.fork_count_branches.get({ parent_run_id: parentRunId, name_prefix: `${parent.name}-fork%` });
+            branchName = `${parent.name}-fork-${(existing?.n ?? 0) + 1}`;
+        }
+        const branch = await db.fork_insert_run.get({
+            session_id: parent.session_id, name: branchName, parent_run_id: parentRunId, origin: parent.origin,
+        });
+        if (branch === undefined)
+            throw new Error("fork: branch run insert returned no row");
+        const branchRunId = branch.id;
+        // loops → new loops, mapping old id → new id. A copied loop is INHERITED HISTORY, never the
+        // branch's live work (its own loop is enqueued fresh by injectRun) — so a non-terminal status
+        // is clamped to terminal (200). Otherwise a fork taken while the parent's loop is mid-flight (102)
+        // would carry a frozen-live loop no drain ever advances, falsely marking the branch forever-live
+        // to any liveness check (§run-scheme-fork, the premature-terminate gate §send-premature-terminate).
+        const loops = await db.fork_get_loops.all({ run_id: parentRunId });
+        const loopMap = new Map();
+        for (const l of loops) {
+            const status = Fork.#TERMINAL_LOOP.has(l.status) ? l.status : 200;
+            const nl = await db.fork_insert_loop.get({ run_id: branchRunId, sequence: l.sequence, status, prompt: l.prompt, flags: l.flags });
+            if (nl === undefined)
+                throw new Error("fork: loop insert returned no row");
+            loopMap.set(l.id, nl.id);
+        }
+        // turns → new turns, loop_id remapped, mapping old id → new id.
+        const turns = await db.fork_get_turns.all({ run_id: parentRunId });
+        const turnMap = new Map();
+        for (const { id, loop_id, ...rest } of turns) {
+            // #254 — a fork inherits the parent's log for context but spends no new money:
+            // the copied turns are history, not fresh generations. Zero their usage so the
+            // cost-rollup triggers add nothing — the session total stays true lifetime spend
+            // (no double-count) and the branch's cost_pico accrues only what IT generates.
+            const nt = await db.fork_insert_turn.get({
+                ...rest, usage_prompt: 0, usage_completion: 0, usage_reasoning: 0, usage_cached: 0, usage_cost_pico: 0,
+                loop_id: loopMap.get(loop_id),
+            });
+            if (nt === undefined)
+                throw new Error("fork: turn insert returned no row");
+            turnMap.set(id, nt.id);
+        }
+        // entries → new entries: run/loop/turn ids remapped; fold-state and
+        // attribution and content all preserved.
+        const entries = await db.fork_get_log_entries.all({ run_id: parentRunId });
+        for (const e of entries) {
+            await db.fork_insert_log_entry.run({ ...e, run_id: branchRunId, loop_id: loopMap.get(e.loop_id), turn_id: turnMap.get(e.turn_id) });
+        }
+        // §run-scheme — inherit the parent's run-scope SCRATCH, owner remapped (parent → branch) in
+        // the pathname so the branch's private workspace is independent and diverges on its own edits.
+        const parentPrefix = `/${parent.name}/`;
+        const branchPrefix = `/${branchName}/`;
+        const scratch = await db.fork_get_run_scope_entries.all({ session_id: parent.session_id, owner_prefix: `${parentPrefix}*` });
+        for (const s of scratch) {
+            const newPathname = branchPrefix + s.pathname.slice(parentPrefix.length);
+            const ne = await db.fork_insert_run_scope_entry.get({ session_id: parent.session_id, scheme: s.scheme, pathname: newPathname, deep_hash: s.deep_hash, attributes: s.attributes });
+            if (ne === undefined)
+                throw new Error("fork: run-scope entry copy returned no row");
+            await db.fork_copy_entry_channels.run({ old_entry_id: s.id, new_entry_id: ne.id });
+            await db.fork_copy_entry_tags.run({ old_entry_id: s.id, new_entry_id: ne.id });
+        }
+        return branchRunId;
+    }
+}
+//# sourceMappingURL=fork.js.map

package/dist/core/fork.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.js","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"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"}

package/dist/core/fork.sql

@@ -0,0 +1,85 @@
+-- Fork a run: deep-copy its log into a NEW run in the SAME session (SPEC §machine-processes —
+-- branch the log, share the world). loops → turns → entries are copied with their
+-- fold-state (expanded) and attribution (origin/source) intact; only the run/loop/
+-- turn ids are remapped. Nothing of the world is copied (§machine-processes-fork-shares-the-world) — the session's entries and
+-- overlay are shared. The §env-delta reconciliation snapshot (run_watermarks) is NOT
+-- copied; the branch first-sights its world like any fresh run.
+
+-- PREP: fork_get_run
+SELECT session_id, name, origin FROM runs WHERE id = $id;
+
+-- PREP: fork_insert_run
+-- A new run in the parent's session; lineage recorded via parent_run_id (§lifecycle-terms).
+INSERT INTO runs (session_id, name, parent_run_id, origin)
+VALUES ($session_id, $name, $parent_run_id, $origin)
+RETURNING id;
+
+-- PREP: fork_count_branches
+-- How many fork branches the parent already has — for a UNIQUE `<parent>-fork-<N>` default name, so N
+-- self-forks of one parent are individually addressable (KILL/SEND/READ by name) instead of colliding
+-- on a single `<parent>-fork` that run_resolve_by_name would resolve to the newest only (§run-scheme-fork).
+SELECT COUNT(*) AS n FROM runs WHERE parent_run_id = $parent_run_id AND name LIKE $name_prefix;
+
+-- PREP: fork_get_loops
+SELECT id, sequence, status, prompt, flags
+FROM loops WHERE run_id = $run_id ORDER BY id;
+
+-- PREP: fork_insert_loop
+INSERT INTO loops (run_id, sequence, status, prompt, flags)
+VALUES ($run_id, $sequence, $status, $prompt, $flags)
+RETURNING id;
+
+-- PREP: fork_get_turns
+-- All turns across the run's loops, in order — loop_id is remapped by the caller.
+SELECT t.id, t.loop_id, t.sequence, t.timestamp, t.status,
+       t.usage_prompt, t.usage_completion, t.usage_cached, t.usage_cost_pico,
+       t.packet, t.finish_reason, t.model
+FROM turns t JOIN loops l ON l.id = t.loop_id
+WHERE l.run_id = $run_id ORDER BY t.id;
+
+-- PREP: fork_insert_turn
+INSERT INTO turns (loop_id, sequence, timestamp, status, usage_prompt, usage_completion, usage_reasoning, usage_cached, usage_cost_pico, packet, finish_reason, model)
+VALUES ($loop_id, $sequence, $timestamp, $status, $usage_prompt, $usage_completion, $usage_reasoning, $usage_cached, $usage_cost_pico, $packet, $finish_reason, $model)
+RETURNING id;
+
+-- PREP: fork_get_log_entries
+-- Everything but the row id and run_id (run_id is the branch's; loop_id/turn_id are
+-- remapped by the caller). origin/source (attribution) and expanded (fold-state) ride along. §machine-processes-fork-copies-the-log
+SELECT loop_id, turn_id, sequence, at, origin, source, op, suffix, signal,
+       scheme, username, password, hostname, port, pathname, params, fragment,
+       lineMarker, tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens,
+       state, outcome, attrs, expanded
+FROM log_entries WHERE run_id = $run_id ORDER BY id;
+
+-- PREP: fork_insert_log_entry
+INSERT INTO log_entries (run_id, loop_id, turn_id, sequence, at, origin, source, op, suffix, signal, scheme, username, password, hostname, port, pathname, params, fragment, lineMarker, tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens, state, outcome, attrs, expanded)
+VALUES ($run_id, $loop_id, $turn_id, $sequence, $at, $origin, $source, $op, $suffix, $signal, $scheme, $username, $password, $hostname, $port, $pathname, $params, $fragment, $lineMarker, $tx, $mimetype_tx, $rx, $mimetype_rx, $status_rx, $tokens, $state, $outcome, $attrs, $expanded);
+
+-- §run-scheme — a fork inherits the parent's run-scope SCRATCH (its private workspace), distinct
+-- from the shared session world above: "fork = everything-in-common-but-name, then diverges". The
+-- entries are deep-copied (new ids) with the owner remapped in the pathname (parent → branch), so
+-- the branch's scratch is independent — it edits its own without touching the parent's.
+
+-- PREP: fork_get_run_scope_entries
+-- The parent's run-scope entries (owner = the parent's run name, prefix `/<parent>/*`). deep_hash
+-- and attributes ride along; copying the channels with their tokens keeps the deep_hash valid so
+-- the next-turn pump skips re-derivation (the content is byte-identical).
+SELECT id, scheme, pathname, deep_hash, attributes
+FROM entries WHERE scope = 'run' AND session_id = $session_id AND pathname GLOB $owner_prefix ORDER BY id;
+
+-- PREP: fork_insert_run_scope_entry
+-- A run-scope entry copy with the owner-remapped pathname. synced_sig/membership_origin are NULL
+-- (scratch is never disk-synced nor a file member); version defaults 0.
+INSERT INTO entries (scope, session_id, scheme, pathname, deep_hash, attributes)
+VALUES ('run', $session_id, $scheme, $pathname, $deep_hash, $attributes)
+RETURNING id;
+
+-- PREP: fork_copy_entry_channels
+-- Copy every channel (body + derived graph/fts/embedding) from the source entry to the copy — one
+-- statement, content/tokens/state preserved, so the deep_hash gate holds and nothing re-derives.
+INSERT INTO entry_channels (entry_id, name, content, mimetype, tokens, state)
+SELECT $new_entry_id, name, content, mimetype, tokens, state FROM entry_channels WHERE entry_id = $old_entry_id;
+
+-- PREP: fork_copy_entry_tags
+INSERT INTO entry_tags (entry_id, tag)
+SELECT $new_entry_id, tag FROM entry_tags WHERE entry_id = $old_entry_id;

package/dist/core/git-membership.d.ts

@@ -0,0 +1,23 @@
+import type { Db } from "./Db.ts";
+import type { PlurnkSchemeContext } from "./scheme-types.ts";
+export interface FsDivergence {
+    pathname: string;
+    scheme: string | null;
+    entryId: number;
+    channel: string;
+    before: string;
+    after: string;
+}
+export default class GitMembership {
+    #private;
+    static resolveGitMembership(db: Db, sessionId: number, signal: AbortSignal | undefined): Promise<string[]>;
+    static resolveMembershipEffects(db: Db, sessionId: number, signal: AbortSignal | undefined): Promise<{
+        members: Array<{
+            path: string;
+            effect: "member" | "view";
+        }>;
+        hidden: string[];
+    }>;
+    static indexGitMembership(ctx: PlurnkSchemeContext): Promise<FsDivergence[]>;
+}
+//# sourceMappingURL=git-membership.d.ts.map

package/dist/core/git-membership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-membership.d.ts","sourceRoot":"","sources":["../../src/core/git-membership.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAO7D,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,CAAC,OAAO,OAAO,aAAa;;IAmK9B,OAAa,oBAAoB,CAC7B,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAAG,SAAS,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAkCnB;IASD,OAAa,wBAAwB,CACjC,EAAE,EAAE,EAAE,EACN,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAAG,SAAS,GAChC,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAkB5F;IAsGD,OAAa,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAUjF;CACJ"}