pi-daddy 0.28.0 → 0.32.0

package/src/herdr-stage.ts

@@ -1,55 +0,0 @@
-/**
- * Staging a definition's instructions to a file, because herdr cannot carry them in argv.
- *
- * Split out of `src/run-herdr.ts` at the 400-line ceiling. A real seam rather than an arbitrary cut: this is
- * the one place that works around a **herdr encoding limit**, and it is the only part of the herdr path that
- * touches the filesystem. `run-herdr.ts` starts and reaps agents; this prepares one argument.
- */
-
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-/**
- * Move a multi-line `--append-system-prompt` out of argv, because herdr cannot encode it.
- *
- * **Measured.** `herdr agent start` types the argv into the pane's shell, so a value containing newlines
- * is rejected outright: `invalid_agent_argument — agent arguments cannot be encoded safely for the target
- * shell`. A definition's `SKILL.md` body is always multi-line, so every `delegate({agent})` spawn would
- * fail on this path.
- *
- * pi accepts a **file path** there as readily as literal text (`resolvePromptInput` + `existsSync` in
- * `dist/core/resource-loader.js`), so the fix is to write the body to a temp file and pass its path — one
- * short, shell-safe argument.
- *
- * The split lives here rather than in `planSpawn` because the constraint is **herdr's**, not pi's: the
- * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
- * temp files for everybody would be paying one executor's tax on both paths.
- */
-export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
-  const at = args.indexOf("--append-system-prompt");
-  if (at === -1 || at + 1 >= args.length) return { args };
-  return { args: [...args.slice(0, at), ...args.slice(at + 2)], systemPrompt: args[at + 1] };
-}
-
-/**
- * Move a multi-line system prompt into a temp file and return argv pointing at it.
- *
- * Returns the directory so the caller can remove it — and **every** early return on the herdr path must, because
- * nothing else can: a reviewer measured a permanent `/tmp/grants-herdr-*` per failed `tab create`, unreachable by
- * either pane sweep because the pane it belonged to never existed.
- */
-export async function stageSystemPrompt(
-  args: string[],
-): Promise<{ args: string[]; promptDir?: string; error?: string }> {
-  const split = splitSystemPrompt(args);
-  if (split.systemPrompt === undefined) return { args: split.args };
-  try {
-    const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
-    const file = join(promptDir, "system-prompt.md");
-    await writeFile(file, split.systemPrompt, "utf8");
-    return { args: [...split.args, "--append-system-prompt", file], promptDir };
-  } catch (error) {
-    return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
-  }
-}

package/src/init.ts

@@ -1,389 +0,0 @@
-/**
- * `pi-daddy init` — scaffold a governed project from the skill packages already installed (B2, P3).
- *
- * Legacy unregistered npm packages can be scaffolded per skill: create a directory, copy the
- * body and declaration copies plus a starting `PI_GRANTS_GRANT`. Configured enabled Pi resources
- * are referenced where installed instead (ADR-0074); no competing .pi/skills copy is created.
- *
- * **The line it does not cross, and the reason this module exists at all:** `init` writes files an operator
- * then **reviews, edits and commits**. It never chooses a ceiling. A skill that declares `allowed-tools` is
- * copied *verbatim* — the author's declaration is the ceiling, and re-deriving it here would put a second
- * opinion between the file and the enforcer. A skill that declares none is copied with a **commented**
- * placeholder and stays unspawnable until a human fills it in.
- *
- * **What it DOES choose is the starting grant, which is a stronger act** — ADR-0029, added after a reviewer
- * pointed out that ADR-0028 drew its boundary around the wrong object. The handoff's reason a third party
- * may safely author `allowed-tools` is that *"the operator's `PI_GRANTS_GRANT` still bounds it"*; a
- * generated union gives the bound and the bounded one author, and it is not the operator. So capabilities
- * that can change a machine are emitted **commented** (`./grant-env.ts`).
- *
- * The placeholder is deliberately not a working example. Uncommenting it unedited yields capability ids
- * like `tool:<list` which the catalog refuses as unknown — a loud failure, in the direction rule 8 asks
- * for, rather than a grant nobody decided.
- */
-
-import { lstat, mkdir, open, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { agentCapability, workspaceCapability } from "./capabilities.ts";
-import { ceilingForDefinition } from "./definitions.ts";
-import { runWithFinalizers } from "./finalization.ts";
-import { ALWAYS_LIVE, assertGrantIsWritable, isLiveByDefault, renderGrantEnv, type GrantEnvSkill } from "./grant-env.ts";
-import { PI_BUILTIN_TOOLS } from "./pi-tools.ts";
-import type { Capability } from "./resolve.ts";
-import type { SkillPackage } from "./skill-packages.ts";
-
-/**
- * Count declarations, not authorizations (R-73). Both pattern and needs-withheld mean the skill
- * declared a ceiling; only undeclared means it did not. The CLI must report the same distinction.
- */
-export function countDeclaring(skills: PlannedSkill[], from: string): number {
-  return skills.filter((s) => s.from === from && s.withheld !== "undeclared").length;
-}
-
-export type WithholdReason = "undeclared" | "pattern" | "needs-withheld";
-
-export interface PlannedSkill {
-  name: string;
-  /** Which package it came from, as `name@version`. */
-  from: string;
-  sourcePath: string;
-  targetPath: string;
-  /** Configured skills stay at their installed/local source, including when --force is used. */
-  referenced?: boolean;
-  /** Exactly what would be written — the file verbatim, or the file plus a commented note. */
-  content: string;
-  /** The declared ceiling, empty when the declaration is absent or unusable. */
-  ceiling: Capability[];
-  withheld: WithholdReason | null;
-  /** e.g. a sub-tool pattern pi's `--tools` cannot express. Reported, never reinterpreted. */
-  notes: string[];
-}
-
-export interface InitPlan {
-  skills: PlannedSkill[];
-  /** Definitions two packages both declare. First wins; the loser is named rather than silently dropped. */
-  collisions: string[];
-  /** The live grant — what `source .pi/grants.env` actually sets. */
-  grant: Capability[];
-  /** Withheld capability → the definitions that declared it (ADR-0029). Emitted commented. */
-  withheldCapabilities: Map<Capability, string[]>;
-  /** `workspace:<id>` this project could route to (ADR-0035). Always commented — `init` does not choose. */
-  routableWorkspaces: Capability[];
-  grantEnvPath: string;
-  grantEnvContent: string;
-  /** Capabilities a declared ceiling names that pi 0.84.1 has no tool for — a caution, not a verdict. */
-  cautions: string[];
-}
-
-const PLACEHOLDER = [
-  "# pi-daddy: this skill declares no `allowed-tools`, so it CANNOT be spawned as a governed sub-agent —",
-  "# an undeclared capability set is treated as NONE, never as everything. Decide what it needs, then",
-  "# uncomment and complete the line below. pi-daddy does not choose this for you: the capability set is",
-  "# the thing you are meant to review and commit.",
-  "# pi 0.84.1's tools: " + PI_BUILTIN_TOOLS.join(", ") + ".",
-  "# allowed-tools: <list the tools this skill needs, e.g. Read, Grep>",
-];
-
-/**
- * A copied file that is unspawnable for a reason an operator cannot see by reading it.
- *
- * The undeclared case got four explanatory lines from the start; a pattern-carrying one got nothing, so
- * opening `.pi/skills/git-ops/SKILL.md` to find out why it will not spawn showed a perfectly ordinary file.
- * Same argument, opposite treatment — now the same treatment.
- */
-const patternNote = (patterns: string[]) => [
-  "# pi-daddy: this skill CANNOT be spawned as a governed sub-agent. Its `allowed-tools` restricts a tool",
-  `# with a pattern (${patterns.join(", ")}), and pi's --tools matches whole tool names only — granting the`,
-  "# bare tool would widen the declaration and dropping it would silently narrow, so neither is done.",
-  "# Replace the pattern with whole tool names to make it spawnable.",
-];
-
-/**
- * The file to write for one skill: verbatim when it declares a usable ceiling, plus a commented note when
- * it does not.
- *
- * Inserted at the END of the frontmatter block, so the rest of the file — including its own key order and
- * its body — is byte-identical to the package's. A `#` line is a YAML comment and this package's
- * frontmatter reader skips it, so an undeclared copy is still *undeclared*: not spawnable until a human
- * edits it, which is the whole point.
- */
-export function withPlaceholder(text: string, declared: boolean, note: string[] = PLACEHOLDER): string {
-  if (declared) return text;
-  const match = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(text);
-  // No frontmatter at all means `parseSkillDefinition` returned null and this skill was never discovered;
-  // inventing one here would invent a file shape. Left exactly as it is.
-  if (!match) return text;
-  const [full, opening, body, close] = match;
-  const eol = close.startsWith("\r\n") ? "\r\n" : "\n";
-  return opening + body + eol + note.join(eol) + close + text.slice(full.length);
-}
-
-/** `tool:` ids pi 0.84.1 has no tool for. `delegate` is this package's own, hence the exemption. */
-function unknownToolIds(capabilities: Capability[]): Capability[] {
-  const builtins = new Set<string>(PI_BUILTIN_TOOLS);
-  return capabilities.filter(
-    (c) => c.startsWith("tool:") && c !== ALWAYS_LIVE && !builtins.has(c.slice("tool:".length)),
-  );
-}
-
-/**
- * Decide what `init` would write. Pure: no filesystem, no npm, no decisions taken on the operator's behalf.
- *
- * The grant is **the read-only part** of what the copied skills declare, plus one `agent:` id per definition
- * that can actually run within it, plus `tool:delegate` — without which the session registers no delegation
- * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
- * away (ADR-0029).
- */
-export function planInit(
-  packages: SkillPackage[],
-  cwd: string,
-  /**
-   * Ids from the operator's workspace registry, when one is configured — read by the CALLER, because
-   * `planInit` is pure and stays that way.
-   *
-   * ADR-0035 made routing a capability and said `init` "scaffolds the registered ids so the common path is a
-   * one-line grant edit". It did not: `init` had never heard of the registry, so the ADR's own stated
-   * migration path for a breaking change did not exist. These are emitted **commented**, never live —
-   * offering the ids while refusing to choose among them is exactly ADR-0028's position.
-   */
-  registeredWorkspaceIds: readonly string[] = [],
-): InitPlan {
-  const skills: PlannedSkill[] = [];
-  const collisions: string[] = [];
-  const seen = new Set<string>();
-
-  for (const pkg of packages) {
-    for (const skill of pkg.skills) {
-      const name = skill.definition.name;
-      if (seen.has(name)) {
-        collisions.push(`${name} (also in ${pkg.name}@${pkg.version}, not written)`);
-        continue;
-      }
-      seen.add(name);
-
-      const ceiling = ceilingForDefinition(skill.definition);
-      const notes: string[] = [];
-      let withheld: WithholdReason | null = null;
-      let note = PLACEHOLDER;
-      if (ceiling.undeclared) withheld = "undeclared";
-      else if (ceiling.patterns.length > 0) {
-        withheld = "pattern";
-        note = patternNote(ceiling.patterns);
-        notes.push(
-          `declares ${ceiling.patterns.join(", ")} — pi's --tools matches whole tool names only, so a ` +
-            `sub-tool pattern is refused rather than reinterpreted (granting the bare tool would widen it)`,
-        );
-      }
-
-      skills.push({
-        name,
-        from: `${pkg.name}@${pkg.version}`,
-        sourcePath: skill.path,
-        targetPath: skill.referenced ? skill.path : join(cwd, ".pi", "skills", name, "SKILL.md"),
-        referenced: skill.referenced,
-        content: withPlaceholder(skill.text, withheld === null, note),
-        ceiling: ceiling.capabilities,
-        withheld,
-        notes,
-      });
-    }
-  }
-
-  // ADR-0029: split what the declared ceilings ask for into what `init` grants live and what it comments.
-  const declared = skills.filter((s) => s.withheld === null);
-  const withheldCapabilities = new Map<Capability, string[]>();
-  for (const skill of declared) {
-    for (const capability of skill.ceiling) {
-      if (isLiveByDefault(capability)) continue;
-      // A routing destination is withheld but does NOT belong in this map, and the difference is not
-      // cosmetic. This map drives two things: the "WITHHELD BY DEFAULT — these can change your machine"
-      // block, and `/grants init`'s dialog. Review found a `workspace:` id reaching both — described to the
-      // operator with `tool:bash`'s rationale (routing does not change your machine, and unlike `bash` it
-      // *is* gateable), and then granted **live and persisted** on one "Yes", off a third-party package's
-      // declaration. That is the rule `grant-env.ts` states — "does not become live because a package asked
-      // for it" — honoured by the rendered file and broken by the dialog beside it: two surfaces of one
-      // command disagreeing, which is R-28's shape inside the fix for R-28.
-      //
-      // Which worktree a child starts in is not derivable from a declaration (ADR-0028), so `init` lists
-      // routing and never grants it. `routableWorkspaces` below is where these go; the definition that
-      // declared one still loses its live `agent:` id via the `needs-withheld` pass, so nothing becomes
-      // spawnable behind the operator's back either.
-      if (capability.startsWith("workspace:")) continue;
-      withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
-    }
-  }
-
-  // A definition needing a withheld capability does not get a live `agent:` id either: authorising it to run
-  // and then refusing it at spawn time is a worse answer than not authorising it, and it would put an
-  // `agent:` id in the grant whose definition cannot work — the shape ADR-0028 rule 3 already refuses.
-  for (const skill of declared) {
-    if (skill.ceiling.some((c) => !isLiveByDefault(c))) skill.withheld = "needs-withheld";
-  }
-
-  const authorised = skills.filter((s) => s.withheld === null);
-  const written = new Set(authorised.map((s) => s.name));
-  // `agent:<other>` in a ceiling is legitimate — it is how a delegator learns which definitions IT may
-  // spawn — but a name `init` did not write here would authorise a file from another skill root that the
-  // operator is not reviewing, including `~/.pi/agent/skills`, which other tools install into. Reported,
-  // never granted: the same objection ADR-0028 rule 3 makes to authorising an undeclared skill.
-  const crossReferences: { from: string; capability: Capability }[] = [];
-  const live = new Set<Capability>([ALWAYS_LIVE]);
-  for (const skill of authorised) {
-    live.add(agentCapability(skill.name));
-    for (const capability of skill.ceiling) {
-      if (capability.startsWith("agent:") && !written.has(capability.slice("agent:".length))) {
-        crossReferences.push({ from: skill.name, capability });
-        continue;
-      }
-      live.add(capability);
-    }
-  }
-  const grant = [...live].sort();
-
-  const cautions = authorised.flatMap((s) =>
-    unknownToolIds(s.ceiling).map(
-      (c) =>
-        `${s.name} declares ${c}, which pi 0.84.1 has no tool for — unless an extension provides it, ` +
-        `spawning ${s.name} is refused as an unknown capability`,
-    ),
-  );
-
-  // R-78's structural backstop. Throws rather than rendering something a shell could read as more than a
-  // value, so a gap in the per-entry whitelist costs a refusal instead of an injection.
-  assertGrantIsWritable(grant);
-
-  const describe: Record<WithholdReason, (s: PlannedSkill) => string> = {
-    undeclared: (s) => "declares no `allowed-tools` — fill it in, then add `agent:" + s.name + "` below",
-    pattern: (s) => s.notes.join("; "),
-    "needs-withheld": (s) =>
-      `needs ${s.ceiling.filter((c) => !isLiveByDefault(c)).join(", ")}, withheld by default — see below`,
-  };
-
-  const grantEnvSkills: GrantEnvSkill[] = skills.map((s) => ({
-    name: s.name,
-    ceiling: s.ceiling,
-    ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
-  }));
-
-  // Registry ids the operator could route to, plus any a copied definition actually declares — a package
-  // naming `workspace:prod` is evidence that id matters here, and it must still be uncommented by hand.
-  const declaredWorkspaces = skills.flatMap((s) => s.ceiling.filter((c) => c.startsWith("workspace:")));
-  const routableWorkspaces = [
-    ...new Set([...registeredWorkspaceIds.map(workspaceCapability), ...declaredWorkspaces]),
-  ].sort();
-
-  return {
-    skills,
-    collisions,
-    grant,
-    withheldCapabilities,
-    routableWorkspaces,
-    grantEnvPath: join(cwd, ".pi", "grants.env"),
-    grantEnvContent: renderGrantEnv({
-      skills: grantEnvSkills,
-      live: grant,
-      withheld: withheldCapabilities,
-      withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
-      crossReferences,
-      cautions,
-      routableWorkspaces,
-    }),
-    cautions,
-  };
-}
-
-export interface InitOutcome {
-  written: string[];
-  /** Present already, so left alone. `init` never silently overwrites an edited ceiling. */
-  kept: string[];
-  failed: { path: string; error: string }[];
-}
-
-/**
- * Create a file only if nothing is there, and **never through a symlink**.
- *
- * Both properties come from `O_CREAT|O_EXCL` (`flag: "wx"`), and both were defects in the first version
- * (R-79). It probed for existence with `readFile` and then called `writeFile`:
- *
- *  - `readFile` conflates *unreadable* with *absent*, so an operator's `SKILL.md` with restrictive
- *    permissions was reported `wrote` and their narrowed `allowed-tools: Read` was replaced by the
- *    package's wider one — **without `--force`**, falsifying this package's own documented "Kept" rule.
- *    A FIFO at the target path hung the probe forever, with no timeout anywhere in the path.
- *  - `writeFile` follows symlinks, so a dangling symlink at a target path created the file at the link's
- *    destination, outside the project, while reporting an in-project path. That is **B-I6**, which
- *    `approval-store.ts` already fixed for the approval store under ADR-0014 — a new writer in the same
- *    package reintroducing a defect the package documents as closed, and whose comment says in so many
- *    words *"never through a symlink"*.
- *
- * `wx` fails with `EEXIST` on anything at the path, including a dangling symlink, so there is no probe, no
- * race between the probe and the write, and no way to write through a link.
- */
-async function createUnlessPresent(path: string, content: string, outcome: InitOutcome): Promise<void> {
-  try {
-    await mkdir(join(path, ".."), { recursive: true });
-    const handle = await open(path, "wx");
-    await runWithFinalizers(
-      () => handle.writeFile(content, "utf8"),
-      [{ label: "new-file handle cleanup failed", run: () => handle.close() }],
-    );
-    outcome.written.push(path);
-  } catch (error) {
-    if ((error as { code?: string }).code === "EEXIST") outcome.kept.push(path);
-    else outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
-  }
-}
-
-/** Replace a file, unlinking first so a symlink is REPLACED rather than written through. */
-async function replace(path: string, content: string, outcome: InitOutcome): Promise<void> {
-  try {
-    await mkdir(join(path, ".."), { recursive: true });
-    // `rm` unlinks the LINK, never its target — which is exactly the semantics `--force` should have.
-    await rm(path, { force: true });
-    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
-    outcome.written.push(path);
-  } catch (error) {
-    outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
-  }
-}
-
-/**
- * Apply a plan.
- *
- * **Existing files are kept, not overwritten**, and that default is load-bearing rather than polite: the
- * edit an operator makes to one of these files IS the capability decision, and the second run of a
- * scaffolding command is exactly when it would be destroyed.
- *
- * **`--force` never regenerates `.pi/grants.env`** (R-79). It rewrites the definition copies, which is the
- * documented re-sync path for R-74 — but the grant file is the *reviewed artifact*, and an operator who had
- * deleted `agent:build` and added a ledger path would have had both silently restored to generated defaults
- * by a command whose usage text mentions only `allowed-tools`. Deleting the file is how to regenerate it,
- * and that is not something anyone does by accident.
- */
-export async function applyInit(plan: InitPlan, options: { force?: boolean } = {}): Promise<InitOutcome> {
-  const outcome: InitOutcome = { written: [], kept: [], failed: [] };
-  const projectPi = join(plan.grantEnvPath, "..");
-  try {
-    // A new project gets a private control directory. Existing operator/Pi state is never chmodded or reused.
-    await mkdir(projectPi, { mode: 0o700 });
-    const created = await lstat(projectPi);
-    if (!created.isDirectory() || created.isSymbolicLink()) throw Error("private .pi directory creation failed");
-  } catch (error) {
-    if ((error as { code?: string }).code !== "EEXIST") {
-      outcome.failed.push({ path: projectPi, error: error instanceof Error ? error.message : String(error) });
-      return outcome;
-    }
-    const existing = await lstat(projectPi);
-    if (existing.isSymbolicLink() || !existing.isDirectory()) {
-      outcome.failed.push({ path: projectPi, error: "existing .pi state is not a directory; it was not followed or changed" });
-      return outcome;
-    }
-  }
-  const force = options.force === true;
-  for (const skill of plan.skills) {
-    if (skill.referenced) continue;
-    if (force) await replace(skill.targetPath, skill.content, outcome);
-    else await createUnlessPresent(skill.targetPath, skill.content, outcome);
-  }
-  await createUnlessPresent(plan.grantEnvPath, plan.grantEnvContent, outcome);
-  return outcome;
-}

package/src/intent-application.ts

@@ -1,91 +0,0 @@
-import { lstat, realpath } from "node:fs/promises";
-import { dirname, isAbsolute, resolve } from "node:path";
-import { readDailySnapshot } from "./daily-view-input.ts";
-import { workDestination } from "./work-ledger-destination.ts";
-import { appendWorkLedgerEventOnce, buildWorkRevisionEvent, buildWorkSnapshotEvent, parseWorkLedgerText, type WorkFrozen, type WorkRevision } from "./work-ledger.ts";
-import { resolveWorkSnapshotText } from "./work-ledger-snapshot.ts";
-import { controlShape } from "./dispatch-control.ts";
-import { freezeWork } from "./work-ledger-json.ts";
-import { intentKey, intentSelection, intentPriorities, type WorkIntentBinding, type IntentRequest, type IntentState, type IntentSelection, type IntentPriority } from "./intent-control.ts";
-const ref = (r: WorkFrozen<WorkRevision>) => ({ kind: r.kind, id: r.id, revision: r.revision, digest: r.digest });
-const entity = (r: { kind: string; id: string } | null) => r ? `${r.kind}:${r.id}` : null;
-const allowedIntentPath=(path:string)=>!path.split("/").includes(".pi")||path.endsWith("/.pi/work.jsonl");
-export function workIntentBinding(input: WorkIntentBinding): WorkIntentBinding {
-  controlShape(input, ["version", "path", "device", "inode", "grantLedgerPath", "selection", "priorities"]);
-  if (input.version !== "1.0" || typeof input.path !== "string" || input.path.length > 1024 || !isAbsolute(input.path) || resolve(input.path) !== input.path || !allowedIntentPath(input.path) ||
-    ![input.device, input.inode].every(x => typeof x === "string" && /^\d+$/.test(x)) || !(input.grantLedgerPath === null || typeof input.grantLedgerPath === "string" && input.grantLedgerPath.length <= 1024 && isAbsolute(input.grantLedgerPath))) throw new TypeError("invalid pinned work binding");
-  return JSON.parse(intentKey({ ...input, selection: intentSelection(input.selection), priorities: intentPriorities(input.priorities) }));
-}
-export async function readIntentWork(input: WorkFrozen<WorkIntentBinding>): Promise<string> {
-  const check = async () => {
-    const st = await lstat(input.path, { bigint: true });
-    if (!st.isFile() || st.nlink !== 1n || st.uid !== BigInt(process.getuid!()) || (st.mode & 0o077n) || String(st.dev) !== input.device || String(st.ino) !== input.inode || await realpath(input.path) !== input.path) throw new Error("work binding changed");
-  };
-  await check(); const bytes = await readDailySnapshot(input.path, 16 * 1024 * 1024); await check();
-  if (bytes.status !== "read") throw new Error("required work snapshot unavailable");
-  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.bytes);
-  if (!text.endsWith("\n") || !parseWorkLedgerText(text).complete) throw new Error("incomplete work ledger; no repair");
-  return text;
-}
-export function resolveIntent(text: string, selection: WorkFrozen<IntentSelection>, priorities: WorkFrozen<IntentPriority[]>): ReturnType<typeof resolveWorkSnapshotText> {
-  const result = resolveWorkSnapshotText(text, selection);
-  if (result.scopeState !== "valid" || !result.scope || !result.snapshot || result.revisions.length > 64) throw new Error("unresolved authoritative work selection");
-  const wanted = result.snapshot.bindings.map(b => intentKey(b.obligation)).sort();
-  if (intentKey(wanted) !== intentKey(priorities.map(p => intentKey(p.obligation)).sort())) throw new Error("priority policy must name exactly the selected obligations");
-  return result;
-}
-/** Actual owned bytes establish the physical binding; caller supplies the exact initial selection. */
-export async function bindWorkIntent(input: { path: string; grantLedgerPath: string | null; selection: IntentSelection; priorities: IntentPriority[] }): Promise<WorkFrozen<WorkIntentBinding>> {
-  controlShape(input, ["path", "grantLedgerPath", "selection", "priorities"]);
-  const selection = intentSelection(input.selection), priorities = intentPriorities(input.priorities), path = input.path, grantLedgerPath = input.grantLedgerPath;
-  if (typeof path !== "string" || !isAbsolute(path) || !allowedIntentPath(path)) throw new TypeError("explicit work path required");
-  await workDestination(path, grantLedgerPath);
-  const parent = await lstat(dirname(path), { bigint: true });
-  if (!parent.isDirectory() || (parent.mode & 0o077n) || parent.uid !== BigInt(process.getuid!())) throw new Error("owner-private work parent required");
-  const st = await lstat(path, { bigint: true });
-  const binding = workIntentBinding({ version: "1.0", path, grantLedgerPath, device: String(st.dev), inode: String(st.ino), selection, priorities });
-  resolveIntent(await readIntentWork(binding), selection, priorities); return freezeWork(binding);
-}
-/** No authority callback: validate concrete P01 effects and prevent permission/owner/policy expansion. */
-export async function validateIntentApplication(binding: WorkFrozen<WorkIntentBinding>, state: IntentState, request: WorkFrozen<IntentRequest>): Promise<void> {
-  const text = await readIntentWork(binding), current = resolveIntent(text, state.selection, state.priorities);
-  const existing = parseWorkLedgerText(text).events;
-  const missing = request.events.filter(e => {
-    const sameId = existing.filter(old => old.eventId === e.eventId);
-    if (sameId.some(old => old.digest !== e.digest)) throw new Error("proposed event identity conflicts with retained work");
-    return sameId.length === 0;
-  });
-  const candidate = text + missing.map(e => intentKey(e) + "\n").join("");
-  const next = resolveIntent(candidate, request.selection, request.priorities);
-  if (request.action === "reprioritize" && intentKey(request.selection) !== intentKey(state.selection)) throw new Error("priority is not scope selection");
-  if (request.action !== "reprioritize" && intentKey(request.selection) === intentKey(state.selection)) throw new Error("a different exact recorded selection is required");
-  const old = [current.scope!, ...current.revisions], after = [next.scope!, ...next.revisions];
-  if (intentKey(old.map(entity).sort()) !== intentKey(after.map(entity).sort())) throw new Error("entity expansion/removal is outside this bounded adapter");
-  for (const r of after) {
-    const prior = old.find(p => entity(p) === entity(r))!;
-    if (r.ownerId !== prior.ownerId || r.scopeId !== prior.scopeId || r.permittedEffects.some(e => !prior.permittedEffects.includes(e)) || intentKey(r.policy) !== intentKey(prior.policy) ||
-      entity(r.parent) !== entity(prior.parent) || intentKey(r.dependencies.map(entity).sort()) !== intentKey(prior.dependencies.map(entity).sort()) ||
-      r.kind === "policy" && r.digest !== prior.digest) throw new Error("owner, policy, topology or permission expansion refused");
-    if (["revise-scope", "revise-selection"].includes(request.action) && r.digest !== prior.digest && (r.revision !== prior.revision + 1 || intentKey(r.predecessor) !== intentKey(ref(prior)))) throw new Error("exact successor required");
-  }
-  if (request.action === "revise-selection" && !after.some(r => r.digest !== old.find(p => entity(p) === entity(r))!.digest)) throw new Error("at least one exact successor revision required");
-  if (request.action === "revise-scope" && (next.scope!.revision !== current.scope!.revision + 1 || intentKey(next.scope!.predecessor) !== intentKey(ref(current.scope!)))) throw new Error("scope revision is not dispatch revision");
-  for (const e of request.events) {
-    // Rebuild through the actual P01 builders, not an alternate event/hash encoder.
-    if (e.event === "work_revision") {
-      const { digest: _digest, ...revision } = e.payload.revision;
-      if (!after.some(r => intentKey(ref(r)) === intentKey(ref(e.payload.revision))) || intentKey(buildWorkRevisionEvent({ eventId: e.eventId, now: new Date(e.ts), revision: JSON.parse(intentKey(revision)) })) !== intentKey(e)) throw new Error("unselected or noncanonical revision proposal");
-    } else if (e.event === "work_snapshot") {
-      const { digest: _digest, ...snapshot } = e.payload.snapshot;
-      if (e.eventId !== request.selection.event.eventId || e.digest !== request.selection.event.digest || intentKey(buildWorkSnapshotEvent({ eventId: e.eventId, now: new Date(e.ts), snapshot: JSON.parse(intentKey(snapshot)) })) !== intentKey(e)) throw new Error("unselected snapshot proposal");
-    }
-  }
-}
-export async function applyIntentApplication(binding: WorkFrozen<WorkIntentBinding>, state: IntentState, request: WorkFrozen<IntentRequest>): Promise<void> {
-  await validateIntentApplication(binding, state, request);
-  for (const event of request.events) {
-    await readIntentWork(binding);
-    await appendWorkLedgerEventOnce({ path: binding.path, grantLedgerPath: binding.grantLedgerPath }, event);
-  }
-  resolveIntent(await readIntentWork(binding), request.selection, request.priorities);
-}

package/src/intent-control.ts

@@ -1,107 +0,0 @@
-import { createHash } from "node:crypto";
-import { canonicalWorkJson, copyWorkJson, freezeWork, parseWorkJson } from "./work-ledger-json.ts";
-import { parseWorkLedgerText, type WorkFrozen, type WorkProjectionContext, type RevisionRef, type WorkRevisionEvent, type WorkSnapshotEvent } from "./work-ledger.ts";
-import { validateWorkSelection } from "./work-ledger-validation.ts";
-import { controlShape } from "./dispatch-control.ts";
-export type IntentSelection = NonNullable<WorkProjectionContext["selectedSnapshot"]>;
-export interface IntentPriority { obligation: RevisionRef; rank: number }
-export interface WorkIntentBinding {
-  version: "1.0"; path: string; device: string; inode: string; grantLedgerPath: string | null;
-  selection: IntentSelection; priorities: IntentPriority[];
-}
-export interface IntentRequest {
-  version: "intent-request-v1" | "intent-request-v2"; requestId: string; bindingDigest: string; expectedRevision: number;
-  expectedSelection: IntentSelection; action: "revise-scope" | "reprioritize" | "select-alternative" | "revise-selection";
-  events: (WorkRevisionEvent | WorkSnapshotEvent)[]; selection: IntentSelection; priorities: IntentPriority[];
-}
-export interface IntentReceipt {
-  requestId: string; digest: string; expectedRevision: number; expectedSelection: IntentSelection;
-  action: IntentRequest["action"]; selection: IntentSelection; priorities: IntentPriority[];
-  events: { eventId: string; digest: string }[];
-  decision: "approved" | "authority-unavailable" | "stale" | "busy";
-  application: "pending-or-unknown" | "applied" | "not-applied";
-  outcome: "pending-or-unknown" | "selection-applied" | "priority-applied" | "refused";
-  resultSelection: IntentSelection | null;
-}
-export interface IntentState { revision: number; selection: IntentSelection; priorities: IntentPriority[]; records: IntentReceipt[] }
-export interface IntentAdmission { selection: IntentSelection; revision: number; obligation: RevisionRef }
-export type IntentSnapshot = WorkFrozen<IntentState & { version: "intent-controller-snapshot-v1"; bindingDigest: string;
-  admission: "blocked-pending" | "intent-ready"; acceptance: "not-assessed"; freshness: "snapshot-unknown" }>;
-export const intentKey = (value: unknown) => canonicalWorkJson(copyWorkJson(value));
-const hash = (value: unknown) => createHash("sha256").update(intentKey(value)).digest("hex");
-const id = (x: unknown) => typeof x === "string" && /^[a-zA-Z0-9:_-]{1,128}$/.test(x);
-const hex = (x: unknown) => typeof x === "string" && /^[a-f0-9]{64}$/.test(x);
-export function intentPriorities(input: unknown): IntentPriority[] {
-  const result = copyWorkJson(input) as unknown as IntentPriority[];
-  if (!Array.isArray(result) || result.length > 32) throw new TypeError("bounded explicit priorities required");
-  for (const p of result) {
-    controlShape(p, ["obligation", "rank"]); controlShape(p.obligation, ["kind", "id", "revision", "digest"]);
-    if (p.obligation.kind !== "obligation" || !id(p.obligation.id) || !hex(p.obligation.digest) || !Number.isSafeInteger(p.obligation.revision) || p.obligation.revision < 1 ||
-      !Number.isSafeInteger(p.rank) || p.rank < 0 || p.rank > 127) throw new TypeError("invalid priority");
-  }
-  if (new Set(result.map(p => intentKey(p.obligation))).size !== result.length) throw new TypeError("duplicate priority obligation");
-  return result.sort((a, b) => a.rank - b.rank || (intentKey(a.obligation) < intentKey(b.obligation) ? -1 : 1));
-}
-export function intentSelection(value: unknown): IntentSelection {
-  const copied = copyWorkJson(value); validateWorkSelection(copied);
-  if (copied === null) throw new TypeError("exact intent selection required");
-  return copied as unknown as IntentSelection;
-}
-export function intentRequest(input: IntentRequest): WorkFrozen<IntentRequest> {
-  const r = copyWorkJson(input) as unknown as IntentRequest;
-  controlShape(r, ["version", "requestId", "bindingDigest", "expectedRevision", "expectedSelection", "action", "events", "selection", "priorities"]);
-  if ((r.action === "revise-selection" ? r.version !== "intent-request-v2" : r.version !== "intent-request-v1") || !id(r.requestId) || !hex(r.bindingDigest) || !Number.isSafeInteger(r.expectedRevision) || r.expectedRevision < 0 || r.expectedRevision > 32 ||
-    !["revise-scope", "reprioritize", "select-alternative", "revise-selection"].includes(r.action) || !Array.isArray(r.events) || r.events.length > 16 || Buffer.byteLength(intentKey(r)) > 48 * 1024) throw new TypeError("invalid bounded intent request");
-  const parsed = parseWorkLedgerText(r.events.map(e => intentKey(e)).join("\n"));
-  if (!parsed.complete || parsed.events.some(e => !id(e.eventId) || !["work_revision", "work_snapshot"].includes(e.event)) || new Set(parsed.events.map(e => e.eventId)).size !== parsed.events.length ||
-    (!["revise-scope", "revise-selection"].includes(r.action) && r.events.length)) throw new TypeError("only strict revision/snapshot proposals may be appended");
-  return freezeWork({ ...r, expectedSelection: intentSelection(r.expectedSelection), selection: intentSelection(r.selection), priorities: intentPriorities(r.priorities) });
-}
-export const parseIntentRequest = (text: string) => intentRequest(parseWorkJson(text) as unknown as IntentRequest);
-export const intentRequestDigest = (input: WorkFrozen<IntentRequest>) => hash(intentRequest(input as IntentRequest));
-export function intentReceipt(input: WorkFrozen<IntentRequest>, decision: IntentReceipt["decision"]): IntentReceipt {
-  return JSON.parse(intentKey({ requestId: input.requestId, digest: intentRequestDigest(input), expectedRevision: input.expectedRevision,
-    expectedSelection: input.expectedSelection, action: input.action, selection: input.selection, priorities: input.priorities,
-    events: input.events.map(e => ({ eventId: e.eventId, digest: e.digest })), decision,
-    application: decision === "approved" ? "pending-or-unknown" : "not-applied",
-    outcome: decision === "approved" ? "pending-or-unknown" : "refused", resultSelection: null }));
-}
-export function matchesIntentReceipt(receipt: IntentReceipt, request: WorkFrozen<IntentRequest>): boolean {
-  const expected = intentReceipt(request, receipt.decision);
-  if (receipt.application === "applied") {
-    expected.application = "applied"; expected.resultSelection = JSON.parse(intentKey(request.selection));
-    expected.outcome = request.action === "reprioritize" ? "priority-applied" : "selection-applied";
-  }
-  return intentKey(receipt) === intentKey(expected);
-}
-export function intentDecision(state: IntentState, request: Pick<IntentRequest, "expectedRevision" | "expectedSelection">, authorized: boolean, dispatchBusy: boolean): IntentReceipt["decision"] {
-  if (!authorized) return "authority-unavailable";
-  if (request.expectedRevision !== state.revision || intentKey(request.expectedSelection) !== intentKey(state.selection)) return "stale";
-  if (dispatchBusy || state.records.some(r => r.application === "pending-or-unknown")) return "busy";
-  return "approved";
-}
-export function replayIntent(state: IntentState, event: Record<string, unknown>, active: number, dispatchBusy: boolean): void {
-  if (event.type === "intent-request") {
-    controlShape(event, ["type", "receipt"]);
-    const r = event.receipt as IntentReceipt;
-    controlShape(r, ["requestId", "digest", "expectedRevision", "expectedSelection", "action", "selection", "priorities", "events", "decision", "application", "outcome", "resultSelection"]);
-    intentSelection(r.expectedSelection); intentSelection(r.selection); intentPriorities(r.priorities);
-    if (!id(r.requestId) || !hex(r.digest) || !Number.isSafeInteger(r.expectedRevision) || r.expectedRevision < 0 || !["revise-scope", "reprioritize", "select-alternative", "revise-selection"].includes(r.action) ||
-      !Array.isArray(r.events) || r.events.length > 16 || state.records.length >= 32 || state.records.some(p => p.requestId === r.requestId) ||
-      intentDecision(state, r, r.decision !== "authority-unavailable", dispatchBusy) !== r.decision || r.application !== (r.decision === "approved" ? "pending-or-unknown" : "not-applied") ||
-      r.outcome !== (r.decision === "approved" ? "pending-or-unknown" : "refused") || r.resultSelection !== null) throw new Error("invalid intent decision sequence");
-    for (const ref of r.events) { controlShape(ref, ["eventId", "digest"]); if (!id(ref.eventId) || !hex(ref.digest)) throw new Error("invalid event reference"); }
-    state.records.push(r); if (r.decision === "approved") state.revision++;
-  } else {
-    controlShape(event, ["type", "requestId"]);
-    const r = state.records.find(r => r.requestId === event.requestId);
-    if (event.type !== "intent-apply" || !r || r.application !== "pending-or-unknown" || active || dispatchBusy) throw new Error("invalid intent application boundary");
-    state.selection = r.selection; state.priorities = r.priorities; r.application = "applied";
-    r.outcome = r.action === "reprioritize" ? "priority-applied" : "selection-applied"; r.resultSelection = r.selection;
-  }
-}
-export function intentSnapshot(state: IntentState, bindingDigest: string): IntentSnapshot {
-  return freezeWork({ version: "intent-controller-snapshot-v1", bindingDigest, ...state,
-    admission: state.records.some(r => r.application === "pending-or-unknown") ? "blocked-pending" : "intent-ready",
-    acceptance: "not-assessed", freshness: "snapshot-unknown" });
-}