Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
/**
* Documents: typed JSON state per session, kept in the session's log.
*
* A document is a small JSON object (at most `DOC_MAX_BYTES` of
* `JSON.stringify`) that every kernel harness and app code can read and
* write. It is not shown to the model unless an app gives it tools that read
* it (code reads them, as in pi-durable).
*
* Two ways to change one:
*
* - **In-band, inside an effect** (`io.docs.update`): the change rides on
* the effect's own outcome (`step_completed`, an envelope `{ $docs: 1,
* value, docs }`), so it is atomic with it. A call that throws, or never
* reports (a crash), changed nothing. Such an edit always applies where its
* outcome lands (rebased path by path when something landed in between):
* the World makes a step's first outcome final, so an outcome can never be
* refused because of a document.
* - **Out-of-band, from app code** (`sessions.updateDoc`): a `hook_received`
* on the session's docs hook (`harness:<runId>:docs`, created on the first
* such edit). It applies only on the revision it was computed from
* (optimistic concurrency); `updateDoc` re-reads and retries, or throws
* `DocConflict` with `expectRevision`.
*
* The fold is the only interpreter: it reads no definitions and no clock, so
* the same log always folds to the same documents. Definitions (schema
* version, `migrate`, `validate`) and the size limit are writers' and
* readers' business.
*
* Browser-safe: no Node APIs (world-browser bundles the kernel).
*/
import type { SessionState } from './types.ts';
export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
export type JsonObject = { [key: string]: JsonValue };
/** `T`, read-only all the way down: what a reader gets (values in the fold are never mutated). */
export type DeepReadonly<T> = T extends (infer U)[]
? readonly DeepReadonly<U>[]
: T extends object
? { readonly [K in keyof T]: DeepReadonly<T[K]> }
: T;
/** 64 KB: the most `JSON.stringify(value)` of a document may take, in UTF-8 bytes. Raising it later is safe; writers enforce it, the fold never does. */
export const DOC_MAX_BYTES = 65_536;
const KIND = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
export interface DocDefinition<T extends object = JsonObject> {
/** The document's name in the log. `/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/`. `hw.` is reserved for harness-world's own documents. */
readonly kind: string;
/** Schema version, a positive integer. Bump it when `T`'s shape changes, and give `migrate`. */
readonly version: number;
/** The value of a document that was never written. A fresh copy each call. */
initial(): T;
/** A stored value of an older schema version, as `T`. Runs on read, never in the fold. Must be pure. */
migrate?(value: JsonObject, fromVersion: number): T;
/** Check a value before it is written (in a tool's `update`, in `updateDoc`). Throw to refuse. Never runs in the fold. */
validate?(value: DeepReadonly<T>): void;
/** JSON Schema of `T` (TypeBox works as-is), for tools that show a document to a model. */
readonly schema?: object;
/**
* What the live `doc` event of each applied edit carries: `'value'` (the
* default) the whole value; `'revision'` the revision without the value,
* for a document that changes often or is large, whose clients read the
* value when they want it (`sessions.doc`). Publishing only: the log is
* the same either way.
*/
readonly live?: DocLive;
/** Every harness-world document is session-scoped (the shape pi-durable's tokens have). */
readonly scope: 'session';
}
/** What a document's live `doc` events carry (`DocDefinition.live`). */
export type DocLive = 'value' | 'revision';
/** A document token: pass it to every read and write. Same shape as pi-durable's (`{ definition }`). */
export interface Doc<T extends object = JsonObject> {
readonly definition: DocDefinition<T>;
}
/** A document as some reader sees it. */
export interface DocSnapshot<T extends object = JsonObject> {
readonly value: DeepReadonly<T>;
/** Edits applied so far. 0: never written, and `value` is `initial()`. */
readonly revision: number;
}
/**
* Define a document.
*
* ```ts
* const Todos = defineDoc<{ items: string[] }>({ kind: 'app.todos', version: 1, initial: () => ({ items: [] }) })
* ```
*/
export function defineDoc<T extends object>(definition: {
kind: string;
version: number;
/** A function (preferred, as in pi-durable) or a plain value (copied on each use). */
initial: T | (() => T);
migrate?: (value: JsonObject, fromVersion: number) => T;
validate?: (value: DeepReadonly<T>) => void;
schema?: object;
live?: DocLive;
scope?: 'session';
}): Doc<T> {
const { kind, version, initial } = definition ?? ({} as typeof definition);
if (typeof kind !== 'string' || !KIND.test(kind)) {
throw new TypeError(`harness-world: a document kind must match ${KIND} (got ${JSON.stringify(kind)})`);
}
if (!Number.isSafeInteger(version) || version < 1) {
throw new TypeError(`harness-world: document ${kind}'s version must be a positive integer (got ${String(version)})`);
}
if (definition.scope !== undefined && definition.scope !== 'session') {
throw new TypeError(`harness-world: document ${kind}'s scope must be 'session'`);
}
if (definition.live !== undefined && definition.live !== 'value' && definition.live !== 'revision') {
throw new TypeError(`harness-world: document ${kind}'s live must be 'value' or 'revision'`);
}
let make: () => T;
if (typeof initial === 'function') make = initial as () => T;
else {
// Checked once, now: a bad initial value fails where it is defined.
const value = strictCopy(initial, kind) as T;
make = () => copyJson(value) as T;
}
const def: DocDefinition<T> = {
kind,
version,
initial: make,
...(definition.migrate ? { migrate: definition.migrate } : {}),
...(definition.validate ? { validate: definition.validate } : {}),
...(definition.schema ? { schema: definition.schema } : {}),
...(definition.live === 'revision' ? { live: 'revision' as const } : {}),
scope: 'session',
};
return Object.freeze({ definition: Object.freeze(def) });
}
// ---------------------------------------------------------------------------
// Errors
/** An out-of-band edit lost a race for its revision (or `expectRevision` did not match). */
export class DocConflict extends Error {
constructor(
readonly kind: string,
/** The document's revision when the conflict was seen. */
readonly revision: number,
/** The revision the writer expected (`expectRevision`), if it named one. */
readonly expected?: number
) {
super(
expected !== undefined
? `harness-world: document ${kind} is at revision ${revision}, not ${expected}`
: `harness-world: document ${kind} kept changing (now at revision ${revision}); the edit was not applied`
);
this.name = 'DocConflict';
}
}
/** A write would leave a document over `DOC_MAX_BYTES` and larger than it was. */
export class DocTooLarge extends Error {
constructor(
readonly kind: string,
readonly bytes: number,
readonly limit: number = DOC_MAX_BYTES
) {
super(`harness-world: document ${kind} would be ${bytes.toLocaleString('en-US')} bytes; the limit is ${limit.toLocaleString('en-US')}`);
this.name = 'DocTooLarge';
}
}
/** A stored document's schema version is newer than the code's, or older with no `migrate`. */
export class DocVersionError extends Error {
constructor(
readonly kind: string,
/** The stored schema version. */
readonly stored: number,
/** The definition's version. */
readonly code: number
) {
super(
stored > code
? `harness-world: document ${kind} is stored at schema version ${stored}, newer than this code's ${code} (no silent downgrade)`
: `harness-world: document ${kind} is stored at schema version ${stored}, older than this code's ${code}, and its definition has no migrate`
);
this.name = 'DocVersionError';
}
}
// ---------------------------------------------------------------------------
// The edit format (what the log stores)
/** Object keys only: arrays are never indexed (index arithmetic is what breaks under a rebase). */
export type DocPath = string[];
export type DocOp =
/** Path `[]` replaces the whole value (which must be an object). */
| { op: 'set'; path: DocPath; value: JsonValue }
| { op: 'delete'; path: DocPath }
| { op: 'append'; path: DocPath; values: JsonValue[] };
export interface DocEdit {
kind: string;
/** The revision the edit was computed from. */
base: number;
/** The schema version of the value after the edit. */
schema: number;
/** Only on a first write (base 0) stored as ops: the value they start from (`initial()`). */
init?: JsonObject;
ops: DocOp[];
}
/** A document in the fold. */
export interface DocState {
kind: string;
/** Stored schema version. */
schema: number;
revision: number;
/** Deep-frozen: the fold copies on write and never mutates a value. */
value: JsonObject;
/** Slot of the event that made this revision. */
slot: number;
by: { step: string; key: string } | { edit: string };
}
/** What an effect's outcome did to documents (`EffectRecord.docs`). Values are in `SessionState.docs`. */
export interface DocEffect {
kind: string;
/** The document's revision after this outcome (or when it was dropped). */
revision: number;
/** Applied on a later revision than it was computed from (merged path by path). */
rebased?: true;
/** Not applied: an older schema than the stored one (code older than a migration), or a malformed edit (a writer bug). */
dropped?: 'older-schema' | 'malformed';
}
/** What an effect that changed documents commits as its result. */
export interface DocsEnvelope {
$docs: 1;
value: unknown;
docs: DocEdit[];
}
/** What an out-of-band edit writes as its `hook_received` payload. */
export interface DocsPayload {
$docs: 1;
/** `dedit_<ulid>`: a resend with the same id is inert. */
id: string;
docs: DocEdit[];
}
/** The docs hook's token. */
export const docsHookToken = (runId: string) => `harness:${runId}:docs`;
/** Whether `value` is an effect outcome carrying document edits. Exactly the keys `$docs` (1), `value`, `docs` (an array). */
export function isDocsEnvelope(value: unknown): value is DocsEnvelope {
if (!isPlainObject(value)) return false;
const v = value as Record<string, unknown>;
if (v.$docs !== 1 || !Array.isArray(v.docs)) return false;
for (const key of Object.keys(v)) if (key !== '$docs' && key !== 'value' && key !== 'docs') return false;
return true;
}
/** Whether `value` is an out-of-band edit's payload. */
export function isDocsPayload(value: unknown): value is DocsPayload {
if (!isPlainObject(value)) return false;
const v = value as Record<string, unknown>;
return v.$docs === 1 && typeof v.id === 'string' && v.id.length > 0 && Array.isArray(v.docs);
}
/**
* What an effect commits as its result: its output, wrapped in the envelope
* when it changed documents. An output that itself looks like an envelope is
* wrapped too (with no edits), so the fold never mistakes it for one.
*/
export function outcomeResult(output: unknown, edits: DocEdit[]): unknown {
if (edits.length > 0 || isDocsEnvelope(output)) return { $docs: 1, value: output, docs: edits } satisfies DocsEnvelope;
return output;
}
// ---------------------------------------------------------------------------
// Strict JSON
export function isPlainObject(value: unknown): value is Record<string, unknown> {
if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
const proto = Object.getPrototypeOf(value);
return proto === Object.prototype || proto === null;
}
const hasOwn = (o: object, k: string) => Object.prototype.hasOwnProperty.call(o, k);
function pathText(path: (string | number)[]): string {
let out = '$';
for (const p of path) out += typeof p === 'number' ? `[${p}]` : /^[A-Za-z_$][\w$]*$/.test(p) ? `.${p}` : `[${JSON.stringify(p)}]`;
return out;
}
/**
* A deep copy of `value`, which must be strict JSON with an object at the
* root: plain objects (or null-prototype), dense arrays, strings, finite
* numbers, booleans, `null`. Throws a `TypeError` naming the path otherwise
* (`undefined` anywhere, `NaN`, infinities, bigint, functions, symbols, class
* instances, `Date`, cycles, the key `__proto__`). A container referenced
* twice is copied twice (as `JSON.stringify` would write it).
*/
export function strictCopy(value: unknown, kind: string): JsonObject {
const ancestors = new Set<object>();
const path: (string | number)[] = [];
const fail = (what: string): never => {
throw new TypeError(`harness-world: document ${kind} is not strict JSON at ${pathText(path)}: ${what}`);
};
const visit = (v: unknown): JsonValue => {
switch (typeof v) {
case 'string':
case 'boolean':
return v;
case 'number':
return Number.isFinite(v) ? v : fail(String(v));
case 'undefined':
return fail('undefined');
case 'object':
break;
default:
return fail(typeof v);
}
if (v === null) return null;
if (ancestors.has(v)) return fail('a cycle');
if (Array.isArray(v)) {
ancestors.add(v);
const out: JsonValue[] = new Array(v.length);
for (let i = 0; i < v.length; i++) {
path.push(i);
if (!(i in v)) fail('a hole in an array');
out[i] = visit(v[i]);
path.pop();
}
ancestors.delete(v);
return out;
}
if (!isPlainObject(v)) return fail(v instanceof Date ? 'a Date' : `an instance of ${(v as object).constructor?.name ?? 'a class'}`);
ancestors.add(v);
const out: JsonObject = {};
for (const key of Object.keys(v)) {
path.push(key);
if (key === '__proto__') fail('the key __proto__');
out[key] = visit((v as Record<string, unknown>)[key]);
path.pop();
}
ancestors.delete(v);
return out;
};
if (!isPlainObject(value)) {
if (value === undefined || value === null || typeof value !== 'object') return fail(`the root must be a plain object, not ${value === null ? 'null' : typeof value}`);
return fail(Array.isArray(value) ? 'the root must be a plain object, not an array' : 'the root must be a plain object');
}
return visit(value) as JsonObject;
}
/** A deep copy of a JSON value already known to be strict (no checks). Mutable, even of a frozen value. */
export function copyJson<T>(value: T): T {
if (value === null || typeof value !== 'object') return value;
if (Array.isArray(value)) return value.map(copyJson) as T;
const out: Record<string, unknown> = {};
for (const key of Object.keys(value)) out[key] = copyJson((value as Record<string, unknown>)[key]);
return out as T;
}
/** Freeze `value` and everything under it. Stops at a frozen node: only ever frozen whole, so its subtree is too. */
export function deepFreeze<T>(value: T): T {
if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value;
Object.freeze(value);
if (Array.isArray(value)) for (const v of value) deepFreeze(v);
else for (const key of Object.keys(value)) deepFreeze((value as Record<string, unknown>)[key]);
return value;
}
/** Deep equality of JSON values, key order ignored. */
export function jsonEqual(a: unknown, b: unknown): boolean {
if (a === b) return true;
if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
if (Array.isArray(a) !== Array.isArray(b)) return false;
if (Array.isArray(a)) {
const bb = b as unknown[];
if (a.length !== bb.length) return false;
for (let i = 0; i < a.length; i++) if (!jsonEqual(a[i], bb[i])) return false;
return true;
}
const ak = Object.keys(a);
const bo = b as Record<string, unknown>;
if (ak.length !== Object.keys(bo).length) return false;
for (const k of ak) if (!hasOwn(bo, k) || !jsonEqual((a as Record<string, unknown>)[k], bo[k])) return false;
return true;
}
/** UTF-8 bytes of a string, without encoding it. */
function utf8Length(s: string): number {
let n = 0;
for (let i = 0; i < s.length; i++) {
const c = s.charCodeAt(i);
if (c < 0x80) n += 1;
else if (c < 0x800) n += 2;
else if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00) {
n += 4;
i++;
} else n += 3;
}
return n;
}
/** What the size limit measures: UTF-8 bytes of `JSON.stringify(value)`. */
export function docBytes(value: unknown): number {
return utf8Length(JSON.stringify(value) ?? '');
}
// ---------------------------------------------------------------------------
// Diff and apply
/**
* Ops up to this size are kept even when a root `set` would be a few bytes
* smaller: on a small document a root `set` saves nothing that matters, and
* it would replace, under a rebase, what another writer changed meanwhile.
*/
export const DOC_OPS_SLACK_BYTES = 1024;
/**
* The ops that turn `a` into `b`: equal (deep, key order ignored) gives none;
* two plain objects recurse key by key (`set` for a new or changed key,
* `delete` for a gone one); an array `b` that is `a` plus items at the end
* gives one `append`; anything else is a `set` of `b`. If those ops encode
* larger than a root `set` of `b` (and larger than `DOC_OPS_SLACK_BYTES`),
* the root `set` is returned instead.
*/
export function diffDoc(a: JsonObject, b: JsonObject): DocOp[] {
const ops = diffOps(a, b);
if (ops.length === 0) return ops;
const bytes = docBytes(ops);
if (bytes <= DOC_OPS_SLACK_BYTES) return ops;
const root: DocOp[] = [{ op: 'set', path: [], value: b }];
return bytes > docBytes(root) ? root : ops;
}
/** The fine-grained ops from `a` to `b` (`diffDoc` without the root-`set` fallback). */
export function diffOps(a: JsonObject, b: JsonObject): DocOp[] {
const ops: DocOp[] = [];
diffInto(a, b, [], ops);
return ops;
}
function diffInto(a: JsonValue, b: JsonValue, path: DocPath, out: DocOp[]): void {
if (jsonEqual(a, b)) return;
if (isPlainObject(a) && isPlainObject(b)) {
const ao = a as JsonObject;
const bo = b as JsonObject;
for (const key of Object.keys(bo)) {
if (!hasOwn(ao, key)) out.push({ op: 'set', path: [...path, key], value: bo[key]! });
else diffInto(ao[key]!, bo[key]!, [...path, key], out);
}
for (const key of Object.keys(ao)) if (!hasOwn(bo, key)) out.push({ op: 'delete', path: [...path, key] });
return;
}
if (Array.isArray(a) && Array.isArray(b) && b.length > a.length && a.every((x, i) => jsonEqual(x, b[i]))) {
out.push({ op: 'append', path, values: b.slice(a.length) });
return;
}
out.push({ op: 'set', path, value: b });
}
/**
* Apply `ops` to `value`, copy-on-write along each path (`value` is never
* mutated), and deep-freeze what is new. Total for well-formed ops (see
* `validEdit`): `set` creates a missing or non-object intermediate as `{}`;
* `delete` of a missing path does nothing; `append` makes its target an
* array if it is not one. On its own base, `applyDocOps(a, diffDoc(a, b))`
* deep-equals `b`; on a later revision the same rules merge path by path
* (edits to different keys both survive, appends both survive, the later
* edit wins a key both touched, an array replaced whole is replaced).
*/
export function applyDocOps(value: JsonObject, ops: readonly DocOp[]): JsonObject {
let out: JsonValue = value;
for (const op of ops) {
if (op.path.length === 0) {
// Validated: only a `set` of an object at the root.
if (op.op === 'set' && isPlainObject(op.value)) out = op.value;
continue;
}
if (op.op === 'delete') out = deleteIn(out, op.path, 0);
else if (op.op === 'set') out = setIn(out, op.path, 0, () => op.value);
else out = setIn(out, op.path, 0, (old) => (Array.isArray(old) ? [...old, ...op.values] : [...op.values]));
}
return deepFreeze(out as JsonObject);
}
function setIn(node: JsonValue | undefined, path: DocPath, i: number, leaf: (old: JsonValue | undefined) => JsonValue): JsonValue {
if (i === path.length) return leaf(node);
const obj = isPlainObject(node) ? (node as JsonObject) : {};
const key = path[i]!;
const copy: JsonObject = { ...obj };
copy[key] = setIn(hasOwn(obj, key) ? obj[key] : undefined, path, i + 1, leaf);
return copy;
}
function deleteIn(node: JsonValue, path: DocPath, i: number): JsonValue {
if (!isPlainObject(node)) return node;
const obj = node as JsonObject;
const key = path[i]!;
if (!hasOwn(obj, key)) return node;
const copy: JsonObject = { ...obj };
if (i === path.length - 1) delete copy[key];
else {
const child = deleteIn(obj[key]!, path, i + 1);
if (child === obj[key]) return node;
copy[key] = child;
}
return copy;
}
function validPath(path: unknown): path is DocPath {
return Array.isArray(path) && path.every((p) => typeof p === 'string' && p !== '__proto__');
}
function validOp(op: unknown): op is DocOp {
if (!isPlainObject(op)) return false;
const o = op as Record<string, unknown>;
if (!validPath(o.path)) return false;
const root = (o.path as DocPath).length === 0;
switch (o.op) {
case 'set':
return hasOwn(o, 'value') && o.value !== undefined && (!root || isPlainObject(o.value));
case 'delete':
return !root;
case 'append':
return !root && Array.isArray(o.values);
default:
return false;
}
}
/** Whether an edit is well formed (the fold drops one that is not: a writer bug). */
export function validEdit(edit: unknown): edit is DocEdit {
if (!isPlainObject(edit)) return false;
const e = edit as Record<string, unknown>;
return (
typeof e.kind === 'string' &&
KIND.test(e.kind) &&
Number.isSafeInteger(e.base) &&
(e.base as number) >= 0 &&
Number.isSafeInteger(e.schema) &&
(e.schema as number) >= 1 &&
(e.init === undefined || isPlainObject(e.init)) &&
Array.isArray(e.ops) &&
e.ops.every(validOp)
);
}
// ---------------------------------------------------------------------------
// The fold's rules (pure functions of log order)
/**
* Apply an outcome's edits at `slot` (its `step_completed` applied: the
* record was running). Each applies on its base exactly, on a later revision
* by the rebase rules (`rebased`), on an absent document from `init` (or `{}`
* for a root `set`). An edit whose schema is below the stored one is dropped
* (`older-schema`), a malformed one too (`malformed`); the outcome stands
* either way.
*/
export function foldInBandEdits(state: SessionState, edits: readonly unknown[], slot: number, by: { step: string; key: string }): DocEffect[] {
const out: DocEffect[] = [];
for (const raw of edits) {
const kind = isPlainObject(raw) && typeof raw.kind === 'string' ? raw.kind : '';
const cur = kind ? state.docs.get(kind) : undefined;
if (!validEdit(raw)) {
out.push({ kind, revision: cur?.revision ?? 0, dropped: 'malformed' });
continue;
}
if (cur && raw.schema < cur.schema) {
out.push({ kind, revision: cur.revision, dropped: 'older-schema' });
continue;
}
const revision = (cur?.revision ?? 0) + 1;
const value = applyDocOps(cur ? cur.value : deepFreeze(raw.init ?? {}), raw.ops);
state.docs.set(kind, { kind, schema: raw.schema, revision, value, slot, by });
out.push({ kind, revision, ...((cur?.revision ?? 0) !== raw.base ? { rebased: true as const } : {}) });
}
return out;
}
/**
* Apply an out-of-band edit (a `hook_received` on the docs hook) at `slot`.
* Inert (`'inert'`) when the payload is not the docs shape or its `id` was
* already seen. Otherwise all of its edits apply exactly or none do: each
* must be on its document's current revision (0 for an absent one) and not
* below its stored schema. Either way the outcome is recorded in `docEdits`.
*/
export function foldOutOfBandEdits(state: SessionState, payload: unknown, slot: number): 'applied' | 'conflict' | 'inert' {
if (!isDocsPayload(payload) || state.docEdits.has(payload.id)) return 'inert';
const kinds = new Set<string>();
let ok = payload.docs.length > 0;
for (const edit of payload.docs) {
if (!ok) break;
if (!validEdit(edit) || kinds.has(edit.kind)) {
ok = false;
break;
}
kinds.add(edit.kind);
const cur = state.docs.get(edit.kind);
if (edit.base !== (cur?.revision ?? 0) || (cur && edit.schema < cur.schema)) ok = false;
}
if (ok) {
for (const edit of payload.docs) {
const cur = state.docs.get(edit.kind);
const value = applyDocOps(cur ? cur.value : deepFreeze(edit.init ?? {}), edit.ops);
state.docs.set(edit.kind, { kind: edit.kind, schema: edit.schema, revision: (cur?.revision ?? 0) + 1, value, slot, by: { edit: payload.id } });
}
}
state.docEdits.set(payload.id, { applied: ok, slot });
return ok ? 'applied' : 'conflict';
}
// ---------------------------------------------------------------------------
// Readers and writers
/** A document's value as one definition reads it. */
export interface Materialized {
/** Deep-frozen. */
value: JsonObject;
revision: number;
/** Whether the log has the document (`revision > 0`). */
present: boolean;
/** Read through `migrate` (the stored schema is older than the definition's). */
migrated: boolean;
/** The value as the log holds it (before any migration), when it is there: what the size limit compares growth with. */
stored?: JsonObject;
}
/** The bytes the log holds for a materialized document, 0 when it holds none (`prepareUpdate`'s `storedBytes`). */
export const storedBytes = (m: Pick<Materialized, 'stored'>): number => (m.stored ? docBytes(m.stored) : 0);
function definitionOf<T extends object>(doc: Doc<T>): DocDefinition<T> {
const def = doc?.definition;
if (!def || typeof def.kind !== 'string' || typeof def.initial !== 'function') {
throw new TypeError('harness-world: not a document token (make one with defineDoc)');
}
return def;
}
/**
* A stored document (or none) as `def` reads it: as is at the same schema;
* through `migrate` when older; `DocVersionError` when newer, or older with
* no `migrate`. A document never written is `initial()`.
*/
export function materializeDoc<T extends object>(def: DocDefinition<T>, stored: Pick<DocState, 'schema' | 'value' | 'revision'> | undefined): Materialized {
if (!stored) return { value: deepFreeze(strictCopy(def.initial(), def.kind)), revision: 0, present: false, migrated: false };
if (stored.schema === def.version) return { value: deepFreeze(stored.value), revision: stored.revision, present: true, migrated: false, stored: stored.value };
if (stored.schema > def.version || !def.migrate) throw new DocVersionError(def.kind, stored.schema, def.version);
const migrated = def.migrate(copyJson(stored.value), stored.schema);
return { value: deepFreeze(strictCopy(migrated, def.kind)), revision: stored.revision, present: true, migrated: true, stored: stored.value };
}
/** A document in a fold (a `sessions.inspect`, a drive's view), as `doc` reads it. */
export function readDoc<T extends object>(state: Pick<SessionState, 'docs'>, doc: Doc<T>): DocSnapshot<T> {
const def = definitionOf(doc);
const m = materializeDoc(def, state.docs?.get(def.kind));
return { value: m.value as unknown as DeepReadonly<T>, revision: m.revision };
}
/**
* Run a writer's `mutate` on a copy of `current` and check the result:
* strict JSON (a `TypeError` naming the path), `validate`, and size (over
* the limit and larger than `current`: `DocTooLarge`). Returns the new
* value, deep-frozen and owned by the caller of this (never the mutator's).
*
* `storedBytes`: what the log holds for the document (`storedBytes(m)`; 0
* when it holds none). Growth is measured from the smaller of that and
* `current`, so a `migrate` that makes a document bigger than the log holds
* cannot carry it past the limit on the next write.
*/
export function prepareUpdate<T extends object>(
def: DocDefinition<T>,
current: JsonObject,
mutate: (draft: T) => void | T,
options: { storedBytes?: number | (() => number) } = {}
): JsonObject {
if (typeof mutate !== 'function') throw new TypeError(`harness-world: update(${def.kind}) needs a function`);
const draft = copyJson(current) as unknown as T;
const returned = mutate(draft);
const next = deepFreeze(strictCopy(returned === undefined ? draft : returned, def.kind));
def.validate?.(next as unknown as DeepReadonly<T>);
const bytes = docBytes(next);
if (bytes > DOC_MAX_BYTES) {
const floor = typeof options.storedBytes === 'function' ? options.storedBytes() : options.storedBytes;
if (bytes > Math.min(docBytes(current), floor ?? Number.POSITIVE_INFINITY)) throw new DocTooLarge(def.kind, bytes);
}
return next;
}
/**
* The edit that turns `base` (as read) into `next`, or undefined when there
* is nothing to write. After a migration it is a root `set` at the new
* schema (ops against a migrated value would not apply to the stored one). A
* first write carries `init` when it is stored as ops.
*
* `exact`: the edit applies only on its own base (an out-of-band edit), so a
* root `set` may stand in for ops that encode larger (`diffDoc`). Otherwise
* (an in-band edit, which the fold rebases onto whatever landed meanwhile)
* it is always the fine-grained ops: a root `set` rebased onto a sibling's or
* an app's edit would erase it (two first appends of a large item to an
* empty list kept only the last).
*/
export function encodeEdit(def: DocDefinition<any>, base: Materialized, next: JsonObject, options: { exact?: boolean } = {}): DocEdit | undefined {
if (jsonEqual(base.value, next)) return undefined;
const ops: DocOp[] = base.migrated ? [{ op: 'set', path: [], value: next }] : options.exact ? diffDoc(base.value, next) : diffOps(base.value, next);
const rootSet = ops.length === 1 && ops[0]!.path.length === 0;
return {
kind: def.kind,
base: base.revision,
schema: def.version,
...(!base.present && !rootSet ? { init: base.value } : {}),
ops,
};
}
/** Documents inside an effect: pinned at the call's first touch of each, plus the call's own updates. */
export interface DocsIO {
/** The document as this call sees it. `revision` is the revision it was pinned at. */
read<T extends object>(doc: Doc<T>): DocSnapshot<T>;
/**
* Change the document. `mutate` gets a mutable deep copy of this call's
* value and edits it or returns a replacement; it runs exactly once, now.
* Returns the new value as this call sees it. The change commits with the
* call's outcome: a call that throws, or never reports (a crash), changed
* nothing. Throws `DocTooLarge`, `DocVersionError`, a `TypeError` (not
* strict JSON, naming the path), or what `validate` throws.
*/
update<T extends object>(doc: Doc<T>, mutate: (draft: T) => void | T): DeepReadonly<T>;
}
/** Documents in a drive's current view, outside effects (prompts, display). Not pinned. */
export interface DocsReader {
read<T extends object>(doc: Doc<T>): DocSnapshot<T>;
}
/** One effect call's documents: its `DocsIO`, and the edits it made (committed with its outcome). */
export interface CallDocs {
io: DocsIO;
/** One edit per document the call changed, from its pinned base to its last value. */
edits(): DocEdit[];
}
/**
* A `DocsIO` for one call over `view` (the speculative fold when running
* ahead, else the durable one). `onPin` sees each document's definition when
* the call first touches it (the publisher of its live events needs `live`).
*/
export function callDocs(view: () => Pick<SessionState, 'docs'>, onPin?: (def: DocDefinition<any>) => void): CallDocs {
const pins = new Map<string, { def: DocDefinition<any>; base: Materialized; current: JsonObject }>();
const pin = (doc: Doc<any>) => {
const def = definitionOf(doc);
let p = pins.get(def.kind);
if (!p) {
const base = materializeDoc(def, view().docs?.get(def.kind));
p = { def, base, current: base.value };
pins.set(def.kind, p);
onPin?.(def);
} else if (p.def.version !== def.version) {
throw new TypeError(`harness-world: document ${def.kind} was used at schema versions ${p.def.version} and ${def.version} in one call`);
}
return p;
};
return {
io: {
read(doc) {
const p = pin(doc);
return { value: p.current as never, revision: p.base.revision };
},
update(doc, mutate) {
const p = pin(doc);
p.current = prepareUpdate(p.def, p.current, mutate as (draft: object) => void | object, { storedBytes: () => storedBytes(p.base) });
return p.current as never;
},
},
edits() {
const out: DocEdit[] = [];
for (const p of pins.values()) {
const edit = encodeEdit(p.def, p.base, p.current);
if (edit) out.push(edit);
}
return out;
},
};
}
/** A `DocsReader` over `view`. */
export function docsReader(view: () => Pick<SessionState, 'docs'>): DocsReader {
return { read: (doc) => readDoc(view(), doc) };
}
// ---------------------------------------------------------------------------
// The live `doc` event
/**
* On the session's live stream, once per applied edit. Best effort, like
* every live event: keep the highest `revision` seen of each kind. A drive
* running ahead of its writes publishes from its speculative fold; when the
* log put the edit at another revision (an app's edit landed in between) it
* publishes the log's document once the write lands, and after a `rewind`
* it publishes what the log has, so a client takes the next event of each
* kind after a `rewind` whatever its revision.
*
* A document defined with `live: 'revision'` (the workspace's manifest) is
* published without its `value`: a client that wants it reads it
* (`sessions.doc`), when the revision moves past the one it has.
*/
export interface DocLiveEvent {
type: 'doc';
kind: string;
revision: number;
/** The stored schema version of the document. */
schema: number;
/** The whole value after the edit (after any rebase). Absent for a document defined with `live: 'revision'`. */
value?: JsonObject;
by: { effect: string; step: string } | { edit: string };
t: number;
}
/** The live event for `doc` as the log has it: with its value, unless `live` is `'revision'` (the definition's `live`). */
export function docLiveEvent(doc: DocState, t: number, live: DocLive = 'value'): DocLiveEvent {
return {
type: 'doc',
kind: doc.kind,
revision: doc.revision,
schema: doc.schema,
...(live === 'revision' ? {} : { value: doc.value }),
by: 'edit' in doc.by ? { edit: doc.by.edit } : { effect: doc.by.key, step: doc.by.step },
t,
};
}
/** Whether `event` is a live `doc` event. */
export function isDocLiveEvent(event: unknown): event is DocLiveEvent {
return isPlainObject(event) && event.type === 'doc' && typeof event.kind === 'string';
}
/**
* A live `doc` event as `doc`'s definition reads it (for a client): its value
* migrated, or `{ type: 'doc', kind, revision, error }` when it cannot be.
* For a definition with `live: 'revision'` (or an event without a value),
* the event without its value.
*/
export function docEventFor(doc: Doc<any>, event: { kind: string; revision: number; schema: number; value?: JsonObject }): Record<string, unknown> {
const def = definitionOf(doc);
const { value, ...rest } = event;
if (def.live === 'revision' || value === undefined) return { ...rest, type: 'doc' };
try {
const m = materializeDoc(def, { ...rest, value });
return { ...event, type: 'doc', schema: def.version, value: m.value };
} catch (err) {
return { type: 'doc', kind: event.kind, revision: event.revision, error: err instanceof Error ? err.message : String(err) };
}
}
// ---------------------------------------------------------------------------
// Names and the prompt hook
/**
* A document's short name: the last dot-separated segment of its kind, made
* safe for a tool name (`app.todos` → `todos`, `crm.notes-v2` → `notes-v2`).
*/
export function docNameOf(kind: string): string {
const last = kind.split('.').filter(Boolean).at(-1) ?? kind;
return last.replace(/[^A-Za-z0-9_-]/g, '_');
}
/** Documents by name: a record's keys, or each kind's short name (`docNameOf`). Throws on a repeated name. */
export function namedDocs(docs: readonly Doc<any>[] | Readonly<Record<string, Doc<any>>>): [string, Doc<any>][] {
const entries: [string, Doc<any>][] = Array.isArray(docs)
? (docs as readonly Doc<any>[]).map((d) => [docNameOf(definitionOf(d).kind), d])
: Object.entries(docs as Record<string, Doc<any>>).map(([name, d]) => (definitionOf(d), [name, d]));
const seen = new Set<string>();
for (const [name] of entries) {
if (seen.has(name)) throw new TypeError(`harness-world: two documents are named ${JSON.stringify(name)}: name them with a record ({ name: Doc })`);
seen.add(name);
}
return entries;
}
/**
* The prompt hook for kernel harnesses: what to put in the instructions of
* each model call. A list (or record) of documents, shown with
* `docsPrompt`, or a function of the call's documents. Off unless given:
* documents reach the model only where the app puts them.
*/
export type PromptDocs = readonly Doc<any>[] | Readonly<Record<string, Doc<any>>> | ((docs: DocsReader) => string | undefined);
/**
* A prompt section with the documents' current values, as JSON:
*
* ```text
* The session's documents, as of this model call (JSON; revision 0: never written):
*
* <document name="todos" kind="app.todos" revision="3">
* {"items":["buy milk"]}
* </document>
* ```
*
* Call it with the model effect's `io.docs` (inside the effect), so the
* values are the ones that call pinned and a replay never depends on a later
* read. A document this code cannot read (`DocVersionError`) shows its error.
*/
export function docsPrompt(docs: readonly Doc<any>[] | Readonly<Record<string, Doc<any>>>): (reader: DocsReader) => string {
const named = namedDocs(docs);
return (reader) => {
const parts = named.map(([name, doc]) => {
const kind = definitionOf(doc).kind;
try {
const snap = reader.read(doc);
return `<document name="${name}" kind="${kind}" revision="${snap.revision}">\n${JSON.stringify(snap.value)}\n</document>`;
} catch (err) {
return `<document name="${name}" kind="${kind}" error="${String(err instanceof Error ? err.message : err).replace(/"/g, "'")}"></document>`;
}
});
return `The session's documents, as of this model call (JSON; revision 0: never written):\n\n${parts.join('\n\n')}`;
};
}
/** The text a `PromptDocs` option adds to one model call's instructions, or undefined (off, or nothing to add). */
export function promptDocsText(option: PromptDocs | undefined, reader: DocsReader | undefined): string | undefined {
if (!option || !reader) return undefined;
const text = typeof option === 'function' ? option(reader) : docsPrompt(option)(reader);
return text ? text : undefined;
}