@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/documents/conversions.ts

@@ -0,0 +1,402 @@
+// A stored document's history as data: each conversion is a guarded, pure rewrite of the raw JSON a store reads, run
+// before the schema on every read. The guard makes a conversion a no-op on a document already past it, so running the
+// whole list over a document from any era converges on today's shape without the document carrying a version, and
+// every door old bytes arrive through (an update, a bundle, a git revert, a history restore) is covered by the read.
+// Two rules keep that sound, and the vocabulary below only offers moves that obey them: a change of meaning ships as a
+// rename, never as a new reading of the same key; and a retired key is never reused.
+
+// The only thing a conversion rewrites: one JSON object, never mutated, replaced along the branch that changed.
+export type JsonObject = Record<string, unknown>;
+
+export const isJsonObject = (value: unknown): value is JsonObject => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// What one conversion did at one place in a document, for the ledger and the pre-flight plan. `at` is the path inside
+// the document ("" is the document itself, "[3]" its fourth entry, "trigger" a nested object).
+export interface ConversionChange {
+    readonly conversion: string;
+    readonly at: string;
+    readonly detail?: string;
+}
+
+interface ConversionBase<Kind extends string> {
+    readonly kind: Kind;
+    // One line a person reads in a plan or the ledger: "renames agentRunModel to agentRunModels".
+    readonly describe: string;
+}
+
+export interface RenameConversion<From extends string = string, To extends string = string> extends ConversionBase<"rename"> {
+    readonly from: From;
+    readonly to: To;
+}
+
+export interface DropConversion<Key extends string = string> extends ConversionBase<"drop"> {
+    readonly key: Key;
+}
+
+export interface RetypeConversion<Key extends string = string, In = unknown, Out = unknown> extends ConversionBase<"retype"> {
+    readonly key: Key;
+    // True only for the OLD representation; a converted value must fail it, or the conversion would run twice.
+    readonly guard: (value: unknown) => value is In;
+    // Method syntax on purpose: the guard proves `In` at runtime, so a union of conversions may hold any input type.
+    convert(value: In): Out;
+}
+
+export interface MapValueConversion<Key extends string = string, Mapping extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>>
+    extends ConversionBase<"mapValue"> {
+    readonly key: Key;
+    readonly mapping: Mapping;
+}
+
+export interface PinDefaultConversion<Key extends string = string, Value = unknown> extends ConversionBase<"pinDefault"> {
+    readonly key: Key;
+    readonly value: Value;
+}
+
+export interface TransformConversion<In extends JsonObject = JsonObject, Out extends JsonObject = JsonObject> extends ConversionBase<"transform"> {
+    // True only for the old shape; the output must fail it.
+    readonly applies: (value: JsonObject) => value is In;
+    // Method syntax on purpose, as for retype.
+    convert(value: In): Out;
+}
+
+// Several keys become one (three optional fields folded into a ladder): the old keys go, the new one takes the place of
+// the first of them.
+export interface FoldConversion<From extends string = string, Into extends string = string, Out = unknown> extends ConversionBase<"fold"> {
+    readonly from: readonly From[];
+    readonly into: Into;
+    // True only for the old shape; the folded output must fail it.
+    readonly applies: (value: JsonObject) => boolean;
+    // Method syntax on purpose, as for retype. `whole` is the object before folding, for a value derived from elsewhere.
+    convert(fields: Readonly<Partial<Record<From, unknown>>>, whole: JsonObject): Out;
+}
+
+// Entries of a list this version withdrew (a capability kind that no longer exists): removed, each one recorded. Only
+// for entries nothing can convert; one with a successor is converted instead (mapValue, fold).
+export interface RetireEntriesConversion<Retired = unknown> extends ConversionBase<"retireEntries"> {
+    readonly isRetired: (entry: unknown) => entry is Retired;
+}
+
+export interface AtConversion<Path extends string = string, Inner = unknown> extends ConversionBase<"at"> {
+    // Dotted keys; `*` is every element of an array or every value of an object.
+    readonly path: Path;
+    readonly inner: Inner;
+}
+
+export type Conversion =
+    | RenameConversion
+    | DropConversion
+    | RetypeConversion
+    | MapValueConversion
+    | PinDefaultConversion
+    | TransformConversion
+    | FoldConversion
+    | RetireEntriesConversion
+    | AtConversion<string, Conversion>;
+
+// Where a document's conversions apply: the document itself, each entry of a top-level array, or each value of a
+// top-level object keyed by id.
+export type Granularity = "object" | "entries" | "record";
+
+// The value a conversion leaves in a change record, short enough for a log line.
+const glimpse = (value: unknown): string => {
+    // String() over the result, since JSON.stringify answers undefined for a value JSON cannot spell.
+    const spelled = String(JSON.stringify(value));
+    return spelled.length > 80 ? `${spelled.slice(0, 77)}…` : spelled;
+};
+
+// Keeps key order: a renamed key takes its predecessor's place, so a tracked file's diff shows one line changing.
+const renamedKey = (target: JsonObject, from: string, to: string): JsonObject =>
+    Object.fromEntries(Object.entries(target).map(([key, value]) => [key === from ? to : key, value]));
+
+const withoutKey = (target: JsonObject, key: string): JsonObject => Object.fromEntries(Object.entries(target).filter(([name]) => name !== key));
+
+export const rename = <const From extends string, const To extends string>(from: From, to: To): RenameConversion<From, To> => ({
+    kind: "rename",
+    describe: `renames ${from} to ${to}`,
+    from,
+    to,
+});
+
+export const drop = <const Key extends string>(key: Key): DropConversion<Key> => ({ kind: "drop", describe: `drops ${key}`, key });
+
+export const retype = <const Key extends string, In, Out>(
+    key: Key,
+    guard: (value: unknown) => value is In,
+    convert: (value: In) => Out,
+    describe = `converts ${key} to its new form`,
+): RetypeConversion<Key, In, Out> => ({ kind: "retype", describe, key, guard, convert });
+
+// A mapped value that is itself a key of the mapping would be mapped again on the next read.
+export const mapValue = <const Key extends string, const Mapping extends Readonly<Record<string, unknown>>>(
+    key: Key,
+    mapping: Mapping,
+): MapValueConversion<Key, Mapping> => {
+    const cyclic = Object.values(mapping).filter((mapped): mapped is string => typeof mapped === "string" && Object.hasOwn(mapping, mapped));
+    if (cyclic.length > 0) {
+        throw new Error(`mapValue(${key}) maps onto its own keys (${cyclic.join(", ")}), so it would not settle`);
+    }
+    return { kind: "mapValue", describe: `converts ${key} from its old values`, key, mapping };
+};
+
+// For a changed schema default: an existing file that never set the key keeps the old behavior, a new one gets the new.
+export const pinDefault = <const Key extends string, const Value>(key: Key, value: Value): PinDefaultConversion<Key, Value> => ({
+    kind: "pinDefault",
+    describe: `keeps the earlier default for ${key}`,
+    key,
+    value,
+});
+
+export const transform = <In extends JsonObject, Out extends JsonObject>(
+    describe: string,
+    applies: (value: JsonObject) => value is In,
+    convert: (value: In) => Out,
+): TransformConversion<In, Out> => ({ kind: "transform", describe, applies, convert });
+
+export const fold = <const From extends string, const Into extends string, Out>(
+    describe: string,
+    shape: {
+        readonly from: readonly From[];
+        readonly into: Into;
+        readonly applies: (value: JsonObject) => boolean;
+        readonly convert: (fields: Readonly<Partial<Record<From, unknown>>>, whole: JsonObject) => Out;
+    },
+): FoldConversion<From, Into, Out> => ({ kind: "fold", describe, from: shape.from, into: shape.into, applies: shape.applies, convert: shape.convert });
+
+// Every key a schema once had and no longer has, dropped: retired, not from the future, so passthrough stops carrying it
+// and no later schema may reuse the name. A tuple, so the type-level replay sees each key.
+export const dropAll = <const Keys extends readonly string[]>(keys: Keys): { readonly [I in keyof Keys]: DropConversion<Keys[I] & string> } =>
+    keys.map((key) => drop(key)) as unknown as { readonly [I in keyof Keys]: DropConversion<Keys[I] & string> };
+
+type Nested<Path extends string, History extends readonly Conversion[], Entries extends boolean> = {
+    readonly [I in keyof History]: History[I] extends RetireEntriesConversion
+        ? AtConversion<Path, History[I]>
+        : AtConversion<Entries extends true ? `${Path}.*` : Path, History[I]>;
+};
+
+// One document's history applied where another document carries it (a definition's `settings` table, a bundle's
+// embedded definition): one declaration, every carrier. `entries` for a carried list, whose entries each convert and
+// whose retired entries leave the list.
+export const nested = <const Path extends string, const History extends readonly Conversion[], const Entries extends boolean = false>(
+    path: Path,
+    history: History,
+    entries?: Entries,
+): Nested<Path, History, Entries> =>
+    history.map((conversion) => at(conversion.kind === "retireEntries" || entries !== true ? path : `${path}.*`, conversion)) as unknown as Nested<
+        Path,
+        History,
+        Entries
+    >;
+
+export const retireEntries = <Retired>(describe: string, isRetired: (entry: unknown) => entry is Retired): RetireEntriesConversion<Retired> => ({
+    kind: "retireEntries",
+    describe,
+    isRetired,
+});
+
+export const at = <const Path extends string, const Inner extends Conversion>(path: Path, inner: Inner): AtConversion<Path, Inner> => ({
+    kind: "at",
+    describe: `${inner.describe} under ${path}`,
+    path,
+    inner,
+});
+
+type Report = (change: ConversionChange) => void;
+
+// One conversion over one object: the same object back, by reference, when its guard says it does not apply.
+const applyToObject = (conversion: Conversion, target: JsonObject, where: string, report: Report): JsonObject => {
+    switch (conversion.kind) {
+        case "rename": {
+            if (!Object.hasOwn(target, conversion.from)) {
+                return target;
+            }
+            if (!Object.hasOwn(target, conversion.to)) {
+                report({ conversion: conversion.describe, at: where });
+                return renamedKey(target, conversion.from, conversion.to);
+            }
+            // Both names holding the same value is a file written under both on purpose (a rename's grace window keeps
+            // the old name for a build that only knows it): nothing to report, nothing for the file to lose.
+            if (JSON.stringify(target[conversion.from]) === JSON.stringify(target[conversion.to])) {
+                return withoutKey(target, conversion.from);
+            }
+            // Both names present and different (an old key back through git, or an older build's edit after the window):
+            // the current name wins, and what the older one held is recorded rather than lost without a word.
+            report({ conversion: conversion.describe, at: where, detail: `kept ${conversion.to}; ${conversion.from} held ${glimpse(target[conversion.from])}` });
+            return withoutKey(target, conversion.from);
+        }
+        case "drop": {
+            if (!Object.hasOwn(target, conversion.key)) {
+                return target;
+            }
+            report({ conversion: conversion.describe, at: where, detail: `it held ${glimpse(target[conversion.key])}` });
+            return withoutKey(target, conversion.key);
+        }
+        case "retype": {
+            const value = target[conversion.key];
+            if (!Object.hasOwn(target, conversion.key) || !conversion.guard(value)) {
+                return target;
+            }
+            report({ conversion: conversion.describe, at: where });
+            return { ...target, [conversion.key]: conversion.convert(value) };
+        }
+        case "mapValue": {
+            const value = target[conversion.key];
+            if (typeof value !== "string" || !Object.hasOwn(conversion.mapping, value)) {
+                return target;
+            }
+            report({ conversion: conversion.describe, at: where, detail: `${glimpse(value)} became ${glimpse(conversion.mapping[value])}` });
+            return { ...target, [conversion.key]: conversion.mapping[value] };
+        }
+        case "pinDefault": {
+            if (Object.hasOwn(target, conversion.key)) {
+                return target;
+            }
+            report({ conversion: conversion.describe, at: where });
+            return { ...target, [conversion.key]: conversion.value };
+        }
+        case "transform": {
+            if (!conversion.applies(target)) {
+                return target;
+            }
+            report({ conversion: conversion.describe, at: where });
+            return conversion.convert(target);
+        }
+        case "fold":
+            return applyFold(conversion, target, where, report);
+        case "retireEntries":
+            // An object is not a list; retiring acts on the list holding it (applyOne, applyAt).
+            return target;
+        case "at":
+            return applyAt(conversion.inner, conversion.path.split("."), target, where, report) as JsonObject;
+    }
+};
+
+const applyFold = (conversion: FoldConversion, target: JsonObject, where: string, report: Report): JsonObject => {
+    if (!conversion.applies(target)) {
+        return target;
+    }
+    const folded = new Set<string>(conversion.from);
+    const fields = Object.fromEntries(Object.entries(target).filter(([key]) => folded.has(key)));
+    const entries = Object.entries(target);
+    const first = entries.findIndex(([key]) => folded.has(key));
+    const kept = entries.filter(([key]) => !folded.has(key) && key !== conversion.into);
+    kept.splice(first === -1 ? kept.length : Math.min(first, kept.length), 0, [conversion.into, conversion.convert(fields, target)]);
+    report({ conversion: conversion.describe, at: where });
+    return Object.fromEntries(kept);
+};
+
+// Removes a list's withdrawn entries, by index for an array and by key for an object keyed by id.
+const retireFrom = (conversion: RetireEntriesConversion, container: unknown, where: string, report: Report): unknown => {
+    const retired = (entry: unknown, place: string): boolean => {
+        if (!conversion.isRetired(entry)) {
+            return false;
+        }
+        report({ conversion: conversion.describe, at: place, detail: glimpse(entry) });
+        return true;
+    };
+    if (Array.isArray(container)) {
+        const kept = container.filter((entry, index) => !retired(entry, joinWhere(where, `[${index}]`)));
+        return kept.length === container.length ? container : kept;
+    }
+    if (!isJsonObject(container)) {
+        return container;
+    }
+    const kept = Object.entries(container).filter(([key, entry]) => !retired(entry, joinWhere(where, key)));
+    return kept.length === Object.keys(container).length ? container : Object.fromEntries(kept);
+};
+
+const joinWhere = (where: string, segment: string): string => (segment.startsWith("[") || where === "" ? `${where}${segment}` : `${where}.${segment}`);
+
+// Every element of an array or every value of an object, rebuilt only where one of them changed.
+const applyToEach = (visit: (value: unknown, where: string) => unknown, container: unknown, where: string): unknown => {
+    if (Array.isArray(container)) {
+        const next = container.map((value, index) => visit(value, joinWhere(where, `[${index}]`)));
+        return next.some((value, index) => value !== container[index]) ? next : container;
+    }
+    if (!isJsonObject(container)) {
+        return container;
+    }
+    const entries = Object.entries(container);
+    const next = entries.map(([key, value]) => [key, visit(value, joinWhere(where, key))] as const);
+    return next.some(([, value], index) => value !== entries[index]?.[1]) ? Object.fromEntries(next) : container;
+};
+
+const applyAt = (inner: Conversion, segments: readonly string[], value: unknown, where: string, report: Report): unknown => {
+    const [head, ...rest] = segments;
+    if (head === undefined) {
+        if (inner.kind === "retireEntries") {
+            return retireFrom(inner, value, where, report);
+        }
+        return isJsonObject(value) ? applyToObject(inner, value, where, report) : value;
+    }
+    if (head === "*") {
+        return applyToEach((element, elementWhere) => applyAt(inner, rest, element, elementWhere, report), value, where);
+    }
+    if (!isJsonObject(value) || !Object.hasOwn(value, head)) {
+        return value;
+    }
+    const child = value[head];
+    const next = applyAt(inner, rest, child, joinWhere(where, head), report);
+    return next === child ? value : { ...value, [head]: next };
+};
+
+// One conversion over a whole document, at its granularity.
+const applyOne = (conversion: Conversion, granularity: Granularity, value: unknown, report: Report): unknown => {
+    if (conversion.kind === "retireEntries" && granularity !== "object") {
+        return retireFrom(conversion, value, "", report);
+    }
+    if (granularity === "object") {
+        return isJsonObject(value) ? applyToObject(conversion, value, "", report) : value;
+    }
+    const container = granularity === "entries" ? Array.isArray(value) : isJsonObject(value);
+    return container ? applyToEach((entry, where) => (isJsonObject(entry) ? applyToObject(conversion, entry, where, report) : entry), value, "") : value;
+};
+
+export class ConversionError extends Error {
+    readonly conversion: string;
+
+    constructor(conversion: string, cause: unknown) {
+        super(`conversion "${conversion}" failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = "ConversionError";
+        this.conversion = conversion;
+    }
+}
+
+// Every conversion in declaration order; a throw is named after the conversion that threw, not the last that reported.
+const applyAll = (conversions: readonly Conversion[], granularity: Granularity, raw: unknown, report: Report): unknown => {
+    let value = raw;
+    for (const conversion of conversions) {
+        try {
+            value = applyOne(conversion, granularity, value, report);
+        } catch (error) {
+            throw new ConversionError(conversion.describe, error);
+        }
+    }
+    return value;
+};
+
+export interface Converted {
+    readonly value: unknown;
+    readonly changes: readonly ConversionChange[];
+}
+
+// `checkSettles` runs the list a second time over its own output and fails a conversion that is not a no-op there: what
+// a development build turns on, so the first read that reaches such a conversion fails instead of every read after it
+// quietly rewriting the file.
+export const convertDocument = (conversions: readonly Conversion[], granularity: Granularity, raw: unknown, checkSettles = false): Converted => {
+    if (conversions.length === 0) {
+        return { value: raw, changes: [] };
+    }
+    const changes: ConversionChange[] = [];
+    const value = applyAll(conversions, granularity, raw, (change) => changes.push(change));
+    if (checkSettles && changes.length > 0) {
+        const again: ConversionChange[] = [];
+        const settled = applyAll(conversions, granularity, value, (change) => again.push(change));
+        if (settled !== value || again.length > 0) {
+            throw new ConversionError(again[0]?.conversion ?? "unknown", new Error("it changed its own output, so it would run on every read"));
+        }
+    }
+    return { value, changes };
+};
+
+// A document's conversions as one-line descriptions, for a plan that has nothing to convert but still names the chain.
+export const describeConversions = (conversions: readonly Conversion[]): string[] => conversions.map((conversion) => conversion.describe);

package/src/documents/index.ts

@@ -0,0 +1,5 @@
+// Stored-document evolution shared by everything that keeps a file across versions: the daemon's stores, and an
+// extension's own files through `sandboxDocument` (@intentic/extension-api). The vocabulary of guarded, pure
+// conversions, and the passthrough that keeps what a build does not know on its writes.
+export * from "./conversions.js";
+export * from "./passthrough.js";

package/src/documents/passthrough.ts

@@ -0,0 +1,139 @@
+import { isJsonObject, type JsonObject } from "./conversions.js";
+
+// Carries into a write what the file held that this build's parse dropped: keys a newer build added, and entries this
+// build cannot read. Loose schemas already let an older build READ a newer file; without this, its next write would
+// quietly delete everything it did not understand, so a rollback cost the newer version's data on the first save.
+// What counts as "unknown" is exactly what parse stripped, so a key this build knows and the change removed stays gone,
+// and a key a conversion retired (drop, rename) was removed before parse and is never carried.
+
+// A key whose value names which arm of a union an object is: an object that switched arms carries nothing across, since
+// the old arm's extra keys mean nothing on the new one.
+const DISCRIMINATORS = ["kind", "type"] as const;
+
+const sameArm = (parsed: JsonObject, updated: JsonObject): boolean =>
+    DISCRIMINATORS.every((key) => typeof parsed[key] !== "string" || parsed[key] === updated[key]);
+
+// Which keys name an entry, tried in order: most entries carry `id`, a few (workflow runs) their own.
+export type IdKeys = readonly string[];
+const DEFAULT_ID_KEYS: IdKeys = ["id"];
+
+const carryObject = (raw: JsonObject, parsed: JsonObject, updated: JsonObject, idKeys: IdKeys): JsonObject => {
+    if (!sameArm(parsed, updated)) {
+        return updated;
+    }
+    let result: JsonObject | undefined;
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Object.hasOwn(updated, key)) {
+            // Stripped by parse and not set by the change: a key from a newer build (or a typo, which stays reported).
+            if (!Object.hasOwn(parsed, key)) {
+                result ??= { ...updated };
+                result[key] = value;
+            }
+            continue;
+        }
+        if (Object.hasOwn(parsed, key)) {
+            const carried = carryUnknown(value, parsed[key], updated[key], idKeys);
+            if (carried !== updated[key]) {
+                result ??= { ...updated };
+                result[key] = carried;
+            }
+        }
+    }
+    return result ?? updated;
+};
+
+const idOf = (value: unknown, idKeys: IdKeys): string | undefined => {
+    if (!isJsonObject(value)) {
+        return undefined;
+    }
+    const id = idKeys.map((key) => value[key]).find((candidate) => typeof candidate === "string");
+    return typeof id === "string" ? id : undefined;
+};
+
+// Pairs each written element with the raw element it came from: by reference when the change kept the parsed object,
+// by id when it rebuilt it. Only a parse that kept every element lines raw up with parsed by position.
+const carryArray = (raw: readonly unknown[], parsed: readonly unknown[], updated: readonly unknown[], idKeys: IdKeys): readonly unknown[] => {
+    if (raw.length !== parsed.length) {
+        return updated;
+    }
+    const rawOfParsed = new Map<unknown, unknown>();
+    const indexOfId = new Map<string, number>();
+    parsed.forEach((element, index) => {
+        if (typeof element === "object" && element !== null) {
+            rawOfParsed.set(element, raw[index]);
+        }
+        const id = idOf(element, idKeys);
+        if (id !== undefined) {
+            indexOfId.set(id, index);
+        }
+    });
+    let result: unknown[] | undefined;
+    updated.forEach((element, index) => {
+        const byId = indexOfId.get(idOf(element, idKeys) ?? "");
+        const [source, before] = rawOfParsed.has(element) ? [rawOfParsed.get(element), element] : byId === undefined ? [undefined, undefined] : [raw[byId], parsed[byId]];
+        if (source === undefined) {
+            return;
+        }
+        const carried = carryUnknown(source, before, element, idKeys);
+        if (carried !== element) {
+            result ??= [...updated];
+            result[index] = carried;
+        }
+    });
+    return result ?? updated;
+};
+
+// `raw` is the file as read (after conversions), `parsed` what the schema made of it, `updated` what the change returns.
+// Answers `updated` itself, by reference, when nothing needs carrying.
+export const carryUnknown = (raw: unknown, parsed: unknown, updated: unknown, idKeys: IdKeys = DEFAULT_ID_KEYS): unknown => {
+    if (isJsonObject(raw) && isJsonObject(parsed) && isJsonObject(updated)) {
+        return carryObject(raw, parsed, updated, idKeys);
+    }
+    if (Array.isArray(raw) && Array.isArray(parsed) && Array.isArray(updated)) {
+        return carryArray(raw, parsed, updated, idKeys);
+    }
+    return updated;
+};
+
+// An entry list read one entry at a time: the entries this build can use, the raw entries lined up with them, and the
+// ones it could not read, each at the index it held.
+export interface EntryRead<E> {
+    readonly entries: E[];
+    readonly aligned: readonly unknown[];
+    readonly quarantined: readonly { readonly index: number; readonly entry: unknown }[];
+}
+
+export const readEntries = <E>(raw: readonly unknown[], parseEntry: (entry: unknown) => E | undefined): EntryRead<E> => {
+    const entries: E[] = [];
+    const aligned: unknown[] = [];
+    const quarantined: { index: number; entry: unknown }[] = [];
+    raw.forEach((entry, index) => {
+        const parsed = parseEntry(entry);
+        if (parsed === undefined) {
+            quarantined.push({ index, entry });
+            return;
+        }
+        entries.push(parsed);
+        aligned.push(entry);
+    });
+    return { entries, aligned, quarantined };
+};
+
+// Puts the entries this build could not read back into what it writes, near where they were; one the write now holds a
+// same-id entry for was replaced on purpose and stays out.
+export const reemitQuarantined = (
+    updated: readonly unknown[],
+    quarantined: EntryRead<unknown>["quarantined"],
+    idKeys: IdKeys = DEFAULT_ID_KEYS,
+): readonly unknown[] => {
+    const written = new Set(updated.map((entry) => idOf(entry, idKeys)).filter((id) => id !== undefined));
+    const kept = quarantined.filter(({ entry }) => !written.has(idOf(entry, idKeys) ?? "\u0000"));
+    if (kept.length === 0) {
+        return updated;
+    }
+    const result = [...updated];
+    for (const { index, entry } of kept) {
+        result.splice(Math.min(index, result.length), 0, entry);
+    }
+    return result;
+};

package/src/events/agent-events.ts

@@ -4,6 +4,7 @@ import { LandConflictSchema } from "../schemas/agents.js";
 import { ContextTrimSchema } from "../schemas/context-trim.js";
 import { RateLimitInfoSchema } from "../schemas/providers/claude-gate.js";
 import { FastModeStateSchema } from "../schemas/providers/fast-mode.js";
+import { PromptCacheOpeningSchema, PromptFingerprintSchema } from "../schemas/keep-warm.js";
 import { AgentReplySchema, UsageWindowSchema } from "../schemas/providers/plan-limits.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
@@ -50,7 +51,8 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // message to be drawn beside, so this is the only place the reader can learn the turn ran thin.
     ContextTrimSchema.extend({ kind: z.literal("context_trim") }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
-    z.object({ kind: z.literal("init"), model: z.string() }),
+    // `prompt` names the parts the cache is keyed on, so a later turn can say which of them changed.
+    z.object({ kind: z.literal("init"), model: z.string(), prompt: PromptFingerprintSchema.optional() }),
     // The pre-turn snapshot id, emitted once before the provider stream so the client can offer
     // restore-to-before-this-message. Absent on an isolated turn or when the tree was already clean.
     // `index` is the message's position in the transcript, which the rewind route addresses by; absent on a turn with
@@ -139,7 +141,13 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         cacheCreationTokens: z.number().optional(),
         durationMs: z.number().optional(),
         numTurns: z.number().optional(),
+        // The stream's first request only; a sum of frames keeps the first frame's, never adds them.
+        openingCacheReadTokens: z.number().optional(),
+        openingCacheCreationTokens: z.number().optional(),
+        promptFingerprint: z.string().optional(),
     }),
+    // What the turn's first request found in the prompt cache, sent as soon as it is known.
+    PromptCacheOpeningSchema.extend({ kind: z.literal("prompt_cache") }),
     // The provider's live answer to whether this turn may run, pushed mid-turn; drives the rate-limited notice, not the
     // headroom readouts.
     RateLimitInfoSchema.extend({ kind: z.literal("rate_limit_info"), account: z.string().optional() }),

package/src/events/land-breakage.ts

@@ -9,3 +9,15 @@ export const landBreakagePrompt = (parts: readonly string[]): string => [LAND_BR
 
 // Whether a stored prompt is one.
 export const isLandBreakage = (prompt: string): boolean => prompt.startsWith(LAND_BREAKAGE_OPENING);
+
+// The opening of a FRESH conversation the daemon starts on a red main-line check that the conversation that landed the
+// work could not take: nobody could be named, several could, or the one named had gone cold or run out of room.
+// Anchored on by the chat like the follow-up above, so it must stay unique and stable across releases.
+export const LAND_FIX_OPENING =
+    "The main tree's own check went red after work landed, and no conversation still holding that work could take it, so this one was started to fix it. The failures, the lands they arrived with and where to read those conversations are below. Fix them in this isolated worktree and check the fix as you would any change; your work lands like any other turn.";
+
+// The prompt a fresh fix-up is started with: its opening, then the evidence, each part already worded for the model.
+export const landFixPrompt = (parts: readonly string[]): string => [LAND_FIX_OPENING, ...parts].join("\n\n");
+
+// Whether a stored prompt is one.
+export const isLandFix = (prompt: string): boolean => prompt.startsWith(LAND_FIX_OPENING);

package/src/events/land-conflict.ts

@@ -0,0 +1,12 @@
+import { withoutResumeNote } from "./resume.js";
+
+// The turn the app sends a conversation whose land refused, asking it to rebase and resolve, recognised by its opening.
+// Composed by the editor, but lives here because the fold must recognise it as well: that turn's own rebase notice
+// would otherwise tell the reader the thing the turn was sent to fix.
+
+// Anchored on by the chat and the fold, so it must stay unique and stable across releases.
+export const LAND_CONFLICT_OPENING =
+    "Landing your work hit a merge conflict, none of it reached the user's workspace; it is all still on your branch. Rebase onto the main line and resolve the conflicts yourself. In each repo below (`root` is your working directory, any other name that subdirectory of it):";
+
+// Whether a stored prompt is one. A turn the daemon re-ran carries the same prompt after its resume note.
+export const isLandConflict = (prompt: string): boolean => withoutResumeNote(prompt.trim()).startsWith(LAND_CONFLICT_OPENING);

package/src/events/system-events.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AgentSummarySchema } from "../schemas/agents.js";
 import { AccountUsageSchema, ProviderRefusalSchema } from "../schemas/providers/plan-limits.js";
 import { MemberRoleSchema } from "../schemas/shared.js";
-import { SidecarStatusSchema } from "../schemas/workspace/workspace-tree.js";
+import { SidecarStatusSchema, WorkspaceTreeDeltaSchema } from "../schemas/workspace/workspace-tree.js";
 
 // Frames about the sandbox rather than a turn: liveness, boot progress, what moved (repos, refs, running processes,
 // presence, the fleet), and account headroom. One stream carries them all.
@@ -128,13 +128,19 @@ export type AccountUsageChanged = z.infer<typeof AccountUsageChangedSchema>;
 export const ProviderRefusalChangedSchema = z.object({ kind: z.literal("providerRefusal"), provider: z.string(), refusal: ProviderRefusalSchema.optional() });
 export type ProviderRefusalChanged = z.infer<typeof ProviderRefusalChangedSchema>;
 
-// The /events stream union: hello, heartbeats, boot progress, workspace/repo/ref/runtime/shadow changes, presence and
-// fleet rosters, account headroom and refusal changes. oRPC validates every frame against this.
+// What moved in the shared tree, once the daemon's resident copy re-listed a batch: a tab holding the generation it
+// counts from patches its tree, and one holding any other fetches it afresh.
+export const TreeChangedSchema = WorkspaceTreeDeltaSchema.extend({ kind: z.literal("treeChanged") });
+export type TreeChanged = z.infer<typeof TreeChangedSchema>;
+
+// The /events stream union: hello, heartbeats, boot progress, workspace/repo/ref/runtime/shadow/tree changes, presence
+// and fleet rosters, account headroom and refusal changes. oRPC validates every frame against this.
 export const SystemEventSchema = z.discriminatedUnion("kind", [
     HelloSchema,
     HeartbeatSchema,
     BootSchema,
     WorkspaceChangedSchema,
+    TreeChangedSchema,
     DerivedChangedSchema,
     ReposChangedSchema,
     RefsChangedSchema,