@sigrun/sigrun 0.1.6 → 0.2.1

package/dist/extension.d.ts

@@ -35,12 +35,12 @@
 import type { AssistantMessage, Provider } from "@earendil-works/pi-ai";
 import type { ConversationDocToken, ConversationId, Cursor, EntryId, EntryQuery, EntryRecord, Extension, InputSubmissionDraft, JsonObject, ModelRef, Page, SubmissionId } from "@earendil-works/pi-durable";
 import type { Access, Sharing } from "@sigrun/shared/access";
-import type { AmbientBody, AmbientPlace, AmbientRecord } from "@sigrun/shared/ambient";
+import type { AmbientPlace, AmbientRecord } from "@sigrun/shared/ambient";
 import type { Action, DataOps, IconName, Tree } from "@sigrun/shared/blocks";
 import type { InteractionAnswer, InteractionRecord } from "@sigrun/shared/interactions";
 import type { JobSpec } from "@sigrun/shared/jobs";
-import type { ConversationSummary, ConversationViewWire, HealthStatus, ModelEntry, SessionMeta, SlashCommand, SubmissionRecordWire, ThinkingLevelWire, UserWire as DirectoryUserWire } from "@sigrun/shared/views";
-export type { Access, AmbientRecord, DirectoryUserWire, InteractionRecord, JobSpec, ModelEntry, Sharing, SlashCommand, };
+import type { AccountLinkWire, ConversationSummary, ConversationViewWire, HealthStatus, ModelEntry, SessionMeta, SlashCommand, SubmissionRecordWire, ThinkingLevelWire, UserWire as DirectoryUserWire } from "@sigrun/shared/views";
+export type { Access, AccountLinkWire, AmbientRecord, DirectoryUserWire, InteractionRecord, JobSpec, ModelEntry, Sharing, SlashCommand, };
 type JsonParams = JsonObject;
 type JsonParamValue = JsonParams[string];
 /**
@@ -63,6 +63,8 @@ export interface HandlerContext {
  */
 export type RunSettledEvent = {
     readonly conversationId: ConversationId;
+    /** The conversation owner at delivery; absent when the conversation is ownerless. */
+    readonly owner?: string;
     readonly inputs: readonly SubmissionId[];
     /** Text blocks of each input's entry (`pi.user`, or an expanded input's
      *  `sigrun.user.expanded` — the ADMITTED text), concatenated;
@@ -100,19 +102,24 @@ export type MemoryEventApi = {
 export type ExtensionLifecyclePayload = {
     conversationCreated: {
         readonly conversationId: ConversationId;
+        readonly owner?: string;
     };
     conversationForked: {
         readonly childId: ConversationId;
         readonly parentId: ConversationId;
         readonly at: EntryId;
+        /** The CHILD's owner at delivery; absent when the child is ownerless. */
+        readonly owner?: string;
     };
     conversationArchived: {
         readonly conversationId: ConversationId;
         readonly archived: boolean;
+        readonly owner?: string;
     };
     conversationIdle: {
         readonly conversationId: ConversationId;
         readonly idleMs: number;
+        readonly owner?: string;
     };
     /** Gateway C6: one terminal interaction transition — the payload mirrors
      *  the record's terminal envelope fields. */
@@ -121,6 +128,11 @@ export type ExtensionLifecyclePayload = {
         readonly callId: string;
         readonly kind: string;
         readonly status: "answered" | "skipped" | "expired" | "cancelled";
+        /** The answering user (C5 attribution), when a human answered. */
+        readonly answeredByUser?: string;
+        /** The STORED (masked-by-construction) answer values — render-safe. */
+        readonly answer?: Readonly<Record<string, unknown>>;
+        readonly owner?: string;
     };
 };
 /** A factory-result `runSettled` handler: called once per settled run, deadline-bounded. */
@@ -151,6 +163,17 @@ export type SigrunLifecycleHandlers = {
     readonly harnessShutdown?: ExtensionHarnessShutdownHandler;
     /** The user-removal transfer event; direct fan-out, not commit-derived. */
     readonly userDeleted?: ExtensionUserDeletedHandler;
+    /**
+     * UI-blocks U4 (spec §13.2): called after a settings write COMMITS —
+     * the keys are the flattened paths the write touched (core keys in
+     * the §13.1 dotted vocabulary, this extension's own top-level keys
+     * for a `settings/<slug>.json` write). Fired for BOTH scopes: a
+     * server-scope write notifies every loaded extension; an extension's
+     * own write notifies it (and every other extension — settings are
+     * shared operator surface). Errors are caught and logged; the write
+     * already succeeded and stays successful.
+     */
+    onSettingsChanged?(keys: readonly string[], user?: string): void | Promise<void>;
 };
 /**
  * The lifecycle event names a worker's `wakeOn` may declare.
@@ -182,6 +205,31 @@ export interface ExtensionWorker {
     /** The work; rejects (or overruns the worker deadline) to fail the run. */
     run(context: HandlerContext, wake?: WorkerWake): Promise<void>;
 }
+/** The command and extra environment/read rights for one per-user process. */
+export interface ServiceSpec {
+    readonly command: string;
+    readonly args: string[];
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+    readonly readPaths?: string[];
+}
+/** One factory-declared long-lived per-user service. */
+export interface UserService {
+    readonly name: string;
+    start(user: string, ctx: HandlerContext): Promise<ServiceSpec | undefined>;
+    readonly idleMinutes?: number;
+}
+/** A shared-stdio attachment to a running per-user service. */
+export interface ServiceHandle {
+    readonly stdin: WritableStream<Uint8Array>;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    readonly exited: Promise<{
+        code: number | null;
+        signal: string | null;
+    }>;
+    release(): void;
+}
 /** Three-state per-provider readiness: not configured, degraded, or ready. */
 export type ProviderReadinessStatus = "not_configured" | "degraded" | "ready";
 /** One readiness report: the status plus optional operator-facing detail. */
@@ -207,6 +255,42 @@ export interface ProviderContribution {
     /** The per-provider readiness tracker (`/v1/auth/check` reports it verbatim). */
     readonly readiness?: ReadinessTracker;
 }
+/** Core-owned state for one external login, with provider-private scratch data. */
+export type LoginFlow = {
+    state: string;
+    callbackUrl: string;
+    data: Record<string, string>;
+};
+/** The identity proof a login provider returns after its callback. */
+export type LoginResult = {
+    subject: string;
+    profile: {
+        username?: string;
+        name?: string;
+        email?: string;
+        emailVerified?: boolean;
+    };
+    groups?: string[];
+};
+/** One extension identity provider; core owns the flow, state and callback. */
+export interface LoginProviderContribution {
+    readonly id: string;
+    readonly label: string;
+    readonly icon?: string;
+    /** Provider-declared provisioning policy, enforced by core. */
+    readonly policy?: {
+        readonly autoProvision?: boolean;
+        readonly allowedGroups?: string[];
+        readonly allowedDomains?: string[];
+    };
+    begin(flow: LoginFlow, ctx: HandlerContext): Promise<{
+        redirectUrl: string;
+    }>;
+    complete(flow: LoginFlow, callback: {
+        query: Record<string, string>;
+        body?: unknown;
+    }, ctx: HandlerContext): Promise<LoginResult>;
+}
 /** One contributed webui bundle: a selection name plus the bundle root directory. */
 export interface WebuiBundleContribution {
     /** The selection key (`server.webui.bundle`); must match `^[a-z][a-z0-9_-]*$`. */
@@ -231,7 +315,9 @@ export interface Principal {
     readonly admin: boolean;
     /** True for the `SIGRUN_API_TOKEN` service principal. */
     readonly service: boolean;
-    readonly method: "none" | "token" | "proxy" | "host";
+    readonly method: "none" | "token" | "session" | "proxy" | "host";
+    /** The login provider that issued a session principal. */
+    readonly provider?: string;
 }
 /** One extension HTTP route, mounted at `/v1/ext/<slug>/<path>`. */
 export interface ExtensionRouteContribution {
@@ -263,14 +349,18 @@ export interface ExtensionCommandContribution {
         readonly notice?: string;
     } | void>;
 }
-/** One notification core delivers to every registered notifier (best-effort). */
-export interface NotificationEvent {
-    readonly type: "interaction.pending" | "job.failed" | "run.settled";
+/** The settled-run outcome: the notification-safe projection of the host
+ *  event's `outcome`/`reason` (status and reason only — no answer text). */
+export type RunSettledOutcome = {
+    readonly status: "answered";
+} | {
+    readonly status: "unanswered";
+    readonly reason: string;
+};
+/** Fields shared by every notification variant. */
+interface NotificationEventBase {
     readonly conversationId?: number;
     readonly jobId?: string;
-    /** Gateway C6: the pending record's id — set on `interaction.pending` only
-     *  (read the record via `host.snapshotInteraction`). */
-    readonly callId?: string;
     /** The recipient. */
     readonly user: string | undefined;
     readonly title: string;
@@ -278,6 +368,21 @@ export interface NotificationEvent {
     /** `${server.publicUrl}/#/c/<conversationId>` when `server.publicUrl` is set; absent otherwise. */
     readonly url?: string;
 }
+/** One notification core delivers to every registered notifier (best-effort). */
+export type NotificationEvent = NotificationEventBase & ({
+    readonly type: "interaction.pending";
+    /** Gateway C6: the pending record's id — set on `interaction.pending` only
+     *  (inspect it via `host.peekInteraction`; the OWNING extension's
+     *  delivery read is `host.snapshotInteraction`). */
+    readonly callId?: string;
+} | {
+    readonly type: "job.failed";
+} | {
+    readonly type: "run.settled";
+    /** Whether the run answered or not (model error, abort, …), with
+     *  the wire reason verbatim. Never infer success from the body. */
+    readonly outcome: RunSettledOutcome;
+});
 /** One notifier transport (ntfy, Signal, web push — core ships none). */
 export interface NotifierContribution {
     readonly name: string;
@@ -564,10 +669,12 @@ export type ActionResult = {
 };
 /**
  * One declared surface (spec §7.1, verbatim shape): the placement is
- * the generic parameter — `"view"` or `"panel"` (the settings sections
- * of §13.3 are a separate workstream).
+ * the generic parameter — `"view"`, `"panel"`, or `"settings"` (the
+ * §13.3 settings sections adapt to settings-placement surfaces; the
+ * host builds those — extensions declare `SettingsSectionDef`s, never
+ * `SurfaceDef<"settings">` directly).
  */
-export interface SurfaceDef<P extends "view" | "panel"> {
+export interface SurfaceDef<P extends "view" | "panel" | "settings"> {
     /** Unique within the extension. */
     readonly id: string;
     readonly title: string;
@@ -577,22 +684,51 @@ export interface SurfaceDef<P extends "view" | "panel"> {
     readonly sharedData?: boolean;
     /** Channels refetch data on this interval while visible (min 5000). */
     readonly refreshMs?: number;
-    /** §7.3; default: canonical JSON of params. */
-    instanceKey?(params: JsonParams): string;
+    /** §7.3; default: canonical JSON of params. The principal argument
+     *  lets principal-owned surfaces isolate their revision/action identity. */
+    instanceKey?(params: JsonParams, principal: Principal): string;
     render(ctx: SurfaceContext): Promise<SurfaceRenderResult>;
     data?(ctx: SurfaceContext): Promise<SurfaceDataResult>;
     readonly actions?: Readonly<Record<string, (ctx: SurfaceContext, payload: JsonParamValue) => Promise<ActionResult>>>;
 }
 /**
- * The `surfaces` field of a factory result (spec §7.1): declared views
- * and panels. Ids are unique across BOTH lists (one namespace — the
- * loader enforces it).
+ * One declared settings section (spec §13.3, verbatim shape): a static
+ * `settings`-placement form bound to the extension's settings object
+ * (`settings/<slug>.json`). The host adapts it to a surface under the
+ * extension's own `/v1/ext/<slug>/surfaces/` mount — core's own
+ * sections use the same renderer, under the reserved `core` slug.
+ */
+export interface SettingsSectionDef {
+    /** Unique within the extension. */
+    readonly id: string;
+    readonly title: string;
+    readonly icon?: IconName;
+    /** A root `form` block; the placement is `settings` (spec §5.7). */
+    readonly form: Tree;
+    /** Declared secrets, rendered as `secret` fields backed by the §7.7 secrets routes. */
+    readonly secrets?: readonly {
+        key: string;
+        label: string;
+        help?: string;
+    }[];
+    /** Only admins see and edit it; default true for shared sections.
+     *  A user-scope section is visible to every signed-in user unless this
+     *  is explicitly true. */
+    readonly admin?: boolean;
+    /** `"user"` reads/writes the calling user's settings; absent/`"server"`
+     *  keeps the extension's shared settings file. */
+    readonly scope?: "server" | "user";
+}
+/**
+ * The `surfaces` field of a factory result (spec §7.1): declared views,
+ * panels, and settings sections. Ids are unique across ALL THREE lists
+ * (one namespace — the loader enforces it).
  */
 export interface SurfacesContribution {
     readonly views?: readonly SurfaceDef<"view">[];
     readonly panels?: readonly SurfaceDef<"panel">[];
-    /** §13.3 settings sections — a separate workstream; declared for shape stability. */
-    readonly settings?: readonly never[];
+    /** §13.3 settings sections (UI-blocks U4 Task 3). */
+    readonly settings?: readonly SettingsSectionDef[];
 }
 /** One wire part of a `host.conversations.submit` input array. */
 export type SubmissionInputPart = {
@@ -620,8 +756,38 @@ export type WhenBusyMode = NonNullable<InputSubmissionDraft["whenBusy"]>;
  * factory body.
  */
 export interface SigrunHost {
+    /**
+     * Publish tools for ONE user (multi-user M2). Only factory results that
+     * declared `perUserTools: true` may call this; other extensions throw
+     * `perUserTools not declared`. An empty list uninstalls the user's entry.
+     * Core wraps every tool with a committed-owner check at execute time.
+     */
+    readonly tools: {
+        setUserTools(user: string, tools: readonly import("@earendil-works/pi-durable").ToolRegistration[]): void;
+    };
+    /** Connect to one declared per-user service; core owns its process lifecycle. */
+    readonly services: {
+        connect(name: string, user: string, ctx: HandlerContext): Promise<ServiceHandle>;
+    };
     /** The scoped extension-stores handle (your secrets/settings sections + raw data/cache/state paths). */
     readonly stores: {
+        /** One directory user's secrets/settings/paths, still scoped to your slug. */
+        user(user: string): {
+            readonly secrets: {
+                get(key: string): Promise<string | undefined>;
+                set(key: string, value: string): Promise<void>;
+                delete(key: string): Promise<void>;
+            };
+            readonly settings: {
+                get(): Promise<Record<string, unknown>>;
+                set(value: Record<string, unknown>): Promise<void>;
+            };
+            readonly paths: {
+                readonly data: string;
+                readonly state: string;
+                readonly cache: string;
+            };
+        };
         /** Your section of secrets.json. */
         readonly secrets: {
             get(key: string): Promise<string | undefined>;
@@ -653,7 +819,22 @@ export interface SigrunHost {
     }): Promise<boolean>;
     /** Mark a pending interaction expired/cancelled/skipped (extension-owned semantics). */
     settleInteraction(conversationId: ConversationId, callId: string, status: "skipped" | "expired" | "cancelled", context: HandlerContext): Promise<boolean>;
-    /** Read one interaction record (the poll loop's read). */
+    /**
+     * Inspect one interaction record WITHOUT consuming anything: returns
+     * the same stored projection as {@link SigrunHost.snapshotInteraction}
+     * (secret values stay `SECRET_MASK`), but never touches the one-shot
+     * secret-delivery `take` path. Safe to repeat; neither extends nor
+     * shortens secret TTL; creates, settles, and mutates nothing. Use for
+     * inspection/rendering (notifiers, outcome edits, correlation).
+     */
+    peekInteraction(conversationId: ConversationId, callId: string, context: HandlerContext): Promise<Readonly<InteractionRecord> | undefined>;
+    /**
+     * The OWNING extension's delivery read: the first applicable read of
+     * an answered secret record merges its raw secret values back ONCE;
+     * subsequent reads see the stored mask. Inspection-only callers must
+     * use {@link SigrunHost.peekInteraction} instead — a consuming read
+     * by a non-owner silently destroys the owner's one-shot delivery.
+     */
     snapshotInteraction(conversationId: ConversationId, callId: string, context: HandlerContext): Promise<Readonly<InteractionRecord> | undefined>;
     /** Fully replace one ambient surface's state (write = replacement); the key must be unowned or yours. */
     setAmbient(conversationId: ConversationId, record: {
@@ -662,7 +843,7 @@ export interface SigrunHost {
         readonly maxRows?: number;
         readonly overflow?: "drop" | "wrap" | "summarize";
         readonly refreshMs?: number;
-        readonly body?: AmbientBody;
+        readonly body?: Tree;
         readonly details?: JsonObject;
     }, context: HandlerContext): Promise<void>;
     /** Clear one ambient surface (empty replacement; keeps ownership). */
@@ -729,6 +910,8 @@ export interface SigrunHost {
         configure(id: ConversationId, opts: {
             readonly model?: string;
             readonly thinking?: ThinkingLevelWire;
+            /** Exact extension selection; another user's `<slug>@<user>` entry is rejected. */
+            readonly extensions?: readonly string[];
         }): Promise<void>;
         /** Admit one manual compaction task (gateway C4, the compact route's op). */
         compact(id: ConversationId): Promise<void>;
@@ -782,6 +965,25 @@ export interface SigrunHost {
         list(): Promise<readonly DirectoryUserWire[]>;
         get(user: string): Promise<DirectoryUserWire | undefined>;
     };
+    /**
+     * External identities linked to directory users (multi-user §11.3): the
+     * one table for chat senders (`chat:<channel>`) and login subjects
+     * (`login:<slug>:<id>`), shared with the gateway.
+     *
+     * Core owns the file — extensions go through this surface, never
+     * `accounts.json` directly. One link per `(provider, subject)`: a
+     * re-link to the same user is a no-op returning the existing record, a
+     * link to a DIFFERENT user rejects with an `Error` whose message starts
+     * `account_link_conflict:` (the message never names the current
+     * holder — extensions match the prefix, as they do `command_not_found:`).
+     * An unknown user rejects `unknown user "<user>"`.
+     */
+    readonly accounts: {
+        lookup(provider: string, subject: string): Promise<AccountLinkWire | undefined>;
+        link(provider: string, subject: string, user: string, via: AccountLinkWire["via"]): Promise<AccountLinkWire>;
+        unlink(provider: string, subject: string): Promise<boolean>;
+        listForUser(user: string): Promise<readonly AccountLinkWire[]>;
+    };
     /**
      * Resolve one principal's access to one shared resource (the whole
      * sharing contract for extension-owned records — core stores nothing
@@ -841,12 +1043,18 @@ export interface SigrunHost {
  * begins reading each when its task lands.
  */
 export interface SigrunExtensionResult extends SigrunLifecycleHandlers {
+    /** Long-lived per-user sibling processes, launched and supervised by core. */
+    readonly userServices?: readonly UserService[];
+    /** Declare the per-user tool surface (`host.tools.setUserTools`). */
+    readonly perUserTools?: boolean;
     /** The pi-durable `Extension` to install; its declared name is the slug source. */
     readonly extension?: Extension;
     /** The contributor-only identity (required when contributing without an `extension`). */
     readonly name?: string;
     /** Provider contributions, merged into the boot model catalog (last-registered-wins, collisions recorded). */
     readonly providers?: readonly ProviderContribution[];
+    /** External identity providers; core qualifies ids as `login:<slug>:<id>`. */
+    readonly loginProviders?: readonly LoginProviderContribution[];
     /** Webui-bundle contributions; each `dir` anchors at the extension ENTRY's directory. */
     readonly webuiBundles?: readonly WebuiBundleContribution[];
     /** The surface's health producer, aggregated into `/v1/meta` `health` (any `"degraded"` degrades). */

package/dist/harness/ambient.js

@@ -1,8 +1,9 @@
 /**
- * The ambient seam (spec: docs/approval-ux-seams.md, "Ambient surfaces"):
- * core-owned, channel-neutral records for persistent read-mostly state —
- * statusline slots and panel widgets — written by extensions through the
- * host context and rendered by channels generically.
+ * The ambient seam (spec: docs/approval-ux-seams.md, "Ambient surfaces";
+ * the block mapping: UI-blocks design §9.2): core-owned,
+ * channel-neutral records for persistent read-mostly state — statusline
+ * slots and panel widgets — written by extensions through the host
+ * context and rendered by channels generically.
  *
  * SPLIT (build-and-webui Task 1): the canonical TYPE declarations live in
  * the `@sigrun/shared` package (`shared/src/ambient.ts` — the records ride
@@ -16,10 +17,22 @@
  * not silent composition — the pi-zentui chrome-skin lesson).
  *
  * Layering mirrors the interaction seam: strict envelope (key, place,
- * budget, refresh, expires) around a body composed only from the closed
- * ambient primitives (line, rows, gauge, ledger), with opaque `details`.
+ * budget, refresh, expires) around a block-tree body (placement
+ * `ambient`; `status`/`footer` allow one line), with opaque `details`.
+ * Legacy-shaped bodies FAIL with paths (ruling 16).
  */
 import { defineDoc, defineDocFamily } from "@earendil-works/pi-durable";
+import { validateTree } from "../blocks/validate.js";
+/**
+ * Narrow a stored record to the public wire record. SAFETY: the two
+ * shapes are identical at runtime — a stored body passed `validateTree`
+ * (placement `ambient`) at write time, and a validated tree IS the JSON
+ * the mirror describes; the cast only restores the type-level naming
+ * `JsonObject`-erasure removed.
+ */
+export function asAmbientRecord(value) {
+    return value;
+}
 /**
  * The ambient record family: one record per surface key, per conversation.
  * (Session-scoped statuslines that outlive one conversation are a v2
@@ -48,9 +61,12 @@ export const AmbientOwnersDoc = defineDoc({
 });
 const PLACES = new Set(["status", "footer", "panel"]);
 const OVERFLOWS = new Set(["drop", "wrap", "summarize"]);
-const FORMATS = new Set(["compact", "usd", "percent"]);
-const ZONES = new Set(["left", "middle", "right"]);
-/** Structural validation of one ambient record. Returns the error text or null. */
+/**
+ * Structural validation of one ambient record: the envelope's own checks,
+ * then the body tree through `validateTree({placement: "ambient"})` with
+ * the one-line rule for `status`/`footer` (§9.2). Returns the error text
+ * (with the tree paths) or null.
+ */
 export function validateAmbient(value) {
     if (typeof value !== "object" || value === null) {
         return "ambient record must be an object";
@@ -80,182 +96,20 @@ export function validateAmbient(value) {
     const body = r.body;
     if (body === undefined)
         return null; // an empty write clears the surface
-    if (typeof body !== "object" || body === null) {
-        return "body must be an object";
-    }
-    const b = body;
-    const known = new Set(["line", "rows", "gauge", "ledger"]);
-    const unknownKey = Object.keys(b).find((k) => !known.has(k));
-    if (unknownKey !== undefined) {
-        return `body.${unknownKey} is outside the closed primitives (move it to details)`;
-    }
-    if (b.line !== undefined) {
-        const problem = validateLine(b.line);
-        if (problem !== null)
-            return problem;
-    }
-    if (b.rows !== undefined) {
-        if (!Array.isArray(b.rows))
-            return "body.rows must be an array";
-        for (const row of b.rows) {
-            const problem = validateRow(row);
-            if (problem !== null)
-                return problem;
-        }
-    }
-    if (b.gauge !== undefined) {
-        const problem = validateGauge(b.gauge);
-        if (problem !== null)
-            return problem;
-    }
-    if (b.ledger !== undefined) {
-        if (!Array.isArray(b.ledger))
-            return "body.ledger must be an array";
-        for (const e of b.ledger) {
-            const problem = validateLedgerEntry(e);
-            if (problem !== null)
-                return problem;
-        }
-    }
-    return null;
-}
-function validateLine(value) {
-    if (typeof value !== "object" || value === null)
-        return "line must be an object";
-    const l = value;
-    if (l.text === undefined && l.segments === undefined) {
-        return "line needs text or segments";
-    }
-    if (l.text !== undefined && typeof l.text !== "string") {
-        return "line.text must be a string";
-    }
-    if (l.segments !== undefined) {
-        if (!Array.isArray(l.segments))
-            return "line.segments must be an array";
-        for (const s of l.segments) {
-            if (typeof s !== "object" || s === null)
-                return "segment must be an object";
-            const seg = s;
-            if (typeof seg.id !== "string" || seg.id.length === 0) {
-                return "segment.id must be a non-empty string";
-            }
-            if (typeof seg.text !== "string")
-                return "segment.text must be a string";
-            if (seg.place !== undefined && !ZONES.has(String(seg.place))) {
-                return `segment.place must be one of left|middle|right (got ${String(seg.place)})`;
-            }
-        }
-    }
-    return null;
-}
-function validateRow(value) {
-    if (typeof value !== "object" || value === null)
-        return "row must be an object";
-    const r = value;
-    if (typeof r.id !== "string" || r.id.length === 0) {
-        return "row.id must be a non-empty string";
-    }
-    if (typeof r.label !== "string")
-        return "row.label must be a string";
-    if (r.status !== undefined && typeof r.status !== "string") {
-        return "row.status must be a string";
-    }
-    if (r.severity !== undefined &&
-        r.severity !== 0 &&
-        r.severity !== 1 &&
-        r.severity !== 2) {
-        return "row.severity must be 0, 1, or 2";
-    }
-    if (r.quiet !== undefined && typeof r.quiet !== "boolean") {
-        return "row.quiet must be a boolean";
-    }
-    if (r.detail !== undefined && typeof r.detail !== "string") {
-        return "row.detail must be a string";
-    }
-    if (r.depth !== undefined && typeof r.depth !== "number") {
-        return "row.depth must be a number";
-    }
-    if (r.deps !== undefined && !Array.isArray(r.deps)) {
-        return "row.deps must be an array of ids";
-    }
-    if (Array.isArray(r.deps) && r.deps.some((d) => typeof d !== "string")) {
-        return "row.deps must be an array of ids";
-    }
-    if (r.spinnerLabel !== undefined && typeof r.spinnerLabel !== "string") {
-        return "row.spinnerLabel must be a string";
-    }
-    if (r.metrics !== undefined) {
-        const problem = validateMetrics(r.metrics);
-        if (problem !== null)
-            return problem;
-    }
-    return null;
-}
-function validateMetrics(value) {
-    if (typeof value !== "object" || value === null)
-        return "metrics must be an object";
-    const m = value;
-    for (const k of ["tokens", "cost", "current", "total", "completed"]) {
-        if (m[k] !== undefined && typeof m[k] !== "number") {
-            return `metrics.${k} must be a number`;
-        }
-    }
-    if (m.format !== undefined && !FORMATS.has(String(m.format))) {
-        return `metrics.format must be one of compact|usd|percent (got ${String(m.format)})`;
-    }
-    return null;
-}
-function validateGauge(value) {
-    if (typeof value !== "object" || value === null)
-        return "gauge must be an object";
-    const g = value;
-    if (typeof g.label !== "string")
-        return "gauge.label must be a string";
-    if (g.percent !== undefined && typeof g.percent !== "number") {
-        return "gauge.percent must be a number";
-    }
-    if (g.phase !== undefined && typeof g.phase !== "string") {
-        return "gauge.phase must be a string";
-    }
-    if (g.elapsedMs !== undefined && typeof g.elapsedMs !== "number") {
-        return "gauge.elapsedMs must be a number";
-    }
-    if (g.recentOutput !== undefined && !Array.isArray(g.recentOutput)) {
-        return "gauge.recentOutput must be an array of strings";
-    }
-    if (Array.isArray(g.recentOutput) && g.recentOutput.some((l) => typeof l !== "string")) {
-        return "gauge.recentOutput must be an array of strings";
-    }
-    if (g.checks !== undefined && !Array.isArray(g.checks)) {
-        return "gauge.checks must be row-shaped";
-    }
-    if (Array.isArray(g.checks)) {
-        for (const row of g.checks) {
-            const problem = validateRow(row);
-            if (problem !== null)
-                return `gauge.checks: ${problem}`;
-        }
-    }
-    return null;
-}
-function validateLedgerEntry(value) {
-    if (typeof value !== "object" || value === null)
-        return "ledger entry must be an object";
-    const e = value;
-    if (typeof e.id !== "string" || e.id.length === 0) {
-        return "ledger.id must be a non-empty string";
-    }
-    if (typeof e.at !== "number")
-        return "ledger.at must be a number";
-    if (typeof e.kind !== "string")
-        return "ledger.kind must be a string";
-    if (typeof e.summary !== "string")
-        return "ledger.summary must be a string";
-    if (e.detail !== undefined && !Array.isArray(e.detail)) {
-        return "ledger.detail must be an array of strings";
-    }
-    if (Array.isArray(e.detail) && e.detail.some((d) => typeof d !== "string")) {
-        return "ledger.detail must be an array of strings";
+    // Ruling 16 (no compatibility layer): legacy-shaped bodies (objects
+    // keyed line/rows/gauge/ledger rather than {v, root}) fail HERE, with
+    // the path — a tree is {v, root}.
+    const result = validateTree(body, {
+        placement: "ambient",
+        ambientPlace: r.place,
+    });
+    if (!result.ok) {
+        const first = result.errors[0];
+        if (first === undefined)
+            return "body must be a block tree";
+        // The tree-relative path joins the record's field ("body.root…")
+        // so the error names where the record is wrong, not just the tree.
+        return `body is not a valid ambient tree: body.${first.path} ${first.message}`;
     }
     return null;
 }