A local-first multi-agent app development platform, built on PenguinHarness
/**
* The upgrade ladder, MVP slice: silent → migrator chain → blocked.
*
* "Data is not discarded" is machine-decided by strictParse over the parked
* document (after running per-node migration chains). Any dropped/missing/
* invalid path blocks the swap: the old instance keeps running untouched and
* the caller receives the parked doc plus the exact paths — the input for the
* next rungs of the ladder (auto-upgrader / agent / human), which live outside
* the kernel.
*
* Validate-then-swap: the running tree is only disposed after the whole
* document reconciles. Boot itself can still fail after the dispose — that
* residual risk is surfaced as a RETURNED outcome (`status: "failed"`, carrying
* the parked document), never a throw: the caller holds everything needed to
* re-boot the previous implementation from that document, so the worst case is
* an automatic recovery boot, never data loss and never a half-dead process
* whose old tree is disposed with nothing booted in its place.
*/
import type { Json } from "./json.js";
import { isJsonObject } from "./json.js";
import type { AnyIface, Iface, Park } from "./iface.js";
import { isKeyed } from "./iface.js";
import type { Impl, Instance, ParkedNode, Resources } from "./boot.js";
import { boot } from "./boot.js";
export interface UpgradeBlocked {
status: "blocked";
dropped: string[];
missing: string[];
invalid: string[];
/** The parked (and partially migrated) document — persist it; nothing is lost. */
doc: Json;
}
export interface UpgradeFailed {
status: "failed";
/** What the new implementation's boot threw. */
error: unknown;
/**
* The parked document. The OLD tree is disposed by this point (validate-then-swap
* disposes before boot, so the new tree can adopt what the old one delivered) — this
* document is what the previous implementation re-boots from.
*/
doc: Json;
}
export type UpgradeResult<A extends Park> =
| { status: "ok"; mode: "silent" | "migrated"; instance: Instance<A>; doc: Json }
| UpgradeBlocked
| UpgradeFailed;
/** An undeclared child that is an empty container (no data to lose). */
function isEmptyChildDoc(doc: Json): boolean {
if (doc === null) return true;
if (isJsonObject(doc) && Object.keys(doc).length === 1 && isJsonObject(doc.items)) {
return Object.keys(doc.items).length === 0;
}
return false;
}
interface ReconcileState {
dropped: string[];
missing: string[];
invalid: string[];
migrated: boolean;
}
/** Runs migration chains and strict-parses the whole tree; pure, touches no instance. */
function reconcileNode(iface: AnyIface, doc: Json, path: string, state: ReconcileState): Json {
if (!isJsonObject(doc) || typeof doc.v !== "number" || doc.self === undefined) {
state.invalid.push(`${path}: not a parked node document`);
return doc;
}
let version = doc.v;
let self = doc.self;
if (version > iface.version) {
state.invalid.push(`${path}.v: parked under v${version}, newer than iface v${iface.version}`);
return doc;
}
// Migrator chain ships with the code (iface.migrations), auto-chained 1→2→3.
// MVP scope: migrations transform the node's own `self` document; reshaping
// children is out of scope for the chain and lands in `blocked` instead.
while (version < iface.version) {
const migrate = iface.migrations[version];
if (migrate === undefined) break;
self = migrate(self);
version += 1;
state.migrated = true;
}
if (version < iface.version) {
state.missing.push(`${path}.v: no migration path from v${version} to v${iface.version}`);
}
const parsed = iface.context.strictParse(self, `${path}.self`);
if (!parsed.ok) {
state.dropped.push(...parsed.dropped);
state.missing.push(...parsed.missing);
state.invalid.push(...parsed.invalid);
}
const docChildren = isJsonObject(doc.children) ? doc.children : {};
const children: { [name: string]: Json } = {};
for (const [name, decl] of Object.entries(iface.children)) {
const childPath = `${path}.children.${name}`;
const childDoc = docChildren[name];
if (isKeyed(decl)) {
const items: { [key: string]: Json } = {};
const itemsDoc = isJsonObject(childDoc) ? childDoc.items : undefined;
if (isJsonObject(itemsDoc)) {
for (const [key, itemDoc] of Object.entries(itemsDoc)) {
items[key] = reconcileNode(decl.iface, itemDoc, `${childPath}.items.${key}`, state);
}
}
children[name] = { items };
} else if (childDoc === undefined) {
state.missing.push(childPath);
} else {
children[name] = reconcileNode(decl, childDoc, childPath, state);
}
}
// Children the new iface no longer declares are discarded data — report
// them, UNLESS they are empty containers: an empty keyed collection (or a
// null slot) carries no data, so dropping it discards nothing (linear
// state tracks values, not shapes).
for (const [name, childDoc] of Object.entries(docChildren)) {
if (name in iface.children) continue;
if (isEmptyChildDoc(childDoc)) continue;
state.dropped.push(`${path}.children.${name}`);
}
const out: ParkedNode = { v: iface.version, self, children };
return out;
}
export async function upgrade<A extends Park, C extends Json>(opts: {
current: Instance<Park>;
impl: Impl<A, C>;
iface: Iface<A, C>;
resources: Resources;
/**
* A last word on a successor that booted: a reason it may not become current, or null.
* A refusal is a boot failure in every respect — the successor is disposed and the
* caller gets the parked document to recover the predecessor from.
*/
admit?: (instance: Instance<A>) => Promise<string | null> | string | null;
}): Promise<UpgradeResult<A>> {
const parked = opts.current.park();
const state: ReconcileState = { dropped: [], missing: [], invalid: [], migrated: false };
const doc = reconcileNode(opts.iface, parked, "$", state);
if (state.dropped.length > 0 || state.missing.length > 0 || state.invalid.length > 0) {
return {
status: "blocked",
dropped: state.dropped,
missing: state.missing,
invalid: state.invalid,
doc: parked,
};
}
// ONE transition, one failure channel: from here the old tree is coming down, so every
// way this can fail — a throwing disposer, a rejected drain, a successor that will not
// boot — has to hand the caller the parked document. A rejection escaping instead would
// leave a disposed tree with nothing booted in its place and no state to recover from,
// which is the one outcome this function exists to prevent.
let instance: Instance<A>;
try {
opts.current.dispose();
// A disposed tree may have an asynchronous tail — work its dispose effects aborted
// but could not await (effects are synchronous). An implementation exposes it as an
// optional in-process `drained` member; awaiting it HERE, between dispose and boot,
// is what makes a successor never race its predecessor.
await (opts.current.api as { drained?: () => Promise<void> | undefined }).drained?.();
instance = await boot(opts.impl, opts.iface, doc, opts.resources);
const refusal = opts.admit === undefined ? null : await opts.admit(instance);
if (refusal !== null) {
instance.dispose();
throw new Error(refusal);
}
} catch (error) {
return { status: "failed", error, doc: parked };
}
return { status: "ok", mode: state.migrated ? "migrated" : "silent", instance, doc };
}