babavoss 0.0.0-stage → 0.0.2

package/src/promptware/sync.ts

@@ -0,0 +1,437 @@
+// Compiled promptware onto disk, owning only what it wrote. The state file
+// records the sha256 of every output the compiler last wrote, and of its
+// part of a shared file; comparing it with the files gives each output a
+// status:
+//
+//   current   the file holds what is wanted
+//   stale     owned and differs from what is wanted, or owned and no longer wanted: rewritten or removed
+//   missing   wanted and absent: written
+//   held      owned but edited by hand, or not a regular file: never touched
+//   foreign   present and never written by the compiler: never touched
+//
+// A shared file, .mcp.json or .claude/settings.json or .codex/config.toml,
+// is voss's only for its part: merged in, taken out when no longer wanted,
+// and the whole file held when the part was edited by hand.
+//
+// The files are reached through `Files`: Bun's on the shell's offline path
+// (disk.ts), the effect's ctx.fs inside a baba. plan() writes nothing;
+// apply() refuses the whole plan when any path no longer has the hash it
+// had when the plan was made.
+import type { Fs } from "../kernel/context.ts";
+import type { Compiled, Merge, Outputs } from "./compile.ts";
+
+export type Status = "current" | "stale" | "missing" | "held" | "foreign";
+export type Action = "write" | "remove";
+
+/** Relative to the project root. */
+export const statePath = ".baba/.voss/promptware.json";
+
+/** What the compiler last wrote: output path to the hash of its text, or of its part of a shared file, and those parts. */
+export interface Written {
+  written: Record<string, string>;
+  parts: Record<string, Merge>;
+  /** No record was found: the compiler's first run in this checkout. Never written to disk. */
+  first?: boolean;
+}
+
+export type Seen = { kind: "absent" } | { kind: "file"; text: string } | { kind: "blocked"; reason: string };
+
+/** The files a plan reads and an apply writes, by path relative to the project. */
+export interface Files {
+  look(path: string): Promise<Seen>;
+  write(path: string, text: string): Promise<void>;
+  remove(path: string): Promise<void>;
+  /** Removes a directory only when it is empty. */
+  prune(path: string): Promise<void>;
+}
+
+export interface Entry {
+  path: string;
+  status: Status;
+  /** What apply() does here; null leaves the path alone. */
+  action: Action | null;
+  /** The file's hash when the plan was made, null when absent: apply() refuses when it changed. */
+  before: string | null;
+  /** Why a path is held or foreign. */
+  reason?: string;
+}
+
+export interface Plan {
+  root: string;
+  io: Files;
+  entries: Entry[];
+  /** What each path written should hold: a whole file, or a shared file with the part merged. */
+  wanted: Outputs;
+  previous: Written;
+  /** The state once every change is applied. */
+  next: Written;
+}
+
+/** What a CLI prints: a plan, or a plan applied. No file contents. */
+export interface Report {
+  root: string;
+  outputs: { path: string; status: Status; action: Action | null; reason?: string }[];
+  written: string[];
+  removed: string[];
+  held: string[];
+  foreign: string[];
+}
+
+export class ChangedError extends Error {
+  constructor(readonly paths: string[]) {
+    super(`changed since the plan was made, nothing written: ${paths.join(", ")}`);
+  }
+}
+
+export function hash(text: string): string {
+  return new Bun.CryptoHasher("sha256").update(text).digest("hex");
+}
+
+const byPath = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+function checkPath(path: string): void {
+  if (!path || path.startsWith("/") || path.split("/").some((p) => p === "" || p === "." || p === ".."))
+    throw new Error(`output path ${JSON.stringify(path)} is not a plain path under the project`);
+}
+
+async function readWritten(io: Files): Promise<Written> {
+  const seen = await io.look(statePath);
+  // No record at all: the compiler's first run in this checkout. A fresh worktree carries the repository's generated files, which another checkout's compiler wrote.
+  if (seen.kind !== "file") return { written: {}, parts: {}, first: true };
+  let v: unknown;
+  try { v = JSON.parse(seen.text); } catch (e) { throw new Error(`${statePath}: ${e instanceof Error ? e.message : String(e)}`); }
+  const { written, parts } = (v ?? {}) as { written?: unknown; parts?: unknown };
+  if (typeof written !== "object" || written === null) throw new Error(`${statePath}: expected { written: { PATH: HASH } }`);
+  return { written: { ...(written as Record<string, string>) }, parts: typeof parts === "object" && parts !== null ? { ...(parts as Record<string, Merge>) } : {} };
+}
+
+const hashOf = (s: Seen) => (s.kind === "file" ? hash(s.text) : null);
+
+// ---- merges --------------------------------------------------------------
+
+type Obj = Record<string, unknown>;
+const isObj = (v: unknown): v is Obj => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** JSON with sorted keys: equal values, equal text. */
+export function stable(v: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(stable).join(",")}]`;
+  if (isObj(v)) return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(",")}}`;
+  return JSON.stringify(v) ?? "null";
+}
+
+function parseJson(text: string | null): Obj {
+  if (text === null || !text.trim()) return {};
+  let v: unknown;
+  try { v = JSON.parse(text); } catch (e) { throw new Error(`not JSON: ${e instanceof Error ? e.message : String(e)}`); }
+  if (!isObj(v)) throw new Error("not a JSON object");
+  return v;
+}
+
+const getAt = (o: Obj, at: string[]): unknown => at.reduce<unknown>((v, k) => (isObj(v) ? v[k] : undefined), o);
+
+/** The object at `at`, made when absent; throws when something else is there. */
+function parentAt(o: Obj, at: string[]): Obj {
+  let cur = o;
+  for (const k of at) {
+    if (cur[k] === undefined) cur[k] = {};
+    if (!isObj(cur[k])) throw new Error(`${at.join(".")} is not an object`);
+    cur = cur[k] as Obj;
+  }
+  return cur;
+}
+
+/** Drops the empty objects and lists left along `at` once voss's part is gone. */
+function prune(o: Obj, at: string[]): void {
+  for (let i = at.length; i > 0; i--) {
+    const parent = getAt(o, at.slice(0, i - 1));
+    const v = isObj(parent) ? parent[at[i - 1]!] : undefined;
+    if (!isObj(parent) || !((isObj(v) && Object.keys(v).length === 0) || (Array.isArray(v) && v.length === 0))) return;
+    delete parent[at[i - 1]!];
+  }
+}
+
+const tomlHeader = /^\s*\[\s*([^[\]]+?)\s*\]\s*(#.*)?$/;
+const tomlName = (n: string) => n.split(".").map((p) => p.trim().replace(/^"(.*)"$/, "$1")).join(".");
+
+/** The lines of `table` in a TOML text: from its header to the next table, trailing blank lines left out. */
+function tomlBlock(lines: string[], table: string): { start: number; end: number } | null {
+  const start = lines.findIndex((l) => { const m = tomlHeader.exec(l); return m !== null && tomlName(m[1]!) === table; });
+  if (start < 0) return null;
+  let end = start + 1;
+  while (end < lines.length && !/^\s*\[/.test(lines[end]!)) end++;
+  while (end > start + 1 && !lines[end - 1]!.trim()) end--;
+  return { start, end };
+}
+
+/** Whether a TOML text sets `table` another way: a dotted key at the top, or a key of its parent table. */
+function tomlElsewhere(text: string, table: string): boolean {
+  const lines = text.split("\n");
+  const parts = table.split(".");
+  const first = lines.findIndex((l) => /^\s*\[/.test(l));
+  const top = first < 0 ? lines : lines.slice(0, first);
+  if (top.some((l) => new RegExp(`^\\s*"?${parts[0]}"?\\s*[.=]`).test(l))) return true;
+  const parent = tomlBlock(lines, parts.slice(0, -1).join("."));
+  return parent !== null && lines.slice(parent.start + 1, parent.end).some((l) => new RegExp(`^\\s*"?${parts.at(-1)}"?\\s*[.=]`).test(l));
+}
+
+const tomlText = (m: Extract<Merge, { kind: "toml-table" }>) => `[${m.table}]\n${m.body.trim()}`;
+
+/** Voss's part of a shared file as it is now, as text to hash; null when absent. Throws for a file that does not read. */
+export function partOf(m: Merge, text: string): string | null {
+  if (m.kind === "toml-table") {
+    const lines = text.split("\n");
+    const b = tomlBlock(lines, m.table);
+    return b ? [`[${m.table}]`, ...lines.slice(b.start + 1, b.end)].join("\n").trim() : null;
+  }
+  const o = parseJson(text);
+  if (m.kind === "json-key") { const v = getAt(o, m.at); return v === undefined ? null : stable(v); }
+  const present = listsOf(m).map((l) => { const v = getAt(o, l.at); return l.values.filter((x) => Array.isArray(v) && v.some((y) => stable(y) === stable(x))); });
+  // One list hashes as its values, as it always did; several as the list of them.
+  return stable(m.kind === "json-list" ? present[0] : present);
+}
+
+/** Voss's part whole, as partOf reads it once merged. */
+export function wholePart(m: Merge): string {
+  return m.kind === "toml-table" ? tomlText(m) : stable(m.kind === "json-key" ? m.value : m.kind === "json-list" ? m.values : listsOf(m).map((l) => l.values));
+}
+
+/** The lists a list merge holds: one for the older single-list kind. */
+const listsOf = (m: Merge): { at: string[]; values: unknown[] }[] => m.kind === "json-lists" ? m.lists : m.kind === "json-list" ? [{ at: m.at, values: m.values }] : [];
+
+/**
+ * A shared file with voss's part taken out (`was`) and put in (`want`):
+ * the text to write, or null when nothing else is left in it.
+ */
+export function mergeText(text: string | null, want: Merge | undefined, was: Merge | undefined): string | null {
+  const kind = (want ?? was)!.kind;
+  if (kind === "toml-table") {
+    let lines = (text ?? "").replace(/\r\n/g, "\n").split("\n");
+    const w = want as Extract<Merge, { kind: "toml-table" }> | undefined;
+    const old = was as Extract<Merge, { kind: "toml-table" }> | undefined;
+    if (old && old.table !== w?.table) { const b = tomlBlock(lines, old.table); if (b) lines = [...lines.slice(0, b.start), ...lines.slice(b.end)]; }
+    if (w) {
+      const b = tomlBlock(lines, w.table);
+      if (b) lines = [...lines.slice(0, b.start), ...tomlText(w).split("\n"), ...lines.slice(b.end)];
+      else {
+        while (lines.length && !lines.at(-1)!.trim()) lines.pop();
+        lines = [...lines, ...(lines.length ? [""] : []), ...tomlText(w).split("\n")];
+      }
+    }
+    const out = lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return out ? out + "\n" : null;
+  }
+  const o = parseJson(text);
+  if (kind === "json-key") {
+    const w = want as Extract<Merge, { kind: "json-key" }> | undefined;
+    const old = was as Extract<Merge, { kind: "json-key" }> | undefined;
+    if (old && (!w || stable(old.at) !== stable(w.at))) {
+      const parent = getAt(o, old.at.slice(0, -1));
+      if (isObj(parent)) delete parent[old.at.at(-1)!];
+      prune(o, old.at.slice(0, -1));
+    }
+    if (w) parentAt(o, w.at.slice(0, -1))[w.at.at(-1)!] = w.value;
+  } else {
+    // Lists: each of voss's entries, by content, taken out where no longer wanted and put in where missing; others' entries stay.
+    const wanted = want ? listsOf(want) : [];
+    for (const old of was ? listsOf(was) : []) {
+      const list = getAt(o, old.at);
+      const still = wanted.find((l) => stable(l.at) === stable(old.at));
+      const keep = new Set((still?.values ?? []).map(stable));
+      if (Array.isArray(list)) {
+        const parent = getAt(o, old.at.slice(0, -1)) as Obj;
+        const gone = new Set(old.values.map(stable));
+        parent[old.at.at(-1)!] = list.filter((x) => { const k = stable(x); return !(gone.has(k) && !keep.has(k)); });
+        prune(o, old.at);
+      }
+    }
+    for (const l of wanted) {
+      const parent = parentAt(o, l.at.slice(0, -1));
+      const key = l.at.at(-1)!;
+      if (parent[key] === undefined) parent[key] = [];
+      const list = parent[key];
+      if (!Array.isArray(list)) throw new Error(`${l.at.join(".")} is not a list`);
+      const have = new Set(list.map(stable));
+      for (const v of l.values) if (!have.has(stable(v))) { list.push(v); have.add(stable(v)); }
+    }
+  }
+  return Object.keys(o).length ? JSON.stringify(o, null, 2) + "\n" : null;
+}
+
+/** Whether two texts of a shared file say the same: equal JSON for JSON, equal text for TOML. */
+function same(m: Merge, a: string, b: string): boolean {
+  if (a === b) return true;
+  if (m.kind === "toml-table") return a.trim() === b.trim();
+  try { return stable(JSON.parse(a)) === stable(JSON.parse(b)); } catch { return false; }
+}
+
+// ---- the plan ------------------------------------------------------------
+
+/** Compares what is wanted with what is on disk and what was last written. Writes nothing. */
+export async function plan(io: Files, wanted: Compiled, root = ""): Promise<Plan> {
+  for (const p of [...Object.keys(wanted.files), ...Object.keys(wanted.merges)]) checkPath(p);
+  const previous = await readWritten(io);
+  const next: Written = { written: {}, parts: {} };
+  const entries: Entry[] = [];
+  const texts: Outputs = {};
+  const paths = [...new Set([...Object.keys(wanted.files), ...Object.keys(wanted.merges), ...Object.keys(previous.written)])].sort(byPath);
+  for (const path of paths) {
+    const want = wanted.files[path];
+    const wm = wanted.merges[path];
+    const recorded = previous.written[path];
+    const was = previous.parts[path];
+    const owned = recorded !== undefined;
+    const keep = () => { if (owned && (want !== undefined || wm)) { next.written[path] = recorded; if (was && wm) next.parts[path] = was; } };
+    let seen: Seen;
+    try { checkPath(path); seen = await io.look(path); } catch { continue; } // a state entry that is not a path is forgotten
+    const now = hashOf(seen);
+    if (seen.kind === "blocked") {
+      entries.push({ path, status: "held", action: null, before: null, reason: seen.reason });
+      keep();
+      continue;
+    }
+    if (wm || (was && want === undefined)) {
+      const text = seen.kind === "file" ? seen.text : null;
+      let merged: string | null;
+      try {
+        if (text !== null) {
+          if (owned && was && hash(partOf(was, text) ?? "") !== recorded) {
+            entries.push({ path, status: "held", action: null, before: now, reason: "voss's part edited by hand" });
+            keep();
+            continue;
+          }
+          if (!owned && wm && wm.kind !== "json-list" && wm.kind !== "json-lists") {
+            const part = partOf(wm, text);
+            if ((part !== null && part !== wholePart(wm)) || (wm.kind === "toml-table" && tomlElsewhere(text, wm.table))) {
+              entries.push({ path, status: "held", action: null, before: now, reason: "an entry voss did not write" });
+              continue;
+            }
+          }
+        }
+        merged = mergeText(text, wm, owned ? was : undefined);
+      } catch (e) {
+        entries.push({ path, status: "held", action: null, before: now, reason: e instanceof Error ? e.message : String(e) });
+        keep();
+        continue;
+      }
+      if (wm) { next.written[path] = hash(wholePart(wm)); next.parts[path] = wm; }
+      if (text === null && merged === null) continue;
+      if (text !== null && merged !== null && same((wm ?? was)!, text, merged)) { entries.push({ path, status: "current", action: null, before: now }); continue; }
+      if (merged === null) { entries.push({ path, status: "stale", action: "remove", before: now }); continue; }
+      texts[path] = merged;
+      entries.push({ path, status: text === null ? "missing" : "stale", action: "write", before: now });
+      continue;
+    }
+    if (want !== undefined && seen.kind === "file" && seen.text === want) {
+      entries.push({ path, status: "current", action: null, before: now });
+      next.written[path] = now!;
+      continue;
+    }
+    if (seen.kind === "file" && !owned && previous.first && want !== undefined) {
+      // On its first run in a checkout the compiler adopts the file the repository carries at a path it writes: generated elsewhere, it is its own.
+      texts[path] = want;
+      entries.push({ path, status: "stale", action: "write", before: now, reason: "adopted on the first run in this checkout" });
+      next.written[path] = hash(want);
+      continue;
+    }
+    if (seen.kind === "file" && !owned) {
+      entries.push({ path, status: "foreign", action: null, before: now, reason: "never written by the compiler" });
+      continue;
+    }
+    if (seen.kind === "file" && now !== recorded) {
+      entries.push({ path, status: "held", action: null, before: now, reason: "edited by hand" });
+      keep();
+      continue;
+    }
+    if (want === undefined) {
+      if (seen.kind === "file") entries.push({ path, status: "stale", action: "remove", before: now });
+      continue;
+    }
+    texts[path] = want;
+    entries.push({ path, status: seen.kind === "file" ? "stale" : "missing", action: "write", before: now });
+    next.written[path] = hash(want);
+  }
+  return { root, io, entries, wanted: { ...wanted.files, ...texts }, previous, next };
+}
+
+const skillDir = /^\.[a-z]+\/skills\/[^/]+$/;
+
+/**
+ * Applies a plan: writes and removes what it says, then records the state.
+ * Refuses, writing nothing, when any path it changes no longer has the hash
+ * it had when the plan was made. When a write fails midway the state
+ * records exactly what was applied, so an applied write is not mistaken for
+ * a hand edit.
+ */
+export async function apply(p: Plan): Promise<Report> {
+  const io = p.io;
+  const changes = p.entries.filter((e) => e.action !== null);
+  const changed: string[] = [];
+  for (const e of changes) {
+    const seen = await io.look(e.path);
+    if (seen.kind === "blocked" || hashOf(seen) !== e.before) changed.push(e.path);
+  }
+  if (changed.length) throw new ChangedError(changed);
+
+  const written: string[] = [];
+  const removed: string[] = [];
+  let failure: unknown = null;
+  const next: Written = { written: { ...p.next.written }, parts: { ...p.next.parts } };
+  for (const [i, e] of changes.entries()) {
+    try {
+      if (e.action === "write") {
+        await io.write(e.path, p.wanted[e.path]!);
+        written.push(e.path);
+      } else {
+        await io.remove(e.path);
+        removed.push(e.path);
+        const dir = e.path.split("/").slice(0, -1).join("/");
+        if (skillDir.test(dir)) await io.prune(dir).catch(() => {});
+      }
+    } catch (err) {
+      failure = err;
+      for (const u of changes.slice(i)) {
+        const old = p.previous.written[u.path];
+        const part = p.previous.parts[u.path];
+        if (old !== undefined) next.written[u.path] = old; else delete next.written[u.path];
+        if (part !== undefined) next.parts[u.path] = part; else delete next.parts[u.path];
+      }
+      break;
+    }
+  }
+  const json = (st: Written) => JSON.stringify({ written: sortKeys(st.written), ...(Object.keys(st.parts).length ? { parts: sortKeys(st.parts) } : {}) }, null, 2) + "\n";
+  if (changes.length > 0 || json(p.previous) !== json(next)) await io.write(statePath, json(next));
+  if (failure) throw failure;
+  return report(p, { written, removed });
+}
+
+function sortKeys<T>(r: Record<string, T>): Record<string, T> {
+  return Object.fromEntries(Object.entries(r).sort(([a], [b]) => byPath(a, b)));
+}
+
+/** A plan, or what applying it did, as JSON a CLI prints. */
+export function report(p: Plan, done: { written: string[]; removed: string[] } = { written: [], removed: [] }): Report {
+  return {
+    root: p.root,
+    outputs: p.entries.map((e) => ({ path: e.path, status: e.status, action: e.action, ...(e.reason ? { reason: e.reason } : {}) })),
+    written: done.written,
+    removed: done.removed,
+    held: p.entries.filter((e) => e.status === "held").map((e) => e.path),
+    foreign: p.entries.filter((e) => e.status === "foreign").map((e) => e.path),
+  };
+}
+
+/** The files as an effect reaches them: through ctx.fs, which keeps every path inside the project. */
+export function contextFiles(fs: Fs): Files {
+  return {
+    async look(path) {
+      let st;
+      try { st = await fs.stat(path); } catch (e) { return { kind: "blocked", reason: e instanceof Error ? e.message : String(e) }; }
+      if (!st) return { kind: "absent" };
+      if (st.dir) return { kind: "blocked", reason: "not a regular file" };
+      return { kind: "file", text: await fs.read(path) };
+    },
+    write: (path, text) => fs.write(path, text),
+    remove: (path) => fs.remove(path),
+    async prune(path) { if ((await fs.list(path)).length === 0) await fs.remove(path); },
+  };
+}

package/src/promptware/system.ts

@@ -0,0 +1,215 @@
+// The promptware system: voss gives it to every baba. The know-how is the
+// baba's promptware, rendered into the manifest with its harness
+// declaration; this system's state is the outputs' hashes; its effects
+// compile the know-how for each harness and write the files through the
+// kernel. The system is made per baba, given the manifest of the
+// baba it joins.
+import { effect, manifestOf, resource, baba, nameOf, type Manifest, type Baba } from "../ecs/baba.ts";
+import { system, type StateOf } from "../ecs/system.ts";
+import { s } from "../kernel/schema.ts";
+import type { Prompt } from "../prompt/index.ts";
+import type { Fs } from "../kernel/context.ts";
+import type { Value } from "../ecs/state.ts";
+import maker from "../maker/system.ts";
+import { catalogOf, desktop } from "../desktop/index.ts";
+import { guide } from "../guide/index.ts";
+import { compile, harnessOf, type Merge } from "./compile.ts";
+import { apply, contextFiles, hash, plan } from "./sync.ts";
+
+const statuses = ["current", "stale", "held", "missing"] as const;
+
+const scanned = s.object({
+  title: s.nullable(s.string()),
+  outputs: s.array(s.object({ path: s.string(), hash: s.string() })),
+});
+const entry = s.object({ path: s.string(), status: s.enum(...statuses), action: s.nullable(s.enum("write", "remove")), reason: s.string(), hash: s.string() });
+const writeArgs = s.object({
+  key: s.string(),
+  apply: s.boolean(),
+  files: s.array(s.object({ path: s.string(), text: s.string() })),
+  merges: s.array(s.object({ path: s.string(), merge: s.unknown() })),
+});
+const written = s.object({ key: s.string(), applied: s.boolean(), written: s.array(s.string()), removed: s.array(s.string()), entries: s.array(entry) });
+
+/** A directory's entries, none when it is absent: asked by stat first, so an absent directory is not a failed request in the log. */
+const entries = async (fs: Fs, path: string) => ((await fs.stat(path).catch(() => null))?.dir ? fs.list(path) : []);
+
+/** Every place an output may be: the instruction files, the shared files (with those an older voss merged into, to take its part out), and the skill directories as they are now. */
+async function outputs(fs: Fs): Promise<{ path: string; hash: string }[]> {
+  const paths = ["AGENTS.md", "CLAUDE.md", ".mcp.json", ".claude/settings.json", ".codex/config.toml"];
+  for (const dir of [".claude/skills", ".agents/skills", ".codex/skills"]) for (const e of await entries(fs, dir)) if (e.dir) paths.push(`${dir}/${e.name}/SKILL.md`);
+  const out: { path: string; hash: string }[] = [];
+  for (const path of paths) {
+    const st = await fs.stat(path).catch(() => null);
+    if (st && !st.dir) out.push({ path, hash: hash(await fs.read(path)) });
+  }
+  return out;
+}
+
+async function scan(fs: Fs): Promise<typeof scanned extends { check(v: unknown): infer T } ? T : never> {
+  let title: string | null = null;
+  try {
+    const pkg = JSON.parse(await fs.read(".baba/package.json")) as { name?: unknown; baba?: { name?: unknown; title?: unknown } };
+    const name = pkg.baba?.name ?? pkg.name;
+    title = typeof pkg.baba?.title === "string" ? pkg.baba.title : typeof name === "string" ? name : null;
+  } catch { /* no title: the program heads the file */ }
+  return { title, outputs: await outputs(fs) };
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+const writtenRow = s.object({ path: s.string(), hash: s.string(), harness: s.string(), status: s.enum(...statuses), action: s.nullable(s.enum("write", "remove")), reason: s.string() });
+
+/**
+ * The system for a baba whose manifest `manifest` answers; null renders
+ * nothing. Its rows are resources, not entities: voss's own system takes no
+ * ids from the baba's sequence and adds nothing to its entities.
+ */
+export const promptwareSystem = (manifest: () => Manifest | null) => system({
+  // promptware, declared: the same for every baba; what it compiles is the manifest each implementation is given.
+  name: "promptware",
+  model: {
+    /** One row per output of the last plan: its hash on disk then, its harness, its status and what a sync does there. */
+    pwWritten: resource(s.array(writtenRow), []),
+    pwStatus: resource({
+      title: s.nullable(s.string()),
+      lastSync: s.nullable(s.integer()),
+      /** Syncs finished, written or failed: what a caller waits on. */
+      syncs: s.integer(),
+      pending: s.integer(),
+      /** The compiled outputs the last plan was made for; empty asks for a new plan. */
+      planned: s.string(),
+      /** A sync asked for and not yet run. */
+      sync: s.boolean(),
+      /** Whether a scan has landed since the baba loaded: nothing is planned before the outputs on disk are known. */
+      scanned: s.boolean(),
+      error: s.nullable(s.string()),
+    }, { title: null, lastSync: null, syncs: 0, pending: 0, planned: "", sync: false, scanned: false, error: null }),
+  },
+  effects: {
+    pwScan: effect({ summary: "read the title and the outputs' hashes", every: 2_000, result: scanned, run: (_, ctx) => scan(ctx.fs) }),
+    pwWrite: effect({
+      summary: "plan the outputs against the files, and write them when asked",
+      args: writeArgs,
+      result: written,
+      run: async (a, ctx) => {
+        const io = contextFiles(ctx.fs);
+        const wanted = { files: Object.fromEntries(a.files.map((f) => [f.path, f.text])), merges: Object.fromEntries(a.merges.map((m) => [m.path, m.merge as Merge])) };
+        let done = { written: [] as string[], removed: [] as string[] };
+        if (a.apply) { const r = await apply(await plan(io, wanted)); done = { written: r.written, removed: r.removed }; }
+        const p = await plan(io, wanted);
+        return {
+          key: a.key, applied: a.apply, ...done,
+          entries: p.entries.map((e) => ({ path: e.path, status: e.status === "foreign" ? "held" as const : e.status, action: e.action, reason: e.reason ?? "", hash: e.before ?? "" })),
+        };
+      },
+    }),
+  },
+}, (promptware, p) => {
+  type W = StateOf<typeof promptware>;
+  const { pwWritten, pwStatus, pwScan, pwWrite } = promptware;
+  const setIf = <K extends typeof pwWritten | typeof pwStatus>(w: W, r: K, v: Value<K>) => { if (!same(w.get(r), v)) w.set(r, v); };
+
+  /** The outputs the state compiles to and their key; null before the baba has a manifest. */
+  const compiled = (w: W) => {
+    const m = manifest();
+    if (!m) return null;
+    const st = w.get(pwStatus);
+    const out = compile({ program: "voss baba", ...(st.title ? { title: st.title } : {}), manifest: m });
+    return { key: hash(JSON.stringify(out)), out };
+  };
+  const currentKey = (w: W) => { try { return compiled(w)?.key ?? null; } catch { return null; } };
+
+  return [
+    p.on(pwScan, {
+      done: (w, _, r) => {
+        const st = w.get(pwStatus);
+        // A file that differs from what the last plan saw asks for a new plan.
+        const disk = new Map(r.outputs.map((o) => [o.path, o.hash]));
+        const dirty = w.get(pwWritten).some((row) => (disk.get(row.path) ?? "") !== row.hash);
+        setIf(w, pwStatus, { ...st, title: r.title, scanned: true, planned: dirty ? "" : st.planned });
+      },
+    }),
+
+    p.on(pwWrite, {
+      done: (w, _, r) => {
+        setIf(w, pwWritten, r.entries.map((e) => ({ path: e.path, hash: e.hash, harness: harnessOf(e.path), status: e.status, action: e.action, reason: e.reason })));
+        const st = w.get(pwStatus);
+        w.set(pwStatus, {
+          ...st, planned: r.key, error: null,
+          pending: r.entries.filter((e) => e.action !== null).length,
+          ...(r.applied ? { lastSync: w.now, syncs: st.syncs + 1, sync: false } : {}),
+        });
+      },
+      failed: (w, _, error) => {
+        const st = w.get(pwStatus);
+        // The plan stays as asked: a file that changes asks again, a failure does not loop.
+        w.set(pwStatus, { ...st, planned: currentKey(w) ?? st.planned, error, ...(st.sync ? { syncs: st.syncs + 1, sync: false } : {}) });
+      },
+    }),
+
+    // What the baba's promptware compiles to, planned when it changed, written when the harness says auto or a sync asked.
+    p.step("plan", (w) => {
+      const st = w.get(pwStatus);
+      if (w.running(pwWrite) || !st.scanned) return;
+      let c;
+      try { c = compiled(w); } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        if (st.error !== error || st.sync) w.set(pwStatus, { ...st, error, sync: false, syncs: st.sync ? st.syncs + 1 : st.syncs });
+        return;
+      }
+      if (!c) return;
+      if (!st.sync && c.key === st.planned) return;
+      w.run(pwWrite, {
+        key: c.key, apply: st.sync || manifest()!.harness.auto,
+        files: Object.entries(c.out.files).map(([path, text]) => ({ path, text })),
+        merges: Object.entries(c.out.merges).map(([path, merge]) => ({ path, merge })),
+      });
+    }),
+
+    p.action("promptware-sync", {
+      summary: "compile the know-how for each harness and write the files now",
+      result: s.object({ asked: s.boolean(), outputs: s.array(writtenRow) }),
+      run: (w) => {
+        w.set(pwStatus, { ...w.get(pwStatus), sync: true });
+        return { asked: true, outputs: w.get(pwWritten) };
+      },
+    }),
+
+    p.query("promptware-plan", {
+      summary: "each output of each harness: its status and what a sync does there",
+      result: s.object({ auto: s.boolean(), lastSync: s.nullable(s.integer()), syncs: s.integer(), pending: s.integer(), error: s.nullable(s.string()), outputs: s.array(writtenRow) }),
+      read: (w) => {
+        const st = w.get(pwStatus);
+        return { auto: manifest()?.harness.auto ?? true, lastSync: st.lastSync, syncs: st.syncs, pending: st.pending, error: st.error, outputs: w.get(pwWritten) };
+      },
+    }),
+  ];
+});
+
+/** What voss tells agents in every baba, after the baba's own promptware: its skills. The word on the two systems it adds is the compiler's, in the shell of the context file. */
+const voss: readonly Prompt[] = guide;
+
+/** Voss's own systems, by identity: filtered from what a project's docs and tables show. */
+export const ours = new WeakSet<object>();
+export const isOurs = (c: object) => ours.has(c);
+
+/** The baba with voss's own systems after its own: what the runtime runs. Every baba gets the shell, the desktop system, over the apps it declares. */
+export function withPromptware(v: Baba): Baba {
+  if (v.systems.some((c) => ours.has(c))) return v;
+  for (const name of ["promptware", "maker"]) if (v.systems.some((c) => nameOf(c) === name)) throw new Error(`a system of this baba is named ${name}, which voss gives every baba; name it otherwise`);
+  // A baba from before the shell was voss's brings its own desktop system, and keeps it; one system or the other, never both.
+  const own = v.systems.find((c) => nameOf(c) === "desktop");
+  if (own && v.apps.length) throw new Error("this baba declares apps and also has a system named desktop; the shell is voss's now: drop the system and keep baba({ apps })");
+  let m: Manifest | null = null;
+  const pw = promptwareSystem(() => m);
+  const catalog = own ? v.apps : catalogOf(v.apps);
+  const shell = own ? null : desktop({ apps: catalog });
+  ours.add(pw);
+  ours.add(maker);
+  if (shell) ours.add(shell);
+  const composed = baba({ systems: [...v.systems, ...(shell ? [shell] : []), pw, maker], apps: catalog, promptware: [...v.promptware, ...voss], harness: v.harness, ...(v.tick !== null ? { tick: v.tick } : {}) });
+  m = manifestOf(composed);
+  return composed;
+}
+