@theoremjs/studio 0.0.0-stage → 0.3.1

package/server/save-plan.js

@@ -0,0 +1,1134 @@
+/**
+ * What Save writes: each changed value of a profile or a tool, found in the
+ * builder's file and rewritten there. A value written in the call is changed in
+ * place. A value from a constant is changed where the constant is set, when
+ * every profile and tool that reads the constant makes the same change, and the
+ * plan says when other code reads the constant too. A value from a constant that
+ * someone leaves as it was, or from code, is not written; the plan says where it
+ * is set and who shares it. A tool's schema is changed in the Zod that writes it,
+ * one part at a time (`zod-edit.ts`).
+ *
+ * @module
+ */
+import { MASK, unmaskUrl } from '@theoremjs/agents/surface';
+import ts from 'typescript';
+import { canonical } from "../canonical.js";
+import { definitionFactory } from "../providers.js";
+import { AGENTS_PACKAGE, valueSource } from "../source.js";
+import { keySource } from "../tool-schema.js";
+import { declares, definedAs, followed, holderOf, importExtension, isHeldId, isInCall, isInTarget, propertyName, providerNamed, shapeOf, sourceOf, specifierTo, unwrapped, usersOf, } from "./project-source.js";
+import { isWrittenOut, methodCall, methodSpan, readZod, unread, zodName, zodObject, zodSource, } from "./zod-edit.js";
+export const NOT_PLAIN = Symbol('not plain');
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** A value the page sent with each mask in it filled in from `written`, what the file holds there. */
+function fileHeld(shown, written) {
+    if (typeof shown !== 'string' || !shown.includes(MASK))
+        return shown;
+    return shown === MASK ? written : unmaskUrl(shown, written);
+}
+function same(a, b) {
+    return canonical(a) === canonical(b);
+}
+/** The value an expression writes out in full, or `NOT_PLAIN` when it names or computes anything. */
+export function plain(expression) {
+    const node = unwrapped(expression);
+    if (ts.isStringLiteralLike(node))
+        return node.text;
+    if (ts.isNumericLiteral(node))
+        return Number(node.text);
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand))
+        return -Number(node.operand.text);
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (node.kind === ts.SyntaxKind.NullKeyword)
+        return null;
+    if (ts.isArrayLiteralExpression(node)) {
+        const items = node.elements.map(plain);
+        return items.includes(NOT_PLAIN) ? NOT_PLAIN : items;
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+        const entries = [];
+        for (const property of node.properties) {
+            const name = propertyName(property);
+            if (name === undefined || !ts.isPropertyAssignment(property))
+                return NOT_PLAIN;
+            const value = plain(property.initializer);
+            if (value === NOT_PLAIN)
+                return NOT_PLAIN;
+            entries.push([name, value]);
+        }
+        return Object.fromEntries(entries);
+    }
+    // Lines joined: how the studio's own printer writes text of several lines.
+    if (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === 'join' &&
+        node.arguments.length === 1) {
+        const lines = plain(node.expression.expression);
+        const between = plain(node.arguments[0]);
+        if (Array.isArray(lines) &&
+            typeof between === 'string' &&
+            lines.every((line) => typeof line === 'string')) {
+            return lines.join(between);
+        }
+    }
+    return NOT_PLAIN;
+}
+/** The whitespace a line starts with. */
+export function indentAt(source, position) {
+    const { line } = source.getLineAndCharacterOfPosition(position);
+    const start = source.getPositionOfLineAndCharacter(line, 0);
+    return /^[ \t]*/.exec(source.text.slice(start))?.[0] ?? '';
+}
+/** One level of a file's indentation: a tab, or its narrowest run of spaces. */
+export function indentUnit(source) {
+    let narrowest = 0;
+    for (const line of source.text.split('\n')) {
+        if (line.startsWith('\t'))
+            return '\t';
+        const width = /^ +(?=\S)/.exec(line)?.[0].length ?? 0;
+        if (width && (!narrowest || width < narrowest))
+            narrowest = width;
+    }
+    return ' '.repeat(narrowest || 2);
+}
+/** Text of one line, in the quotes the file already uses at this spot. */
+/** Quotes as the text being replaced does. With no text there, as the file's first import does. */
+function quoteLike(existing, source) {
+    const first = existing && ts.isArrayLiteralExpression(existing)
+        ? existing.elements.find(ts.isStringLiteral)
+        : existing;
+    const like = first && ts.isStringLiteral(first)
+        ? first
+        : source.statements.find(ts.isImportDeclaration)?.moduleSpecifier;
+    const double = like?.getText(source).startsWith('"');
+    return (text) => {
+        const body = JSON.stringify(text);
+        if (double)
+            return body;
+        return `'${body.slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+    };
+}
+/** A tool's schemas, by the key its file writes each under. */
+const TOOL_SCHEMAS = {
+    inputSchema: { key: 'input', side: 'input' },
+    outputSchema: { key: 'output', side: 'output' },
+};
+/** The methods that say whether an object takes fields it does not name. */
+const OPEN_METHODS = new Set(['strict', 'passthrough', 'loose']);
+/** A new field's schema, written as Zod where a plain value would be. */
+class ZodField {
+    write;
+    constructor(write) {
+        this.write = write;
+    }
+}
+/** A value as source: a new field as its Zod, anything else as it is. */
+function written(value, style) {
+    return value instanceof ZodField ? value.write(style) : valueSource(value, style);
+}
+/** An object's fields written out, one to a line, for an object that held none. */
+function objectSource(entries, style) {
+    const inner = { ...style, base: style.base + style.unit };
+    const lines = entries.map(([key, value]) => `${inner.base}${keySource(key, style.quote)}: ${written(value, inner)},`);
+    return `{\n${lines.join('\n')}\n${style.base}}`;
+}
+const names = (value) => Array.isArray(value) ? value.filter((each) => typeof each === 'string') : [];
+const subjectId = (kind, of) => `${kind}:${of}`;
+const editsText = (edits) => canonical([...edits].sort((a, b) => a.start - b.start || a.end - b.end));
+/**
+ * Decides each shared value: its changes are written, once, when everyone it reaches makes the
+ * same ones. Otherwise each change to it is refused, so no profile runs on a value it did not test.
+ */
+function settle(shared, plan) {
+    for (const group of Map.groupBy(shared, (each) => each.holder).values()) {
+        const [first] = group;
+        if (!first)
+            continue;
+        const made = new Set(group.map((each) => each.by));
+        const agreed = first.everyone.every((user) => made.has(user)) &&
+            group.every((each) => editsText(each.edits) === editsText(first.edits));
+        for (const each of group)
+            plan.changes.push(...(agreed ? each.changes : each.refused));
+        if (!agreed)
+            continue;
+        for (const edit of first.edits) {
+            if (!plan.edits.some((other) => canonical(other) === canonical(edit)))
+                plan.edits.push(edit);
+        }
+    }
+}
+/** A node of the file a `z.` call is in. The call itself when none is named. */
+function located(call, node = call.call) {
+    return { node, source: call.source, ...(call.env ? { env: call.env } : {}) };
+}
+function partsOf(read) {
+    const { base } = read;
+    const [first] = base.call.arguments;
+    const part = first && !ts.isSpreadElement(first) ? located(base, first) : undefined;
+    const list = part && base.name === 'union' ? unwrapped(part.node) : undefined;
+    const members = list && ts.isArrayLiteralExpression(list) && !list.elements.some(ts.isSpreadElement)
+        ? list.elements
+        : undefined;
+    return { part, members };
+}
+/** Whether an object takes fields it does not name is the `z.` call it starts from. */
+function objectCall(more, side) {
+    if (more === true || (isRecord(more) && Object.keys(more).length === 0))
+        return 'looseObject';
+    if (more === false)
+        return side === 'input' ? 'strictObject' : 'object';
+    return more === undefined && side === 'input' ? 'object' : undefined;
+}
+/** The parts of a schema that are changed where they are written. A change to any other writes it again whole. */
+function inPlace(z, before, after, kind) {
+    const { part, members, read: { base }, } = z;
+    const reads = new Set(['description']);
+    if (z.object)
+        reads.add('properties').add('required');
+    if (kind)
+        reads.add('additionalProperties');
+    if (part && base.name === 'enum' && Array.isArray(before.enum) && Array.isArray(after.enum))
+        reads.add('enum');
+    if (part && base.name === 'array' && isRecord(before.items) && isRecord(after.items))
+        reads.add('items');
+    const [olds, news] = [before.anyOf, after.anyOf];
+    if (members &&
+        Array.isArray(olds) &&
+        Array.isArray(news) &&
+        olds.length === news.length &&
+        members.length === news.length) {
+        reads.add('anyOf');
+    }
+    return reads;
+}
+class Planner {
+    project;
+    subject;
+    target;
+    shared = [];
+    /** The subject's own call. Other profiles share it when a function makes the call for each. */
+    root;
+    /** What the subject alone writes: its own call, the arguments a function is called with for it. */
+    own = {
+        everyone: [],
+        sharedWith: [],
+        edits: [],
+        changes: [],
+        refused: [],
+    };
+    /** Each shared value the plan writes in, by where it is written. */
+    frames = new Map();
+    frame;
+    constructor(project, subject, target, peers) {
+        this.project = project;
+        this.subject = subject;
+        this.target = target;
+        const everyone = [subject.of, ...peers].map((name) => subjectId(subject.kind, name));
+        this.root = peers.length
+            ? {
+                holder: target.options,
+                everyone,
+                sharedWith: [...peers],
+                edits: [],
+                changes: [],
+                refused: [],
+            }
+            : this.own;
+        this.frame = this.root;
+    }
+    /** What the subject alone writes. */
+    get changes() {
+        return this.own.changes;
+    }
+    get edits() {
+        return this.own.edits;
+    }
+    note(...change) {
+        this.frame.changes.push(this.change(...change));
+    }
+    change(...[status, path, at, name, shared = {}]) {
+        return {
+            kind: this.subject.kind,
+            of: this.subject.of,
+            setting: path.join('.'),
+            status,
+            ...(at
+                ? {
+                    file: at.source.fileName,
+                    line: at.source.getLineAndCharacterOfPosition(at.node.getStart(at.source)).line + 1,
+                }
+                : {}),
+            ...(name ? { name } : {}),
+            // What is written in a value other code reads says so.
+            ...(status === 'written' && this.frame.readByCode ? { readByCode: true } : {}),
+            ...shared,
+        };
+    }
+    /** What holds `at`: the subject's own call, a constant, or a function, or nothing the studio follows. */
+    regionOf(at) {
+        if (isInTarget(this.target, at))
+            return this.target.options;
+        return isInCall(this.target, at) ? this.target.call?.node : holderOf(at)?.initializer;
+    }
+    /**
+     * Where a change to `origin` is written. In the subject's own call, or in a constant it alone
+     * reads, the change is the subject's. In a value others read too it is kept apart until the plan
+     * knows whether each of them makes it (`settle`). A value other code reads is written as any
+     * other, and each change to it says so. An id other code knows something by is not written.
+     */
+    frameAt(origin, name, path) {
+        if (isInTarget(this.target, origin))
+            return this.root;
+        if (isInCall(this.target, origin))
+            return this.own;
+        const holder = holderOf(origin);
+        if (!holder) {
+            this.note('constant', path, origin, name);
+            return undefined;
+        }
+        const users = usersOf(this.project, holder);
+        const everyone = [...users.profiles]
+            .map((id) => subjectId('profile', id))
+            .concat([...users.tools].map((tool) => subjectId('tool', tool)))
+            .concat([...users.providers].map((provider) => subjectId('provider', provider)));
+        const { kind, of } = this.subject;
+        const sharedWith = [...users.profiles]
+            .filter((id) => kind !== 'profile' || id !== of)
+            .concat([...users.tools].filter((tool) => kind !== 'tool' || tool !== of))
+            .concat([...users.providers].filter((provider) => kind !== 'provider' || provider !== of));
+        const refused = this.change('constant', path, origin, holder.name, {
+            ...(sharedWith.length ? { sharedWith } : {}),
+            ...(users.code ? { readByCode: true } : {}),
+        });
+        if (users.code && isHeldId(kind, path, origin)) {
+            this.frame.changes.push(refused);
+            return undefined;
+        }
+        if (!sharedWith.length && !users.code)
+            return this.own;
+        const frame = this.frames.get(holder.initializer) ?? {
+            holder: holder.initializer,
+            // Read by this one and by code: the change is this one's to make.
+            everyone: sharedWith.length ? everyone : [subjectId(kind, of)],
+            sharedWith,
+            readByCode: users.code,
+            edits: [],
+            changes: [],
+            refused: [],
+        };
+        this.frames.set(holder.initializer, frame);
+        frame.refused.push(refused);
+        return frame;
+    }
+    /** A value written somewhere other than where the walk is: changed there. */
+    enter(origin, name, before, after, path) {
+        const frame = this.frameAt(origin, name, path);
+        if (!frame)
+            return;
+        const outer = this.frame;
+        this.frame = frame;
+        this.walk(origin, before, after, path);
+        this.frame = outer;
+    }
+    /** A value a name, a key, or a call stands for. One the studio cannot follow is not written. */
+    named(at, name, before, after, path) {
+        const origin = followed(this.project, at);
+        const stayed = origin.node === unwrapped(at.node) && origin.source === at.source;
+        const named = ts.isIdentifier(origin.node) || ts.isPropertyAccessExpression(origin.node);
+        if (stayed)
+            this.note(named ? 'constant' : 'code', path, origin, named ? name : undefined);
+        else
+            this.enter(origin, name, before, after, path);
+    }
+    edit(source, start, end, written) {
+        // New lines end as the file's do. A template literal reads a carriage return as nothing.
+        const text = source.text.includes('\r\n') ? written.replace(/\r?\n/g, '\r\n') : written;
+        const edit = { file: source.fileName, start, end, text };
+        const held = this.frame.edits.some((other) => canonical(other) === canonical(edit));
+        if (!held)
+            this.frame.edits.push(edit);
+    }
+    style(source, position, existing) {
+        return {
+            unit: indentUnit(source),
+            base: indentAt(source, position),
+            template: true,
+            quote: quoteLike(existing, source),
+        };
+    }
+    /** The whole of the subject's call, and then what each shared value it wrote in holds. */
+    plan() {
+        const { options, source, env } = this.target;
+        this.walk({ node: options, source, env }, this.subject.before, this.subject.after, []);
+        const by = subjectId(this.subject.kind, this.subject.of);
+        const { root } = this;
+        if (root.holder && (root.changes.length || root.edits.length)) {
+            // A function makes this call for others too: what Save would write here, it writes for each.
+            const name = holderOf({ node: options, source })?.name;
+            const refused = root.changes.map((change) => change.status === 'written'
+                ? {
+                    ...change,
+                    status: 'constant',
+                    ...(name ? { name } : {}),
+                    sharedWith: root.sharedWith,
+                }
+                : change);
+            this.shared.push({ ...root, holder: root.holder, by, refused });
+        }
+        for (const frame of this.frames.values()) {
+            if (frame.holder && (frame.changes.length || frame.edits.length))
+                this.shared.push({ ...frame, holder: frame.holder, by });
+        }
+    }
+    walk(at, before, after, path) {
+        if (same(before, after))
+            return;
+        const node = unwrapped(at.node);
+        const here = { ...at, node };
+        const { source } = at;
+        const shape = isRecord(before) && isRecord(after) ? shapeOf(this.project, here) : undefined;
+        if (shape && isRecord(before) && isRecord(after)) {
+            this.object(shape, here, before, after, path);
+            return;
+        }
+        if (ts.isArrayLiteralExpression(node) &&
+            Array.isArray(before) &&
+            Array.isArray(after) &&
+            before.length === after.length &&
+            node.elements.length === after.length &&
+            !node.elements.some((element) => ts.isSpreadElement(element) || ts.isOmittedExpression(element))) {
+            node.elements.forEach((element, index) => {
+                this.walk({ ...at, node: element }, before[index], after[index], [...path, String(index)]);
+            });
+            return;
+        }
+        const value = plain(node);
+        if (value !== NOT_PLAIN) {
+            // A credential the page holds masked is the file's own text: the edit beside it keeps it.
+            if (this.subject.kind === 'tool' && typeof value === 'string') {
+                const [was, now] = [fileHeld(before, value), fileHeld(after, value)];
+                if (was !== before || now !== after) {
+                    this.walk(at, was, now, path);
+                    return;
+                }
+            }
+            if (!same(value, before)) {
+                this.note('changed', path, { source, node });
+                return;
+            }
+            this.write(here, after, path);
+            return;
+        }
+        this.named(here, node.getText(source), before, after, path);
+    }
+    /** Writes `after` over the plain value at `at`, in the file's own style. */
+    write(at, after, path) {
+        const { source, node } = at;
+        const start = node.getStart(source);
+        // A list's own quotes are for the list that replaces it.
+        const style = this.style(source, start, Array.isArray(after) || !ts.isArrayLiteralExpression(node) ? node : undefined);
+        // A list of plain values on one line stays on one line.
+        const inline = ts.isArrayLiteralExpression(node) &&
+            Array.isArray(after) &&
+            after.length > 0 &&
+            after.every((item) => item === null || typeof item !== 'object') &&
+            !node.getText(source).includes('\n');
+        const text = inline
+            ? `[${after.map((item) => valueSource(item, style)).join(', ')}]`
+            : valueSource(after, style);
+        this.edit(source, start, node.end, text);
+        this.note('written', path, { source, node });
+    }
+    /** Where a key of `shape` is written, or `at` when no property writes it. */
+    placeIn(shape, at, key) {
+        const entry = shape.entries.get(key);
+        return entry?.property ? { source: entry.source, node: entry.property } : at;
+    }
+    object(shape, at, before, after, path) {
+        const inserts = [];
+        const removed = [];
+        for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            if (same(before[key], after[key]))
+                continue;
+            const change = {
+                key,
+                before: before[key],
+                after: after[key],
+                here: [...path, key],
+            };
+            const schema = this.subject.kind === 'tool' && path.length === 0 ? TOOL_SCHEMAS[key] : undefined;
+            const entry = shape.entries.get(key);
+            if (this.subject.kind === 'provider' && path.length === 0 && key === 'definition')
+                this.redefine(change);
+            else if (schema)
+                this.toolSchema(shape, at, schema, change);
+            else if (!entry) {
+                if (this.isAdded(shape, at, change))
+                    inserts.push([key, change.after]);
+            }
+            else {
+                const gone = this.held(shape, at, entry, change);
+                if (gone)
+                    removed.push(gone);
+            }
+        }
+        if (shape.own)
+            this.refit(shape.own, inserts, removed, path);
+    }
+    /** A tool's schema is Zod in its file: each part that changed is changed there. */
+    toolSchema(shape, at, schema, change) {
+        const { before, after, here } = change;
+        const { open } = shape;
+        const held = shape.entries.get(schema.key);
+        if (!held)
+            this.note('code', here, at);
+        else if (!held.value || (open && !open.after.has(schema.key)))
+            this.note('code', here, this.placeIn(shape, at, schema.key));
+        else
+            this.zod(held.value, before, after, here, schema.side);
+    }
+    /** Whether a key the object does not hold is added to it. */
+    isAdded(shape, at, { after, here }) {
+        // Past a spread the studio could not follow, the object may hold the key already.
+        if (shape.open || !shape.own)
+            this.note('code', here, at);
+        else if (after === undefined)
+            this.note('unfound', here, at);
+        else
+            return true;
+        return false;
+    }
+    /** A key the object holds, changed where it is written. Gives the property when it is to be taken out. */
+    held(shape, at, entry, change) {
+        const { key, before, after, here } = change;
+        const { open, own } = shape;
+        const { property, value } = entry;
+        const place = this.placeIn(shape, at, key);
+        if (key === 'protocol' && value && ts.isIdentifier(unwrapped(value.node))) {
+            this.swapKernelName(value, before, after, here, place);
+        }
+        else if (entry.receiver && !(open && !open.after.has(key)))
+            this.reprovide(entry.receiver, value, change);
+        else if (!value || (open && !open.after.has(key)))
+            this.note('code', here, place);
+        else if (property && ts.isShorthandPropertyAssignment(property))
+            this.named(value, key, before, after, here);
+        else if (after === undefined) {
+            // A key another object spreads in is not this one's to take out.
+            if (!property || !own || property.parent !== own.node)
+                this.note('code', here, place);
+            else {
+                this.note('written', here, place);
+                return property;
+            }
+        }
+        else if (this.regionOf(value) === this.regionOf(at))
+            this.walk(value, before, after, here);
+        else
+            this.enter(value, key, before, after, here);
+        return undefined;
+    }
+    /**
+     * A model's provider, changed by rewriting the name its `model()` call is made on. The provider's
+     * own id is never written. A provider the project gives no name, or one this file cannot reach, is
+     * code's to change.
+     */
+    reprovide(receiver, id, { before, after, here }) {
+        const node = unwrapped(receiver.node);
+        const place = { source: receiver.source, node };
+        const to = typeof after === 'string' ? providerNamed(this.project, after) : undefined;
+        if (!id || !ts.isIdentifier(node) || !to)
+            return this.note('code', here, place);
+        if (!same(plain(unwrapped(followed(this.project, id).node)), before))
+            return this.note('changed', here, place);
+        const name = this.brought(receiver.source, to);
+        if (!name)
+            return this.note('code', here, place);
+        this.edit(receiver.source, node.getStart(receiver.source), node.end, name);
+        this.note('written', here, place);
+    }
+    /**
+     * A provider's definition, changed by registering the other kernel definition where its call
+     * names this one.
+     */
+    redefine({ before, after, here }) {
+        const call = this.target.options.parent;
+        const definition = ts.isCallExpression(call) ? call.arguments[0] : undefined;
+        const { source } = this.target;
+        if (!definition)
+            return this.note('code', here, { source, node: this.target.options });
+        const name = (value) => typeof value === 'string' ? definitionFactory(value) : undefined;
+        this.swapKernelName({ node: definition, source }, name(before), name(after), here, {
+            source,
+            node: definition,
+        });
+    }
+    /**
+     * A name the kernel package exports, written at `at`, changed to another of its exports: a
+     * provider's definition (`geminiProvider`) or a model's protocol (`geminiInteractions`). The new
+     * name is imported beside the old, in place of it when nothing else in the file reads the old one.
+     * A name the file does not import from the kernel is code's to change.
+     */
+    swapKernelName(at, before, after, here, place) {
+        const node = unwrapped(at.node);
+        const [from, to] = [before, after].map((value) => typeof value === 'string' ? value : undefined);
+        if (!from || !to || !ts.isIdentifier(node) || at.env?.bound.has(node.text))
+            return this.note('code', here, place);
+        const { source } = at;
+        const imported = namedImports(source);
+        const old = imported.find((element) => element.name.text === node.text);
+        if (!old)
+            return this.note('code', here, place);
+        if ((old.propertyName ?? old.name).text !== from)
+            return this.note('changed', here, place);
+        const held = imported.find((element) => (element.propertyName ?? element.name).text === to);
+        let name = held?.name.text;
+        if (!name) {
+            name = to;
+            if (declares(source, to))
+                return this.note('code', here, place);
+            // The import of the old name is the only other place that reads it: the new one takes its place.
+            if (reads(source, node.text) === 2)
+                this.edit(source, old.getStart(source), old.end, to);
+            else {
+                const last = old.parent.elements.at(-1) ?? old;
+                this.edit(source, last.end, last.end, `, ${to}`);
+            }
+        }
+        this.edit(source, node.getStart(source), node.end, name);
+        this.note('written', here, place);
+    }
+    /** The name `source` reads the provider `to` by, importing it when the file does not yet. Undefined when it cannot. */
+    brought(source, to) {
+        if (to.source === source)
+            return to.name;
+        const imports = source.statements.filter((statement) => ts.isImportDeclaration(statement) &&
+            ts.isStringLiteralLike(statement.moduleSpecifier) &&
+            !statement.importClause?.isTypeOnly &&
+            sourceOf(this.project, source, statement.moduleSpecifier.text) ===
+                to.source);
+        const named = imports.flatMap((statement) => {
+            const bindings = statement.importClause?.namedBindings;
+            return bindings && ts.isNamedImports(bindings) ? [bindings] : [];
+        });
+        const held = named
+            .flatMap((bindings) => [...bindings.elements])
+            .find((element) => !element.isTypeOnly && (element.propertyName ?? element.name).text === to.name);
+        if (held)
+            return held.name.text;
+        if (!to.exported || declares(source, to.name))
+            return undefined;
+        const last = named[0]?.elements.at(-1);
+        if (last)
+            this.edit(source, last.end, last.end, `, ${to.name}`);
+        else {
+            const specifier = specifierTo(source.fileName, to.source.fileName, importExtension(this.project, '.ts'));
+            const line = `import { ${to.name} } from ${quoteLike(undefined, source)(specifier)};`;
+            const after = source.statements.findLast((statement) => ts.isImportDeclaration(statement));
+            if (after)
+                this.edit(source, after.end, after.end, `\n${line}`);
+            else
+                this.edit(source, 0, 0, `${line}\n`);
+        }
+        return to.name;
+    }
+    /** Takes properties out of an object and adds others to it. */
+    refit(own, inserts, removed, path) {
+        if (inserts.length && removed.length === own.node.properties.length) {
+            // Every property goes and others come: the object is written whole, as an empty one is.
+            for (const [key] of inserts)
+                this.note('written', [...path, key], own);
+            const start = own.node.getStart(own.source);
+            this.edit(own.source, start, own.node.end, valueSource(Object.fromEntries(inserts), this.style(own.source, start)));
+            return;
+        }
+        if (this.emptied(own.node, own.source, removed, inserts))
+            return;
+        for (const held of removed)
+            this.remove(held, own.source);
+        if (inserts.length)
+            this.insert(own.node, own.source, inserts, path);
+    }
+    /** Runs `write` where `at` is written: in the subject's own call, or in the constant that holds it. */
+    within(at, path, write) {
+        const frame = this.frameAt(at, at.node.getText(at.source), path);
+        if (!frame)
+            return;
+        const outer = this.frame;
+        this.frame = frame;
+        write();
+        this.frame = outer;
+    }
+    /**
+     * A schema, in the Zod that writes it. A description, the values of an enum, whether a field
+     * can be left out, and a field added or taken away are each changed where they are written,
+     * through any constant that holds them. Any other change writes the schema again whole, when
+     * it is written out where it stands in Zod the studio writes itself. What is left is for code.
+     */
+    zod(at, before, after, path, side, left = { was: false, now: false, path }) {
+        if (same(before, after) && left.was === left.now)
+            return;
+        const site = { ...at, node: unwrapped(at.node) };
+        const where = { source: site.source, node: site.node };
+        const read = readZod(this.project, site);
+        if (!read || !isRecord(before) || !isRecord(after)) {
+            this.note('code', path, where);
+            return;
+        }
+        const stopped = unread(read);
+        if (stopped) {
+            this.note('code', path, { source: stopped.source, node: stopped.call });
+            return;
+        }
+        const z = {
+            site,
+            where,
+            read,
+            ...partsOf(read),
+            object: zodObject(this.project, read),
+        };
+        const change = { before, after, path, side, left };
+        const kind = z.object ? objectCall(after.additionalProperties, side) : undefined;
+        const reads = inPlace(z, before, after, kind);
+        const changed = [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((key) => !same(before[key], after[key]));
+        if (changed.some((key) => !reads.has(key))) {
+            this.rewritten(site, after, left.now, path, side);
+            return;
+        }
+        this.zodAdded(z, change);
+        if (kind)
+            this.zodOpen(z, kind, change);
+        this.zodInner(z, reads, change);
+        if (z.object)
+            this.zodFields(z.object, change);
+    }
+    /** Takes a method off a schema. */
+    cut(call) {
+        const { start, end } = methodSpan(call);
+        this.edit(call.source, start, end, '');
+    }
+    /** What is added to the schema goes after it, where it is used. */
+    zodAdded(z, change) {
+        const { site, where } = z;
+        const adds = [this.described(z, change), this.leftOut(z, change.left)].filter((each) => each !== undefined);
+        const added = adds.map((each) => each.text).join('');
+        // One edit holds all that is added; each setting it adds is its own change.
+        adds.forEach(({ path: here }, index) => {
+            this.within(site, here, () => {
+                if (index === 0)
+                    this.edit(site.source, site.node.end, site.node.end, added);
+                this.note('written', here, where);
+            });
+        });
+    }
+    /** A schema's description, changed where it is written. Gives the method that adds one. */
+    described(z, { before, after, path }) {
+        const [was, now] = [before.description, after.description];
+        if (same(was, now))
+            return undefined;
+        const here = [...path, 'description'];
+        const { site, where } = z;
+        if (now !== undefined && typeof now !== 'string')
+            this.note('code', here, where);
+        else if (was === undefined && now !== undefined) {
+            const text = `.describe(${valueSource(now, this.style(site.source, site.node.getStart(site.source)))})`;
+            return { text, path: here };
+        }
+        else
+            this.redescribed(z, was, now, here);
+        return undefined;
+    }
+    /** A description the schema has, written again or taken off. */
+    redescribed(z, was, now, here) {
+        const describe = methodCall(z.read, 'describe');
+        const [text] = describe?.call.arguments ?? [];
+        if (!describe || !text || ts.isSpreadElement(text)) {
+            this.note('code', here, z.where);
+            return;
+        }
+        const call = located(describe);
+        this.within(call, here, () => {
+            if (now !== undefined) {
+                this.walk({ ...call, node: text }, was, now, here);
+                return;
+            }
+            this.cut(describe);
+            this.note('written', here, { source: describe.source, node: describe.call });
+        });
+    }
+    /** Whether a field can be left out, changed where it is written. Gives the method that lets it be. */
+    leftOut(z, left) {
+        if (!left.was && left.now)
+            return { text: '.optional()', path: left.path };
+        if (!left.was || left.now)
+            return undefined;
+        const optional = methodCall(z.read, 'optional');
+        if (!optional)
+            this.note('code', left.path, z.where);
+        else {
+            this.within({ node: optional.call, source: optional.source }, left.path, () => {
+                this.cut(optional);
+                this.note('written', left.path, { source: optional.source, node: optional.call });
+            });
+        }
+        return undefined;
+    }
+    /** Whether an object takes fields it does not name, said by the `z.` call it starts from. */
+    zodOpen(z, kind, { before, after, path }) {
+        if (same(before.additionalProperties, after.additionalProperties))
+            return;
+        const { base, chain } = z.read;
+        const here = [...path, 'additionalProperties'];
+        // A method that says it is taken away, and the call says it instead.
+        for (const call of chain.filter((each) => OPEN_METHODS.has(each.name))) {
+            this.within({ node: call.call, source: call.source }, here, () => this.cut(call));
+        }
+        this.within(located(base), here, () => {
+            const name = base.call.expression.name;
+            if (name.text !== kind)
+                this.edit(base.source, name.getStart(base.source), name.end, kind);
+            this.note('written', here, { source: base.source, node: base.call });
+        });
+    }
+    /** What a schema holds inside its `z.` call: an enum's values, a list's items, a union's members. */
+    zodInner(z, reads, { before, after, path, side }) {
+        const { part, members, read } = z;
+        if (part && reads.has('enum') && !same(before.enum, after.enum)) {
+            const here = [...path, 'enum'];
+            this.within(located(read.base), here, () => this.walk(part, before.enum, after.enum, here));
+        }
+        if (part && reads.has('items'))
+            this.zod(part, before.items, after.items, [...path, 'items'], side);
+        const [olds, news] = [before.anyOf, after.anyOf];
+        if (members && reads.has('anyOf') && Array.isArray(olds) && Array.isArray(news)) {
+            members.forEach((member, index) => {
+                this.zod(located(read.base, member), olds[index], news[index], [...path, 'anyOf', String(index)], side);
+            });
+        }
+    }
+    /** An object schema's fields: each one changed, added, or taken away. */
+    zodFields(object, { before, after, path, side }) {
+        const [fields, held] = [
+            isRecord(before.properties) ? before.properties : {},
+            isRecord(after.properties) ? after.properties : {},
+        ];
+        const [needed, needs] = [names(before.required), names(after.required)];
+        const own = { node: object.own.node, source: object.own.source };
+        const inserts = [];
+        const removed = [];
+        for (const key of new Set([...Object.keys(fields), ...Object.keys(held)])) {
+            const here = [...path, 'properties', key];
+            const entry = object.entries.get(key);
+            const optional = {
+                was: !needed.includes(key),
+                now: !needs.includes(key),
+                path: [...path, 'required', key],
+            };
+            if (key in fields && key in held) {
+                if (entry?.value)
+                    this.zod(entry.value, fields[key], held[key], here, side, optional);
+                else if (!same(fields[key], held[key]) || optional.was !== optional.now)
+                    this.note('code', here, own);
+            }
+            else if (key in held) {
+                const field = this.fieldAdded(object, held[key], optional.now, side, here);
+                if (field)
+                    inserts.push([key, field]);
+            }
+            else {
+                const gone = this.fieldTaken(object, entry, here);
+                if (gone)
+                    removed.push(gone);
+            }
+        }
+        if (inserts.length || removed.length)
+            this.refield(object, inserts, removed, [...path, 'properties']);
+    }
+    /** A field to add, as the Zod that writes it. */
+    fieldAdded(object, schema, optional, side, here) {
+        const name = zodName(object.own.source);
+        // The field is written as Zod once here, to know that it can be.
+        if (!name || zodSource(schema, optional, side, name) === undefined) {
+            this.note('code', here, object.own);
+            return undefined;
+        }
+        return new ZodField((style) => zodSource(schema, optional, side, name, style) ?? '');
+    }
+    /** A field taken away. Gives its property when the object's own literal writes it. */
+    fieldTaken(object, entry, here) {
+        const property = entry?.property;
+        if (!entry || !property || !ts.isObjectLiteralExpression(property.parent))
+            this.note('code', here, object.own);
+        else if (property.parent === object.own.node)
+            return property;
+        else {
+            this.within({ node: property.parent, source: entry.source }, here, () => {
+                this.remove(property, entry.source);
+                this.note('written', here, { source: entry.source, node: property });
+            });
+        }
+        return undefined;
+    }
+    /** Takes fields out of an object schema's own literal and adds others to it. */
+    refield(object, inserts, removed, inFields) {
+        const { node, source } = object.own;
+        const own = { node, source };
+        this.within(own, inFields, () => {
+            for (const property of removed) {
+                this.note('written', [...inFields, propertyName(property) ?? ''], {
+                    source,
+                    node: property,
+                });
+            }
+            if (inserts.length && removed.length === node.properties.length) {
+                // Every field goes and others come: the object is written whole.
+                for (const [key] of inserts)
+                    this.note('written', [...inFields, key], own);
+                const start = node.getStart(source);
+                this.edit(source, start, node.end, objectSource(inserts, this.style(source, start)));
+                return;
+            }
+            if (this.emptied(node, source, removed, inserts))
+                return;
+            for (const property of removed)
+                this.remove(property, source);
+            if (inserts.length)
+                this.insert(node, source, inserts, inFields);
+        });
+    }
+    /** A schema written again whole, from its JSON Schema, where it stands. */
+    rewritten(site, after, optional, path, side) {
+        const where = { source: site.source, node: site.node };
+        const name = zodName(site.source);
+        const start = site.node.getStart(site.source);
+        const text = name && isWrittenOut(this.project, site)
+            ? zodSource(after, optional, side, name, this.style(site.source, start))
+            : undefined;
+        if (text === undefined) {
+            this.note('code', path, where);
+            return;
+        }
+        this.within(site, path, () => {
+            this.edit(site.source, start, site.node.end, text);
+            this.note('written', path, where);
+        });
+    }
+    /**
+     * An object every property leaves and none comes to, written `{}`. Not when it holds a comment
+     * no property takes with it, which would go too.
+     */
+    emptied(node, source, removed, inserts) {
+        if (inserts.length || removed.length !== node.properties.length)
+            return false;
+        const start = node.getStart(source);
+        let rest = source.text.slice(start + 1, node.end - 1);
+        for (const property of node.properties)
+            rest = rest.replace(property.getFullText(source), '');
+        if (!/^[\s,]*$/.test(rest))
+            return false;
+        this.edit(source, start, node.end, '{}');
+        return true;
+    }
+    /** Takes a property out, with its comma and the comment that leads it. */
+    remove(property, source) {
+        const { text } = source;
+        let start = property.getFullStart();
+        let end = property.end;
+        const comma = /^[ \t]*,/.exec(text.slice(end));
+        if (comma)
+            end += comma[0].length;
+        else if (text[start - 1] === ',')
+            start -= 1;
+        this.edit(source, start, end, '');
+    }
+    /** Adds properties after the last one the object has. */
+    insert(node, source, entries, path) {
+        for (const [key] of entries)
+            this.note('written', [...path, key], { source, node });
+        const last = node.properties.at(-1);
+        const start = node.getStart(source);
+        if (!last) {
+            this.edit(source, start, node.end, objectSource(entries, this.style(source, start)));
+            return;
+        }
+        const trailing = node.properties.hasTrailingComma;
+        const brace = node.end - 1;
+        const braceLine = source.getLineAndCharacterOfPosition(brace).line;
+        const ownLine = source.getLineAndCharacterOfPosition(last.end).line < braceLine;
+        if (ownLine) {
+            // On lines of their own, before the closing brace, so a comment after the last one stays with it.
+            const base = indentAt(source, last.getStart(source));
+            const style = { ...this.style(source, start), base };
+            const lines = entries.map(([key, value]) => `${base}${keySource(key, style.quote)}: ${written(value, style)},\n`);
+            if (!trailing)
+                this.edit(source, last.end, last.end, ',');
+            const at = source.getPositionOfLineAndCharacter(braceLine, 0);
+            this.edit(source, at, at, lines.join(''));
+            return;
+        }
+        const style = this.style(source, start);
+        const fields = entries
+            .map(([key, value]) => `${keySource(key, style.quote)}: ${written(value, style)}`)
+            .join(', ');
+        if (trailing)
+            this.edit(source, node.properties.end, node.properties.end, ` ${fields},`);
+        else
+            this.edit(source, last.end, last.end, `, ${fields}`);
+    }
+}
+/** Finds each subject's call in the project and plans its changes. */
+export function planSave(project, subjects) {
+    const plan = { changes: [], edits: [] };
+    const shared = [];
+    for (const subject of subjects) {
+        if (same(subject.before, subject.after))
+            continue;
+        const defined = definedAs(project, subject.kind);
+        const targets = defined.get(subject.of) ?? [];
+        const whole = { kind: subject.kind, of: subject.of, setting: '' };
+        const [target] = targets;
+        if (!target) {
+            plan.changes.push({ ...whole, status: 'unfound' });
+            continue;
+        }
+        if (targets.length > 1) {
+            // Written twice: the studio cannot tell which one runs.
+            const line = target.source.getLineAndCharacterOfPosition(target.options.getStart(target.source)).line +
+                1;
+            plan.changes.push({ ...whole, status: 'code', file: target.file, line });
+            continue;
+        }
+        // The others a function makes this same call for.
+        const peers = [...defined]
+            .filter(([name, held]) => name !== subject.of && held.some((other) => other.options === target.options))
+            .map(([name]) => name);
+        const planner = new Planner(project, subject, target, peers);
+        planner.plan();
+        plan.changes.push(...planner.changes);
+        // Two subjects may bring the same import into one file: it is written once.
+        for (const edit of planner.edits) {
+            if (!plan.edits.some((other) => canonical(other) === canonical(edit)))
+                plan.edits.push(edit);
+        }
+        shared.push(...planner.shared);
+    }
+    settle(shared, plan);
+    return plan;
+}
+/** `text` with the edits made. Throws when two edits touch the same characters. */
+export function applyEdits(text, edits) {
+    const ordered = edits
+        .map((edit, index) => ({ edit, index }))
+        .sort((a, b) => a.edit.start - b.edit.start || a.index - b.index);
+    let out = '';
+    let cursor = 0;
+    for (const { edit } of ordered) {
+        if (edit.start < cursor)
+            throw new Error('Two changes touch the same text.');
+        out += text.slice(cursor, edit.start) + edit.text;
+        cursor = edit.end;
+    }
+    return out + text.slice(cursor);
+}
+const CONTEXT_LINES = 2;
+/** The changed lines of one file, from the edits made to it. */
+export function diffHunks(text, edits) {
+    const lines = text.split('\n');
+    const starts = [];
+    let offset = 0;
+    for (const line of lines) {
+        starts.push(offset);
+        offset += line.length + 1;
+    }
+    const lineOf = (position) => {
+        let low = 0;
+        let high = starts.length - 1;
+        while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            if ((starts[mid] ?? 0) <= position)
+                low = mid;
+            else
+                high = mid - 1;
+        }
+        return low;
+    };
+    const ordered = [...edits].sort((a, b) => a.start - b.start);
+    const groups = [];
+    for (const edit of ordered) {
+        const first = lineOf(edit.start);
+        const last = lineOf(edit.end);
+        const open = groups.at(-1);
+        if (open && first <= open.last) {
+            open.last = Math.max(open.last, last);
+            open.edits.push(edit);
+        }
+        else
+            groups.push({ first, last, edits: [edit] });
+    }
+    return groups.flatMap((group) => {
+        const from = starts[group.first] ?? 0;
+        const to = (starts[group.last] ?? 0) + (lines[group.last]?.length ?? 0);
+        const local = group.edits.map((edit) => ({
+            ...edit,
+            start: edit.start - from,
+            end: edit.end - from,
+        }));
+        const was = lines.slice(group.first, group.last + 1);
+        const now = applyEdits(text.slice(from, to), local).split('\n');
+        let head = 0;
+        while (head < was.length && head < now.length && was[head] === now[head])
+            head++;
+        let tail = 0;
+        while (tail < was.length - head &&
+            tail < now.length - head &&
+            was[was.length - 1 - tail] === now[now.length - 1 - tail])
+            tail++;
+        const removed = was.slice(head, was.length - tail);
+        const added = now.slice(head, now.length - tail);
+        if (!removed.length && !added.length)
+            return [];
+        const at = group.first + head;
+        const after = at + removed.length;
+        return [
+            {
+                line: at + 1,
+                lead: lines.slice(Math.max(0, at - CONTEXT_LINES), at),
+                removed,
+                added,
+                trail: lines.slice(after, after + CONTEXT_LINES),
+            },
+        ];
+    });
+}
+/** Each name the file imports by name from the kernel package, as values. */
+function namedImports(source) {
+    return source.statements.flatMap((statement) => {
+        if (!ts.isImportDeclaration(statement) || statement.importClause?.isTypeOnly)
+            return [];
+        const from = statement.moduleSpecifier;
+        if (!ts.isStringLiteralLike(from) || from.text !== AGENTS_PACKAGE)
+            return [];
+        const bindings = statement.importClause?.namedBindings;
+        return bindings && ts.isNamedImports(bindings)
+            ? bindings.elements.filter((element) => !element.isTypeOnly)
+            : [];
+    });
+}
+/** How many times the file names `name`, its import included. */
+function reads(source, name) {
+    let count = 0;
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && node.text === name)
+            count += 1;
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return count;
+}