babavoss 0.0.1 → 0.0.2

package/src/ecs/baba.ts

@@ -0,0 +1,431 @@
+// The parts of a baba: the declarations a system's model is made of
+// (components, asks, resources, effects), the handles a declaration makes,
+// the assembled system the runtime runs, the baba that composes systems into
+// one state, and the manifest, the contract as agents, the shell and the GUI
+// see it. `system()` in system.ts is how a system is written.
+// Pure: no IO, no Bun.
+import { s, type Schema, type Infer, type Json, type ObjectOf } from "../kernel/schema.ts";
+import type { Context } from "../kernel/context.ts";
+import { keyFields, keyField } from "./handles.ts";
+import { State, type Component, type Ask, type Resource, type Effect, type Model, type Entity, type Args, type Result, type MirrorEvent } from "./state.ts";
+import { checkPositional } from "../shell/positional.ts";
+import { render, type InterpretationSuite, type Prompt } from "../prompt/index.ts";
+import { routesError } from "../desktop/routes.ts";
+
+// ---- shapes --------------------------------------------------------------
+
+/** A schema, or a bare object of schemas, which is an object schema. */
+export type Shape = Schema<any> | Record<string, Schema<any>>;
+export type SchemaOf<S> = S extends AcceptDef<infer T> ? SchemaOf<T> : S extends Schema<any> ? S : S extends Record<string, Schema<any>> ? Schema<ObjectOf<S>> : never;
+export type Of<S> = Infer<SchemaOf<S>>;
+
+/**
+ * An ask: a component any system may add to an entity, once, that its owner
+ * answers and removes. `components: { ask: accept({ prompt: s.string() }) }`
+ * is how a system says what it does for others; the asker puts the ask on its
+ * own entity and reads the answer there.
+ */
+export interface AcceptDef<S extends Shape = Shape> { readonly isAccept: true; readonly shape: S }
+export function accept<const S extends Shape>(shape: S): AcceptDef<S> { return { isAccept: true, shape }; }
+const isAccept = (v: unknown): v is AcceptDef => typeof v === "object" && v !== null && (v as AcceptDef).isAccept === true;
+
+const isSchema = (v: unknown): v is Schema<any> => typeof v === "object" && v !== null && typeof (v as Schema<any>).check === "function";
+export function shape<S extends Shape>(v: S): SchemaOf<S> {
+  return (isSchema(v) ? v : s.object(v as Record<string, Schema<any>>)) as SchemaOf<S>;
+}
+const empty = s.object({});
+
+// ---- declarations -----------------------------------------------------
+
+/** A resource as declared: its shape and its value before anything happens. */
+export interface ResourceDef<T = unknown> { readonly isResource: true; schema: Schema<T>; initial: T }
+export function resource<S extends Shape>(sh: S, initial: Of<S>): ResourceDef<Of<S>> {
+  return { isResource: true, schema: shape(sh) as Schema<Of<S>>, initial };
+}
+
+/**
+ * An effect as declared: the port. `every` runs it for the system on a
+ * schedule; `retry` re-runs a failure; `repeat: false` says a run cut off by
+ * a crash must not run again: it lands as failed, "interrupted", instead.
+ */
+export interface EffectDef<A = Record<string, never>, R = unknown, V = unknown, Mi extends string | null = string | null, L = unknown> {
+  readonly isEffect: true; args: Schema<A>; result: Schema<R>; retry: number | null; every: number | null; repeat: boolean; summary: string; run(args: A, ctx: Context): Promise<R> | R;
+  shape: "request" | "source"; mirror: string | null; event: Schema<V> | null;
+  // Typed by source(); any here so an Effect of one shape is an Effect of the general one.
+  list: ((args: any, ctx: Context) => Promise<unknown[]> | unknown[]) | null;
+  watch: ((args: any, ctx: Context, last: any) => AsyncIterable<unknown>) | null;
+  /** Types only: the component a mirror keeps, by name, and what its list answers, so the declaration can check both. */
+  readonly $mirror?: Mi;
+  readonly $items?: L;
+}
+const timing = (what: string, def: { retry?: number; every?: number }) => { for (const [k, v] of [["retry", def.retry], ["every", def.every]] as const) if (v !== undefined && !(Number.isInteger(v) && v > 0)) throw new Error(`${what}: ${k} is whole milliseconds, above zero`); };
+export function effect<A = Record<string, never>, R = unknown>(def: { summary?: string; args?: Schema<A>; result?: Schema<R>; retry?: number; every?: number; repeat?: boolean; run(args: A, ctx: Context): Promise<R> | R }): EffectDef<A, R, unknown, null> {
+  timing("effect", def);
+  return { isEffect: true, shape: "request", mirror: null, event: null, list: null, watch: null, args: def.args ?? (empty as unknown as Schema<A>), result: def.result ?? (s.unknown() as Schema<R>), retry: def.retry ?? null, every: def.every ?? null, repeat: def.repeat ?? true, summary: def.summary ?? "", run: def.run };
+}
+
+/**
+ * A source: a job that keeps answering. `list` answers the slice of the
+ * outside as it is; `watch` yields its changes, with the last event it
+ * landed before, for a stream that can resume. With `mirror`, the system's
+ * component it keeps: items are that component's values by its key, a
+ * watch yields items, `{ gone: key }`, or `{ changed: true }` to list again;
+ * `every` lists again on a schedule. Without, a stream: `event` is the
+ * schema of what `watch` yields, read by a step with `w.events`.
+ */
+export function source<A = Record<string, never>, V = unknown, const Mi extends string = never, L = unknown>(def: {
+  summary?: string; args?: Schema<A>; retry?: number; every?: number; repeat?: boolean;
+  mirror?: Mi; event?: Schema<V>;
+  list?: (args: A, ctx: Context) => Promise<L[]> | L[];
+  watch?: (args: A, ctx: Context, last: V | undefined) => AsyncIterable<V | MirrorEvent>;
+}): EffectDef<A, void, V, [Mi] extends [never] ? null : Mi, L> {
+  timing("source", def);
+  if (!def.list && !def.watch) throw new Error("source: a list, a watch, or both");
+  if (def.mirror && def.event) throw new Error("source: a mirror keeps a component, so its events have the component's shape; event is for a stream");
+  if (!def.mirror && !def.watch) throw new Error("source: a stream watches; a source that only lists keeps a mirror");
+  return {
+    isEffect: true, shape: "source", mirror: def.mirror ?? null, event: def.event ?? (def.mirror ? null : (s.unknown() as Schema<V>)), watch: (def.watch as EffectDef["watch"]) ?? null, list: (def.list as EffectDef["list"]) ?? null,
+    args: def.args ?? (empty as unknown as Schema<A>), result: s.void() as Schema<void>, retry: def.retry ?? null, every: def.every ?? null, repeat: def.repeat ?? true, summary: def.summary ?? "",
+    run: () => { throw new Error("a source is driven by the runtime, not run"); },
+  };
+}
+
+/** The contract, by name: an action writes inside the round, a query reads between rounds; both take typed args and answer a typed value. */
+export interface ActionDef<A = any, R = any, X = any> { readonly isAction: true; summary: string; args: Schema<A>; positional?: string[]; result: Schema<R>; run(w: State<X>, args: A): R }
+export function action<const S extends Shape = {}, R = void, X = any>(def: { summary?: string; args?: S; positional?: (keyof Of<S> & string)[]; result?: Schema<R>; run(w: State<X>, args: Of<S>): R }): ActionDef<Of<S>, R, X> {
+  const args = (def.args ? shape(def.args) : empty) as Schema<Of<S>>;
+  return { isAction: true, summary: def.summary ?? "", args, ...(def.positional?.length ? { positional: checkPositional(args.json, def.positional) } : {}), result: def.result ?? (s.unknown() as Schema<R>), run: def.run };
+}
+export interface QueryDef<A = any, R = any, X = any> { readonly isQuery: true; summary: string; args: Schema<A>; positional?: string[]; result: Schema<R>; read(w: State<X>, args: A): R }
+export function query<const S extends Shape = {}, R = unknown, X = any>(def: { summary?: string; args?: S; positional?: (keyof Of<S> & string)[]; result?: Schema<R>; read(w: State<X>, args: Of<S>): R }): QueryDef<Of<S>, R, X> {
+  const args = (def.args ? shape(def.args) : empty) as Schema<Of<S>>;
+  return { isQuery: true, summary: def.summary ?? "", args, ...(def.positional?.length ? { positional: checkPositional(args.json, def.positional) } : {}), result: def.result ?? (s.unknown() as Schema<R>), read: def.read };
+}
+
+/** A skill as the manifest carries it, rendered: what an agent reads when it opens it, and the calls it uses, by name. */
+export interface SkillDef { description: string; body: string; uses?: string[]; eval?: InterpretationSuite }
+/** What the baba tells agents, as the manifest carries it: its section of the context file, its skills, its hooks; the Markdown rendered. */
+export interface Promptware { context: string | null; contextEval?: InterpretationSuite; skills: Record<string, SkillDef>; hooks: HookDef[] }
+
+/** Which harnesses get the baba's files, and Claude Code's permissions; `table` renders the contract as a table of calls; `auto` writes the files on every change. */
+export interface Harness { claude: { enabled: boolean; permissions: string[] }; codex: { enabled: boolean }; table: boolean; auto: boolean }
+/** `harness` as a baba writes it: a harness is on or off, or Claude Code's with permissions added to voss's own. */
+export interface HarnessInput { claude?: boolean | { enabled?: boolean; permissions?: string[] }; codex?: boolean | { enabled?: boolean }; table?: boolean; auto?: boolean }
+
+/** The permission every baba gives Claude Code: its own calls. */
+export const OWN_PERMISSION = "Bash(voss baba:*)";
+export const defaultHarness: Harness = Object.freeze({ claude: { enabled: true, permissions: [OWN_PERMISSION] }, codex: { enabled: false }, table: false, auto: true });
+
+/** The harness as given over the defaults, checked. */
+export function harnessOf(h: HarnessInput | undefined): Harness {
+  const flag = (v: unknown, what: string): boolean => { if (typeof v !== "boolean") throw new Error(`baba: harness.${what} is true or false`); return v; };
+  const on = (v: boolean | { enabled?: boolean } | undefined, what: string) => v === undefined ? defaultHarness[what as "codex"].enabled : typeof v === "boolean" ? v : v.enabled === undefined ? true : flag(v.enabled, `${what}.enabled`);
+  const given = typeof h?.claude === "object" ? h.claude.permissions ?? [] : [];
+  if (!Array.isArray(given) || !given.every((p) => typeof p === "string")) throw new Error("baba: harness.claude.permissions is a list of strings");
+  return {
+    claude: { enabled: on(h?.claude, "claude"), permissions: [...new Set([OWN_PERMISSION, ...given])] },
+    codex: { enabled: on(h?.codex, "codex") },
+    table: h?.table === undefined ? defaultHarness.table : flag(h.table, "table"),
+    auto: h?.auto === undefined ? defaultHarness.auto : flag(h.auto, "auto"),
+  };
+}
+/** A hook as the manifest carries it. */
+export interface HookDef { on: string; match: string | null; action: string; strict: boolean }
+
+// ---- the system, assembled ------------------------------------------------
+
+/** Where a system keeps what the framework knows of it: its handles are its only string keys, so no handle name is reserved. */
+export const SYSTEM: unique symbol = Symbol.for("babavoss.system");
+
+/** A step: synchronous, over the state alone, run once per round in the order the system lists it. */
+export type Step<X = any> = (w: State<X>) => void;
+
+/** How an effect's answers land, and for which entities it runs. */
+export interface Binding<E = Effect, X = any> {
+  /** The entities to run it for, with the args of each; one job per entity, asked again only once answered. */
+  for?: (w: State<X>) => Iterable<readonly [Entity, Args<E>]>;
+  done?: (w: State<X>, entity: Entity | null, result: Result<E>) => void;
+  failed?: (w: State<X>, entity: Entity | null, error: string) => void;
+}
+
+type ComponentRefs<N extends string, C> = { readonly [K in keyof C & string]: C[K] extends AcceptDef<any> ? Ask<K, Of<C[K]>, N> : Component<K, Of<C[K]>, N> };
+type ResourceRefs<N extends string, R> = { readonly [K in keyof R & string]: Resource<K, R[K] extends ResourceDef<infer T> ? T : never, N> };
+type EffectRefs<N extends string, E> = { readonly [K in keyof E & string]: E[K] extends EffectDef<infer A, infer R, infer V> ? Effect<K, A, R, V, N> : never };
+/** A system's handles by name, each branded with the system's name. */
+export type Refs<N extends string, C, R, E> = ComponentRefs<N, C> & ResourceRefs<N, R> & EffectRefs<N, E>;
+
+/** What assembling takes: the effects' bindings, the steps in order, the contract with its bodies. */
+export interface Logic {
+  on?: Map<Effect, Binding>;
+  steps?: { name: string; run: Step }[];
+  actions?: Record<string, ActionDef>;
+  queries?: Record<string, QueryDef>;
+}
+
+/** What a contract entry takes and answers, by name. */
+export type Calls<D> = { [K in keyof D & string]: D[K] extends { args: Schema<infer A>; result: Schema<infer R> } ? { args: A; result: R } : never };
+/** A system's contract, as types: its actions and its queries by name, each its args and result. */
+export interface Contract<A = any, Q = any> { readonly act: A; readonly read: Q }
+
+/** What the runtime reads of a system, under SYSTEM. */
+export interface SystemData {
+  readonly name: string;
+  readonly model: Model;
+  /** The systems it reads: their handles are the only other ones its pieces may touch. */
+  readonly reads: readonly System[];
+  readonly actions: Readonly<Record<string, ActionDef>>;
+  readonly queries: Readonly<Record<string, QueryDef>>;
+  readonly steps: readonly { name: string; run: Step }[];
+  readonly bindings: ReadonlyMap<Effect, Binding>;
+}
+/** Types only: the name, the handles, the systems read, the contract. */
+interface Types<N extends string, X, R, C> { readonly name: N; readonly handles: X; readonly reads: R; readonly contract: C }
+
+/** A system: its handles by name, and under SYSTEM what the runtime runs. `N` its name, `X` its handles, `R` the systems it reads, `C` its contract. */
+export type System<N extends string = string, X = any, R = any, C = any> = X & { readonly [SYSTEM]: SystemData & { readonly $types?: Types<N, X, R, C> } };
+
+/** What the framework knows of a system; a clear error for anything else, a copy of a system included, which loses its data. */
+export function dataOf(v: unknown): SystemData {
+  const d = typeof v === "object" && v !== null ? (v as { [SYSTEM]?: SystemData })[SYSTEM] : undefined;
+  if (!d) throw new Error("not a system: its data is missing (was it cloned, spread or serialized?)");
+  return d;
+}
+/** A system's name. Never String(system): a system has no prototype, so it does not stringify. */
+export const nameOf = (v: unknown): string => dataOf(v).name;
+
+/** A name: a letter, then letters, digits and dashes; a system's is lowercase. */
+const NAME = /^[a-z][a-zA-Z0-9-]*$/;
+const SYSTEM_NAME = /^[a-z][a-z0-9-]*$/;
+/** Words the shell keeps for itself: an action or a query may not take them. */
+export const RESERVED = new Set(["start", "stop", "status", "state", "follow", "run", "raw", "secret", "help", "mcp", "check", "install", "add-system", "serve", "promptware", "init", "babas", "service", "gui"]);
+
+/** What a declaration makes: its handles by name, on an object with no prototype, and the model they form. */
+export interface Declared { readonly name: string; readonly refs: Readonly<Record<string, Component | Resource | Effect>>; readonly model: Model }
+
+/** The handles of a model, checked: names, key fields, mirrors, initial values. */
+export function declareModel(name: string, model: { components?: Record<string, Shape | AcceptDef>; resources?: Record<string, ResourceDef<any>>; effects?: Record<string, EffectDef<any, any>> }): Declared {
+  if (typeof name !== "string" || !SYSTEM_NAME.test(name)) throw new Error(`system ${JSON.stringify(name)}: lowercase letters, digits and dashes`);
+  const m: Model = { components: [], resources: [], effects: [] };
+  // No prototype: `toString` or `constructor` are names like any other, and `in` sees only what was declared.
+  const refs: Record<string, Component | Resource | Effect> = Object.create(null);
+  const word = (n: string, what: string) => {
+    // `entity` is every row's own field: a component under that name would hide it.
+    if (!NAME.test(n) || n === "entity") throw new Error(`${what} ${JSON.stringify(n)} of ${name}: a letter, then letters, digits and dashes; not entity`);
+    if (Object.hasOwn(refs, n)) throw new Error(`${name} declares ${n} twice`);
+    return n;
+  };
+  for (const [n, def] of Object.entries(model.components ?? {})) {
+    const sh = isAccept(def) ? def.shape : def;
+    const c: Component = Object.freeze({ kind: "component", name: word(n, "component"), owner: name, schema: shape(sh), accept: isAccept(def) });
+    const keys = keyFields(c.schema.json);
+    if (keys.length > 1) throw new Error(`component ${n} of ${name} has ${keys.length} key fields, ${keys.join(", ")}; at most one`);
+    refs[n] = c; m.components.push(c);
+  }
+  for (const [n, d] of Object.entries(model.resources ?? {})) { const r: Resource = Object.freeze({ kind: "resource", name: word(n, "resource"), owner: name, schema: d.schema, initial: d.initial }); refs[n] = r; m.resources.push(r); }
+  for (const [n, d] of Object.entries(model.effects ?? {})) {
+    let of: string | null = null;
+    if (d.mirror) {
+      const c = m.components.find((x) => x.name === d.mirror);
+      if (!c) throw new Error(`source ${n} of ${name} keeps ${d.mirror}, which is not a component of ${name}`);
+      if (keyField(c.schema.json) === null) throw new Error(`source ${n} of ${name} keeps ${d.mirror}, which has no key field; a mirror's items are put by their key`);
+      const props = (c.schema.json.properties ?? {}) as Record<string, Json>;
+      const ofs = Object.entries(props).filter(([, p]) => p.description === "an entity").map(([k]) => k);
+      if (ofs.length > 1) throw new Error(`source ${n} of ${name} keeps ${d.mirror}, which has ${ofs.length} entity fields; at most one, for the job's entity`);
+      of = ofs[0] ?? null;
+      if (m.effects.some((x) => x.mirror === d.mirror)) throw new Error(`${d.mirror} of ${name} is kept by two sources`);
+    }
+    const e: Effect = Object.freeze({ kind: "effect", name: word(n, "effect"), owner: name, args: d.args, result: d.result, retry: d.retry, every: d.every, repeat: d.repeat, summary: d.summary, run: d.run, shape: d.shape, mirror: d.mirror, of, event: d.event, list: d.list, watch: d.watch });
+    refs[n] = e; m.effects.push(e);
+  }
+  new State(m);   // initial values checked
+  return { name, refs: Object.freeze(refs), model: m };
+}
+
+/** The system object, built while its pieces are made: its handles now, its data once `complete` runs. */
+export function systemObject(d: Declared, reads: readonly System[]): { system: System; complete(l: Logic): System } {
+  const { name, refs, model: m } = d;
+  const o: Record<string | symbol, unknown> = Object.create(null);
+  for (const k of Object.keys(refs)) o[k] = refs[k];
+  let data: SystemData = { name, model: m, reads, actions: {}, queries: {}, steps: [], bindings: new Map() };
+  Object.defineProperty(o, SYSTEM, { get: () => data, enumerable: false });
+  return {
+    system: o as System,
+    complete(l) {
+      const actions: Record<string, ActionDef> = {};
+      const queries: Record<string, QueryDef> = {};
+      const call = (n: string, what: string) => {
+        if (!NAME.test(n)) throw new Error(`${what} ${JSON.stringify(n)} of ${name}: a letter, then letters, digits and dashes`);
+        if (RESERVED.has(n)) throw new Error(`${what} ${n} of ${name}: ${n} is a word of the shell (reserved: ${[...RESERVED].join(", ")}); name it otherwise`);
+      };
+      for (const [n, a] of Object.entries(l.actions ?? {})) { call(n, "action"); actions[n] = a; }
+      for (const [n, q] of Object.entries(l.queries ?? {})) {
+        call(n, "query");
+        if (n in actions) throw new Error(`${n} of ${name} is both an action and a query`);
+        queries[n] = q;
+      }
+      for (const e of l.on?.keys() ?? []) if (refs[e.name] !== e) throw new Error(`${name} binds ${e.name}, which is not one of its effects`);
+      data = Object.freeze({ name, model: m, reads, actions, queries, steps: l.steps ?? [], bindings: l.on ?? new Map() });
+      return Object.freeze(o) as System;
+    },
+  };
+}
+
+/** A system and every system it reads, and theirs: what a state of it needs. */
+export function closureOf(systems: readonly System[]): System[] {
+  const out: System[] = [];
+  const visit = (sys: System) => { if (out.includes(sys)) return; out.push(sys); for (const r of dataOf(sys).reads) visit(r); };
+  for (const sys of systems) visit(sys);
+  return out;
+}
+
+// ---- the baba -----------------------------------------------------------
+
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type ContractOf<S> = S extends { readonly [SYSTEM]: { readonly $types?: Types<any, any, any, infer C> } } ? C : never;
+/** The actions of a system or a baba, by name, each its args and result: what a typed caller fires. */
+export type ActOf<V> = V extends { readonly kind: "baba"; readonly systems: infer Ss extends readonly unknown[] } ? UnionToIntersection<{ [I in keyof Ss]: ActsOf<Ss[I]> }[number]> : ActsOf<V>;
+/** The queries of a system or a baba, by name. */
+export type ReadOf<V> = V extends { readonly kind: "baba"; readonly systems: infer Ss extends readonly unknown[] } ? UnionToIntersection<{ [I in keyof Ss]: ReadsOf<Ss[I]> }[number]> : ReadsOf<V>;
+// A system typed `any` (a baba built from untyped systems) answers anything, as an untyped caller expects.
+type Loose = Record<string, { args: any; result: any }>;
+type ActsOf<S> = 0 extends 1 & S ? Loose : ContractOf<S> extends Contract<infer A, any> ? A : never;
+type ReadsOf<S> = 0 extends 1 & S ? Loose : ContractOf<S> extends Contract<any, infer Q> ? Q : never;
+
+/**
+ * An app: a kind of window the shell opens, declared by the baba as data. `icon` is a Lucide icon's
+ * name (`git-merge`); `group` heads it in the launcher; `many` lets the launcher open another window
+ * of it, without it an app has one window per session; `systems` names the systems it shows, so the
+ * Maker offers it over a state that has them. `routes` are the paths its windows may be at, `/pr/:n`, the
+ * last segment `*` for the rest; one takes `/`, its home. An app with routes is opened only at a path one of
+ * them takes, and the interface may give it a component per route; without routes any path is its own.
+ * Its component is the interface's, by key.
+ */
+export interface AppSpec { key: string; title: string; group?: string; icon?: string; many?: boolean; systems?: readonly string[]; routes?: readonly string[] }
+/** The routes of each app, as types: what `compose<typeof baba>` checks a table of components against. */
+export type RoutesOf<Sc extends readonly AppSpec[]> = { [A in Sc[number] as A["key"]]: A extends { routes: readonly (infer P extends string)[] } ? P : never };
+
+export interface Baba<Ss extends readonly System[] = readonly System[], K extends string = string, R = {}> {
+  readonly kind: "baba";
+  readonly systems: Ss;
+  /** The apps the shell offers, in launcher order; the interface gives each its component. */
+  readonly apps: readonly AppSpec[];
+  /** The app keys, as a type: what `compose<typeof baba>` asks a component for. */
+  readonly $app: K;
+  /** The routes of each app, as a type: what `compose<typeof baba>` asks a table of components for. */
+  readonly $routes: R;
+  /** What the baba tells agents: `context(...)`, `skill(...)` and `hook(...)` from babavoss/prompt, in order. */
+  readonly promptware: readonly Prompt[];
+  /** Which harnesses get the files, and how. */
+  readonly harness: Harness;
+  /** Milliseconds between rounds the runtime causes on its own, for steps that need time to pass; null for a baba moved by actions and jobs. */
+  readonly tick: number | null;
+  readonly model: Model;
+  readonly actions: Record<string, ActionDef & { owner: string }>;
+  readonly queries: Record<string, QueryDef & { owner: string }>;
+}
+
+export function baba<const Ss extends readonly System[], const Sc extends readonly AppSpec[] = readonly []>(def: { systems: Ss; apps?: Sc; tick?: number; promptware?: readonly Prompt[]; harness?: HarnessInput }): Baba<Ss, Sc[number]["key"], RoutesOf<Sc>> {
+  const harness = harnessOf(def.harness);
+  if (def.tick !== undefined && !(Number.isInteger(def.tick) && def.tick > 0)) throw new Error("baba: tick is whole milliseconds, above zero");
+  const model: Model = { components: [], resources: [], effects: [] };
+  const names = new Map<string, string>();
+  const systemNames = new Set<string>();
+  const systems = (def.systems as readonly unknown[]).map((v, i) => {
+    if (!isSystem(v)) throw new Error(`baba: systems[${i}] is not a system; a system's module exports it: export default system({ name, … }, (it, p) => [ … ])`);
+    return v;
+  });
+  for (const sys of systems) {
+    const c = dataOf(sys);
+    if (systemNames.has(c.name)) throw new Error(`two systems are named ${c.name}`);
+    systemNames.add(c.name);
+    for (const d of [...c.model.components, ...c.model.resources, ...c.model.effects]) {
+      const other = names.get(d.name);
+      if (other) throw new Error(`${d.name} is declared by both ${other} and ${c.name}`);
+      names.set(d.name, c.name);
+    }
+    model.components.push(...c.model.components);
+    model.resources.push(...c.model.resources);
+    model.effects.push(...c.model.effects);
+  }
+  for (const sys of systems) for (const r of dataOf(sys).reads) if (!systems.includes(r)) throw new Error(`${nameOf(sys)} reads ${nameOf(r)}, which is not one of the baba's systems`);
+  const actions: Baba["actions"] = {};
+  const queries: Baba["queries"] = {};
+  for (const sys of systems) {
+    const c = dataOf(sys);
+    for (const [n, a] of Object.entries(c.actions)) {
+      if (n in actions || n in queries) throw new Error(`${n} is an action or query of two systems`);
+      actions[n] = { ...(a as ActionDef), owner: c.name };
+    }
+    for (const [n, q] of Object.entries(c.queries)) {
+      if (n in actions || n in queries) throw new Error(`${n} is an action or query of two systems`);
+      queries[n] = { ...(q as QueryDef), owner: c.name };
+    }
+  }
+  // Scenes took the name apps: an old baba is told what to rename, not left with an empty desktop.
+  if ("scenes" in def) throw new Error("baba: `scenes` is now `apps`; rename it in baba({ … }) and in compose({ … }), and .baba/scenes/ to .baba/apps/");
+  const apps = (def.apps ?? []) as readonly AppSpec[];
+  if (new Set(apps.map((v) => v.key)).size !== apps.length || apps.some((v) => !/^[a-z][a-z0-9-]*$/.test(v.key))) throw new Error("baba: app keys must be unique lowercase names");
+  for (const v of apps) for (const n of v.systems ?? []) if (!systemNames.has(n)) throw new Error(`app ${v.key} shows ${n}, which is not one of the baba's systems`);
+  for (const v of apps) { const e = v.routes && routesError(v.routes); if (e) throw new Error(`app ${v.key}: ${e}`); }
+  return Object.freeze({ kind: "baba", systems: def.systems, apps: apps.map((v) => ({ ...v, ...(v.systems ? { systems: [...v.systems] } : {}), ...(v.routes ? { routes: [...v.routes] } : {}) })), $app: undefined as never, $routes: undefined as never, tick: def.tick ?? null, promptware: [...(def.promptware ?? [])], harness, model, actions, queries });
+}
+
+export function isBaba(v: unknown): v is Baba {
+  return typeof v === "object" && v !== null && (v as Baba).kind === "baba" && Array.isArray((v as Baba).systems);
+}
+
+export function isSystem(v: unknown): v is System {
+  return typeof v === "object" && v !== null && SYSTEM in v;
+}
+
+/** A single system as a baba of its own, with the systems it reads: what a testbed takes. */
+export function ofSystem(c: System): Baba { return baba({ systems: closureOf([c]) }); }
+
+// ---- the manifest --------------------------------------------------------
+
+/** The contract as agents, the shell and the GUI see it: everything by name, with its owner. */
+export interface Manifest {
+  systems: { name: string }[];
+  /** What the baba tells agents, rendered: its context, its skills, its hooks; voss's own skills after the baba's. */
+  promptware: Promptware;
+  harness: Harness;
+  components: Record<string, { owner: string; schema: Json; accept?: true }>;
+  resources: Record<string, { owner: string; schema: Json }>;
+  effects: Record<string, { owner: string; summary: string; args: Json; result: Json; retry: number | null; every: number | null; repeat: boolean; shape: "request" | "source"; mirror?: string; event?: Json }>;
+  actions: Record<string, Call>;
+  queries: Record<string, Call>;
+  tick: number | null;
+  /** The apps the shell offers; absent from a manifest an older voss wrote. */
+  apps?: AppSpec[];
+}
+
+/** One entry of the contract as the manifest carries it. */
+export interface Call { owner: string; summary: string; args: Json; positional?: string[]; result: Json }
+
+export function manifestOf(v: Baba, program = "voss baba"): Manifest {
+  const m: Manifest = { systems: v.systems.map((c) => ({ name: nameOf(c) })), promptware: { context: null, skills: {}, hooks: [] }, harness: v.harness, components: {}, resources: {}, effects: {}, actions: {}, queries: {}, tick: v.tick, apps: v.apps.map((x) => ({ ...x })) };
+  for (const c of v.model.components) m.components[c.name] = { owner: c.owner, schema: c.schema.json, ...(c.accept ? { accept: true as const } : {}) };
+  for (const r of v.model.resources) m.resources[r.name] = { owner: r.owner, schema: r.schema.json };
+  for (const e of v.model.effects) m.effects[e.name] = { owner: e.owner, summary: e.summary, args: e.args.json, result: e.result.json, retry: e.retry, every: e.every, repeat: e.repeat, shape: e.shape, ...(e.mirror ? { mirror: e.mirror } : {}), ...(e.event ? { event: e.event.json } : {}) };
+  const call = (d: (ActionDef | QueryDef) & { owner: string }): Call => ({ owner: d.owner, summary: d.summary, args: d.args.json, ...(d.positional ? { positional: d.positional } : {}), result: d.result.json });
+  for (const [n, a] of Object.entries(v.actions)) m.actions[n] = call(a);
+  for (const [n, q] of Object.entries(v.queries)) m.queries[n] = call(q);
+  // The promptware renders once the contract is in the manifest, since it may refer to it.
+  const refs: string[] = [];
+  m.promptware = renderPromptware(v.promptware, { manifest: m, program, refs });
+  for (const r of refs) if (!(r in m.promptware.skills)) throw new Error(`a skill says "see ${r}", which is not a skill of the baba`);
+  for (const [n, sk] of Object.entries(m.promptware.skills)) for (const u of sk.uses ?? []) if (!(u in m.actions) && !(u in m.queries)) throw new Error(`skill ${n} uses ${u}, which is not an action or query of the baba`);
+  for (const h of m.promptware.hooks) if (!(h.action in m.actions)) throw new Error(`hook on ${h.on} calls ${h.action}, which is not an action of the baba`);
+  return m;
+}
+
+/** The baba's promptware as Markdown: the one context, each skill by name, the hooks. */
+export function renderPromptware(ps: readonly Prompt[], context: { manifest: Manifest; program: string; refs?: string[] }): Promptware {
+  const contexts = ps.filter((p) => p.kind === "context");
+  if (contexts.length > 1) throw new Error("a baba has one context(...); put every paragraph in it");
+  const text = contexts[0] ? render(contexts[0].body, context) : "";
+  const skills: Record<string, SkillDef> = {};
+  for (const p of ps) if (p.kind === "skill") { if (p.name in skills) throw new Error(`two skills are named ${p.name}`); skills[p.name] = { description: p.description, body: render(p.body, context), uses: p.uses, ...(p.eval ? { eval: p.eval } : {}) }; }
+  const hooks = ps.filter((p) => p.kind === "hook").map((p) => ({ on: p.on, match: p.match, action: p.action, strict: p.strict }));
+  return { context: text || null, skills, hooks, ...(contexts[0]?.eval ? { contextEval: contexts[0].eval } : {}) };
+}