@prestack/thread 0.1.21 → 0.1.22

package/dist/operations/generators/capability.js

@@ -12,16 +12,17 @@ import { dirname, resolve } from 'node:path';
 import { argv, stdout } from 'node:process';
 import { pathToFileURL } from 'node:url';
 import { ROOT, TREE, descend, forget } from '../../core/descend.js';
+import { declaresUi, findTree } from '../../core/tree.js';
 import { exit, invoked } from '../../core/invoked.js';
 import { named as packageOf } from '../../core/scope.js';
 import { PREFIXES } from '../../core/thread.js';
 import { secrecyOf } from '../../integrations/secret.js';
 import { reachOf, servesBrowser, targetOf } from '../../integrations/target.js';
-import { CAPABILITIES_AT, CLIENT_AT, MCP_AT, OPENAPI_AT, REACHING_AT, ACTOR_AT, DEFAULTS_AT, DISPATCHING_AT, CHECKED_AT, inboundAt, isSurface, ROUTE, routeAt, SURFACES, switched, UNSTATED, } from '../capabilities.js';
+import { CAPABILITIES_AT, SERVER_AT, SERVER_OUT, CLIENT_AT, MCP_AT, OPENAPI_AT, REACHING_AT, ACTOR_AT, DEFAULTS_AT, DISPATCHING_AT, CHECKED_AT, inboundAt, isSurface, ROUTE, routeAt, SURFACES, switched, UNSTATED, } from '../capabilities.js';
 import { ANONYMOUS, ENVIRONMENT } from '../../core/actor.js';
 import { DISPATCH_AT } from '../dispatch.js';
 import { STREAMED, TOLD } from '../../integrations/https.js';
-import { holdsRow, listBounds, marked, nestedBounds, rowsIn, unread, valuesIn, withField, withRow, withTopField, withoutRow } from '../../core/rows.js';
+import { holdsRow, listBounds, nestedBounds, rowsIn, unread, valuesIn, withField, withRow, withTopField, withoutRow } from '../../core/rows.js';
 import { said } from '../attach.js';
 import { MEMBERS_LIST } from '../operations.js';
 import { beside, operations, quoted, runtime, types } from './seed.js';
@@ -322,7 +323,7 @@ function client(found) {
 function route(one) {
     const at = routeAt(one.operation);
     return [
-        `import { existsSync } from ${quoted(runtime(at, '../../integrations/disk.ts'))}`,
+        "import { existsSync } from 'node:fs'",
         "import { join } from 'node:path'",
         '',
         'import { counting, DECLARED, opening } from ' + quoted(beside(at, REACHING_AT)),
@@ -378,7 +379,7 @@ function inbound(one) {
         ", because: " + quoted(why) + " }, { status: 403 })";
     return [
         ...(signed ? ["import { createHmac, timingSafeEqual } from " + quoted("node:crypto")] : []),
-        "import { existsSync } from " + quoted(runtime(at, "../../integrations/disk.ts")),
+        "import { existsSync } from " + quoted("node:fs"),
         "import { join } from " + quoted("node:path"),
         "",
         "import { counting, DECLARED, opening } from " + quoted(beside(at, REACHING_AT)),
@@ -692,22 +693,220 @@ function caller(keeping, kept) {
 }
 const carries = () => existsSync(resolve(ROOT, 'node_modules', packageOf('operations')));
 const emitted = () => existsSync(resolve(ROOT, CHECKED_AT));
-const files = (found, targets, calls, keeps, webhooks = []) => [
-    { at: CAPABILITIES_AT, text: printed(found) },
-    { at: OPENAPI_AT, text: printed(openapi(found)) },
-    { at: MCP_AT, text: printed(mcp(found)) },
-    { at: CLIENT_AT, text: client(found) },
-    { at: REACHING_AT, text: reaching(targets, calls, kept(), existsSync(resolve(ROOT, VAULT_AT)), carries()) },
-    { at: ACTOR_AT, text: caller(existsSync(resolve(ROOT, ENTITIES_AT)), keeps) },
-    ...(emitted() ? [{ at: DISPATCHING_AT, text: dispatching(found) }] : []),
-    ...found.filter(served).map((one) => ({ at: routeAt(one.operation), text: route(one) })),
-    ...webhooks
-        .filter((one) => found.some((each) => each.operation === one.invokes && each.live.includes('webhook') && each.webhooks.includes(one.id) && compiled(one.invokes)))
-        .flatMap((one) => {
-        const at = (one.derives ?? []).map((each) => each.at).find((each) => each === inboundAt(one.id));
-        return at === undefined ? [] : [{ at, text: inbound(one) }];
-    }),
-];
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+function routeSegments(at) {
+    const parts = at.split('/');
+    if (parts.length < 2 || parts[0] !== 'app' || parts[parts.length - 1] !== 'route.ts')
+        return undefined;
+    return parts.slice(1, -1);
+}
+function methodsIn(source) {
+    const file = ts.createSourceFile(SERVER_AT, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const found = [];
+    for (const statement of file.statements) {
+        const shown = ((ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined) ?? []).some((one) => one.kind === ts.SyntaxKind.ExportKeyword);
+        if (!shown)
+            continue;
+        if (ts.isFunctionDeclaration(statement) && statement.name !== undefined && METHODS.includes(statement.name.text)) {
+            found.push(statement.name.text);
+        }
+        else if (ts.isVariableStatement(statement)) {
+            for (const one of statement.declarationList.declarations) {
+                if (ts.isIdentifier(one.name) && METHODS.includes(one.name.text))
+                    found.push(one.name.text);
+            }
+        }
+    }
+    return found;
+}
+function servedByNode() {
+    const pass = descend();
+    const routes = [];
+    for (const at of pass.threaded.keys()) {
+        const segments = routeSegments(at);
+        if (segments === undefined)
+            continue;
+        const path = resolve(ROOT, at);
+        if (!existsSync(path))
+            continue;
+        const methods = methodsIn(readFileSync(path, 'utf8'));
+        if (methods.length === 0)
+            continue;
+        routes.push({ at, segments, methods });
+    }
+    const dynamism = (one) => one.segments.filter((word) => word.startsWith('[')).length;
+    routes.sort((a, b) => dynamism(a) - dynamism(b) || compare(a.at, b.at));
+    return { hasUi: declaresUi(findTree()), routes };
+}
+function identifier(segments, method) {
+    const plain = segments.map((one) => one.split('[').join('').split(']').join('')).join('_');
+    const base = plain.replace(/[^A-Za-z0-9_$]/g, '_') || 'root';
+    return `${/^[0-9]/.test(base) ? '_' : ''}${base}_${method}`;
+}
+function entry(routes) {
+    const table = routes.map((one) => {
+        const segments = one.segments.map((word) => quoted(word)).join(', ');
+        const methods = one.methods.map((method) => `${method}: ${identifier(one.segments, method)}`).join(', ');
+        return `  { segments: [${segments}], methods: { ${methods} } },`;
+    });
+    return [
+        "import { createServer } from 'node:http'",
+        "import { Readable } from 'node:stream'",
+        '',
+        ...routes.map((one) => `import { ${one.methods.map((method) => `${method} as ${identifier(one.segments, method)}`).join(', ')} } from ${quoted(beside(SERVER_AT, one.at))}`),
+        '',
+        'interface Route {',
+        '  readonly segments: readonly string[]',
+        '  readonly methods: Readonly<Record<string, (request: Request, context: { readonly params: Readonly<Record<string, string>> }) => Response | Promise<Response>>>',
+        '}',
+        '',
+        'const ROUTES: readonly Route[] = [',
+        ...table,
+        ']',
+        '',
+        'function matched(pathname: string): (Route & { readonly params: Readonly<Record<string, string>> }) | undefined {',
+        "  const wanted = pathname.split('/').filter((one) => one.length > 0)",
+        '  for (const route of ROUTES) {',
+        '    if (route.segments.length !== wanted.length) continue',
+        '    const params: Record<string, string> = {}',
+        '    const ok = route.segments.every((segment, at) => {',
+        "      if (segment.startsWith('[') && segment.endsWith(']')) {",
+        '        params[segment.slice(1, -1)] = decodeURIComponent(wanted[at] as string)',
+        '        return true',
+        '      }',
+        '      return segment === wanted[at]',
+        '    })',
+        '    if (ok) return { ...route, params }',
+        '  }',
+        '  return undefined',
+        '}',
+        '',
+        'const PORT = Number(process.env.PORT ?? 3000)',
+        "const HOSTNAME = process.env.HOSTNAME ?? '0.0.0.0'",
+        '',
+        'createServer((req, res) => {',
+        '  const host = req.headers.host ?? `${HOSTNAME}:${String(PORT)}`',
+        "  const url = new URL(req.url ?? '/', `http://${host}`)",
+        '  const route = matched(url.pathname)',
+        '  if (route === undefined) {',
+        '    res.writeHead(404)',
+        '    res.end()',
+        '    return',
+        '  }',
+        "  const method = (req.method ?? 'GET').toUpperCase()",
+        '  const handler = route.methods[method]',
+        '  if (handler === undefined) {',
+        "    res.writeHead(405, { allow: Object.keys(route.methods).join(', ') })",
+        '    res.end()',
+        '    return',
+        '  }',
+        '  const controller = new AbortController()',
+        "  res.on('close', () => {",
+        '    if (!res.writableEnded) controller.abort()',
+        '  })',
+        '  const headers = new Headers()',
+        '  for (const [key, value] of Object.entries(req.headers)) {',
+        '    if (value === undefined) continue',
+        '    for (const one of Array.isArray(value) ? value : [value]) headers.append(key, one)',
+        '  }',
+        '  const request = new Request(url.href, {',
+        '    method,',
+        '    headers,',
+        "    body: method === 'GET' || method === 'HEAD' ? undefined : Readable.toWeb(req),",
+        '    signal: controller.signal,',
+        "    duplex: 'half',",
+        '  } as never)',
+        '  Promise.resolve(handler(request, { params: route.params }))',
+        '    .then((answered) => {',
+        '      const said: Record<string, string> = {}',
+        '      answered.headers.forEach((value, key) => {',
+        '        said[key] = value',
+        '      })',
+        '      res.writeHead(answered.status, said)',
+        '      if (answered.body === null) {',
+        '        res.end()',
+        '        return',
+        '      }',
+        '      Readable.fromWeb(answered.body as never).pipe(res)',
+        '    })',
+        '    .catch((thrown: unknown) => {',
+        '      console.error(thrown instanceof Error ? thrown.stack ?? thrown.message : thrown)',
+        '      if (!res.headersSent) res.writeHead(500)',
+        '      res.end()',
+        '    })',
+        '}).listen(PORT, HOSTNAME)',
+        '',
+    ].join('\n');
+}
+const SERVER_ENTRY_DESCRIBES = 'The server this app runs when it declares no `ui`. It imports every route this app declares, reads the path and method off each request, and calls the one that answers: 404 for a path nothing declares, 405 naming the methods that do answer when the path matches and the method does not, 500 with nothing of the error in the body when the route it calls throws. `thread capabilities` writes it only while this app has no `ui`, because an app that has one is served by Next instead, and takes both it and its row out the moment that changes.';
+const SERVER_DESCRIBES = 'The server entry bundled into the one file this app is actually started from. `thread build` writes it the same way it writes every other declared artifact, so what a released app starts is compiled code rather than the source of this framework.';
+function entered(hasUi, writing) {
+    const sheet = resolve(ROOT, OPERATIONS_AT);
+    if (!existsSync(sheet))
+        return [];
+    const text = readFileSync(sheet, 'utf8');
+    const where = listBounds(text, 'derives');
+    if (where === undefined)
+        return [];
+    const holds = holdsRow(text, where, 'server-entry');
+    const wants = !hasUi;
+    if (wants === holds)
+        return [];
+    const wrong = [
+        wants
+            ? `this app declares no ui, and its row does not derive ${SERVER_AT}`
+            : `this app declares ui, and its row still derives ${SERVER_AT}`,
+    ];
+    if (!writing)
+        return wrong;
+    const next = wants
+        ? withRow(text, where, said({
+            id: 'server-entry',
+            at: SERVER_AT,
+            describes: SERVER_ENTRY_DESCRIBES,
+            version: 1,
+            by: 'thread capabilities',
+            runs: 'thread capabilities --check',
+            derives: [
+                {
+                    id: 'server',
+                    at: SERVER_OUT,
+                    describes: SERVER_DESCRIBES,
+                    version: 1,
+                    by: 'thread build',
+                    runs: 'thread build --check',
+                },
+            ],
+        }, '    '))
+        : withoutRow(text, where, 'server-entry');
+    writeFileSync(sheet, next, 'utf8');
+    return wrong;
+}
+function unentered(hasUi) {
+    if (!hasUi)
+        return [];
+    return [SERVER_AT, SERVER_OUT].filter((at) => existsSync(resolve(ROOT, at)));
+}
+const files = (found, targets, calls, keeps, webhooks = []) => {
+    const { hasUi, routes } = servedByNode();
+    return [
+        { at: CAPABILITIES_AT, text: printed(found) },
+        { at: OPENAPI_AT, text: printed(openapi(found)) },
+        { at: MCP_AT, text: printed(mcp(found)) },
+        { at: CLIENT_AT, text: client(found) },
+        { at: REACHING_AT, text: reaching(targets, calls, kept(), existsSync(resolve(ROOT, VAULT_AT)), carries()) },
+        { at: ACTOR_AT, text: caller(existsSync(resolve(ROOT, ENTITIES_AT)), keeps) },
+        ...(emitted() ? [{ at: DISPATCHING_AT, text: dispatching(found) }] : []),
+        ...found.filter(served).map((one) => ({ at: routeAt(one.operation), text: route(one) })),
+        ...webhooks
+            .filter((one) => found.some((each) => each.operation === one.invokes && each.live.includes('webhook') && each.webhooks.includes(one.id) && compiled(one.invokes)))
+            .flatMap((one) => {
+            const at = (one.derives ?? []).map((each) => each.at).find((each) => each === inboundAt(one.id));
+            return at === undefined ? [] : [{ at, text: inbound(one) }];
+        }),
+        ...(hasUi ? [] : [{ at: SERVER_AT, text: entry(routes) }]),
+    ];
+};
 function unmoved() {
     const tree = defaulted();
     if (tree === undefined || tree.stated)
@@ -789,7 +988,7 @@ if (invoked(import.meta.url)) {
     const words = argv.slice(2).filter((one) => !one.startsWith('-'));
     if (words[0] !== undefined && words[0] !== 'read') {
         console.error('capabilities: `' + words[0] + '` is not something this command does. `thread capabilities` writes what can be reached, and ' +
-            '`thread capabilities read <mark>` prints one. Nothing was written.');
+            '`thread capabilities read <operation>` prints one. Nothing was written.');
         exit(1);
     }
     if (!argv.includes('--check')) {
@@ -808,13 +1007,12 @@ if (invoked(import.meta.url)) {
     const { found, refusals, live } = await derive();
     for (const one of refusals)
         console.error(`capabilities: ${one}`);
-    const mark = (one) => marked([one.operation, one.describes, one.requires.join(','), one.nodes.join(','), one.live.join(',')]);
     const verb = words[0];
     if (verb === 'read') {
         const which = words[1];
-        const one = found.find((each) => mark(each) === which);
+        const one = found.find((each) => each.operation === which);
         if (one === undefined) {
-            console.error(`capabilities: \`${which ?? '(nothing)'}\` is not a mark this tree issued. Run \`thread capabilities\` to see them — each is printed in brackets beside the capability it belongs to.`);
+            console.error(`capabilities: \`${which ?? '(nothing)'}\` is not an operation this app declares. Name one of ${found.map((each) => each.operation).join(', ') || '(none yet)'}.`);
             exit(1);
         }
         stdout.write(`${one.operation} — ${one.describes}\n`);
@@ -840,6 +1038,7 @@ if (invoked(import.meta.url)) {
     const people = sheet('entities.ts', 'ENTITIES');
     const one = people.find((each) => each.actor !== undefined);
     const where = one === undefined ? undefined : targetOf(one.id, all);
+    const { hasUi } = servedByNode();
     const written = files(found, all, sheet('targets.ts', 'CALLS'), where === undefined || typeof where === 'string' ? undefined : where.id, sheet('targets.ts', 'WEBHOOKS'));
     if (checking) {
         const drifted = written.filter((one) => {
@@ -853,6 +1052,8 @@ if (invoked(import.meta.url)) {
             ...(unmoved() === undefined ? [] : [`${CAPABILITIES_AT} switches surfaces that no row states yet`]),
             ...routed(found, false),
             ...unserved(found).map((at) => `${at} is still on disk to be served, and its operation does not answer on api`),
+            ...entered(hasUi, false),
+            ...unentered(hasUi).map((at) => `${at} is still on disk, and this app declares ui now`),
         ];
         for (const one of unsettled)
             console.error(`capabilities: ${one}. Run \`thread capabilities\` and commit the result.`);
@@ -873,6 +1074,15 @@ if (invoked(import.meta.url)) {
     }
     for (const one of routed(found, true))
         console.log(`capabilities: ${one}, so ${OPERATIONS_AT} was changed to match`);
+    for (const one of entered(hasUi, true))
+        console.log(`capabilities: ${one}, so ${OPERATIONS_AT} was changed to match`);
+    for (const at of unentered(hasUi)) {
+        rmSync(resolve(ROOT, at));
+        const folder = dirname(resolve(ROOT, at));
+        if (readdirSync(folder).length === 0)
+            rmSync(folder, { recursive: true, force: true });
+        console.log(`capabilities: deleted ${at}, because this app declares ui now and Next serves it instead`);
+    }
     for (const at of unserved(found)) {
         rmSync(resolve(ROOT, at));
         const folder = dirname(resolve(ROOT, at));

package/dist/operations/generators/compile.js

@@ -8,7 +8,7 @@ import { exit, invoked } from '../../core/invoked.js';
 import { inCode, valuesIn } from '../../core/rows.js';
 import { credentialsOf, holdsOf, reachOf } from '../../integrations/target.js';
 import { DISPATCH_AT, dispatched } from '../dispatch.js';
-import { beside, blockIn, builtFrom, operations, problem, quoted, runtime, types } from './seed.js';
+import { beside, blockIn, builtFrom, operations, problem, quoted, runtime, stepsOf, types } from './seed.js';
 async function reaching() {
     const held = async (file, list) => {
         const path = resolve(ROOT, `_threads/${file}`);
@@ -181,17 +181,21 @@ function spliced(text, shape, roles) {
             const up = node.parent;
             if (up !== undefined && ts.isPropertyAccessExpression(up) && up.expression === node) {
                 const said = up.name.text;
-                if (said !== 'input' && !names.has(said)) {
+                if (said !== 'input' && !names.has(said) && !shape.aliases.has(said)) {
                     because =
                         `reads \`${read.held}.${said}\`, and no node before it answers to that name. ` +
                             `\`${read.held}\` holds \`input\`, which is what this operation was called with, ` +
-                            (names.size === 0
+                            (names.size + shape.aliases.size === 0
                                 ? 'and nothing else — this is the first node, so `input` is all there is'
-                                : `and one name per node that has already answered: ${[...names].map((one) => `\`${one}\``).join(', ')}`);
+                                : `and one name per node that has already answered: ${[...names, ...shape.aliases.keys()].map((one) => `\`${one}\``).join(', ')}`);
                     return;
                 }
-                edits.push({ from: up.getStart(), to: up.getEnd(), text: said });
-                shape.heard.add(said);
+                const alias = shape.aliases.get(said);
+                edits.push({ from: up.getStart(), to: up.getEnd(), text: alias ?? said });
+                if (alias === undefined)
+                    shape.heard.add(said);
+                else
+                    shape.now.add(said);
                 return;
             }
             because = `reaches for \`${read.held}\` itself rather than one thing on it, and once every node is a local there is no such thing to hand it`;
@@ -257,13 +261,7 @@ function forked(name, said, shape) {
         return 'names its ways in a way this cannot read — write each one as `name: block`';
     const unread = shape.unread.has(name);
     const picked = `${OWN}${name}_said`;
-    const runs = [
-        ...(unread ? [] : [`let ${name}: unknown`]),
-        chose.form === 'expression'
-            ? `const ${picked}: string = await (${chose.text})`
-            : `const ${picked}: string = await ((${said[0] ?? ''}) as (opened: ${shape.reads}) => Promise<string>)(opened)`,
-        `switch (${picked}) {`,
-    ];
+    const runs = [...(unread ? [] : [`let ${name}: unknown`]), choosing(chose, shape, picked), `switch (${picked}) {`];
     for (const way of named) {
         const each = spliced(way?.held ?? '', shape, ROLES.block);
         if (typeof each === 'string')
@@ -398,44 +396,25 @@ function compiled(at, id, one, known, unread) {
         };
     }
     const only = one.requires.length === 0 ? 'never' : one.requires.map((each) => quoted(each)).join(' | ');
-    const mine = new Set(['input', ...one.nodes.map((row) => String(row.id))]);
-    const runs = [];
-    const names = new Set();
+    const mine = new Set(['input', ...stepsOf(one).map((row) => String(row.id))]);
     const heard = new Set();
-    let last;
-    for (const [order, row] of one.nodes.entries()) {
-        const name = row.id;
-        const from = builtFrom(row, known);
-        if (from === 'nd_stop' && order !== one.nodes.length - 1) {
-            const after = one.nodes.slice(order + 1).map((each) => `\`${String(each.id)}\``);
-            return {
-                because: `the node \`${String(name)}\` ends \`${id}\`, and ${after.join(', ')} ${after.length === 1 ? 'is' : 'are'} declared after it. ` +
-                    'Nothing runs after the node that ends an operation — move it last, or take off what follows it',
-            };
-        }
-        if (name === undefined)
-            return { because: `\`${id}\` declares a node with no id of its own` };
-        if (row.at === undefined)
-            return { because: `the node \`${name}\` names no file of its own` };
-        if (from === undefined)
-            return { because: `the node \`${name}\` names no type this app declares` };
-        const path = resolve(ROOT, row.at);
-        if (!existsSync(path))
-            return { because: `the node \`${name}\` seeds ${row.at} and nothing is there — run \`thread seed\`` };
-        const held = blockIn(readFileSync(path, 'utf8'));
-        if (held === undefined) {
-            return { because: `the node \`${name}\` states no block this can read in ${row.at} — run \`thread seed\` and write it again` };
-        }
-        const shape = { all: `Opened<${only}>`, reads: `Reads<Opened<${only}>>`, names, mine, heard, unread: unread ?? new Set() };
-        const made = (SHAPES[from] ?? ownType)(name, parts(held), shape);
-        if (typeof made === 'string')
-            return { because: `the node \`${name}\` ${made}` };
-        runs.push(`      ${ENTERED} = ${quoted(name)}`);
-        for (const line of made.runs)
-            runs.push(`      ${line}`);
-        names.add(name);
-        last = from === 'nd_stop' ? undefined : name;
-    }
+    const made = sequence(one.nodes, {
+        of: id,
+        all: `Opened<${only}>`,
+        reads: `Reads<Opened<${only}>>`,
+        names: new Set(),
+        mine,
+        heard,
+        unread: unread ?? new Set(),
+        aliases: new Map(),
+        now: new Set(),
+        within: one.within,
+        known,
+    });
+    if (typeof made === 'string')
+        return { because: made };
+    const runs = made.runs.map((line) => `      ${line}`);
+    const { last } = made;
     if (unread === undefined) {
         const final = one.nodes.at(-1)?.id;
         return compiled(at, id, one, known, new Set([...mine].filter((name) => name !== final && !heard.has(name))));
@@ -477,6 +456,127 @@ function compiled(at, id, one, known, unread) {
     };
 }
 const ownType = (name, said, shape) => plainly(name, said, shape, shape.all, false);
+const choosing = (one, shape, picked) => one.form === 'expression'
+    ? `const ${picked}: string = await (${one.text})`
+    : `const ${picked}: string = await ((${one.whole}) as (opened: ${shape.reads}) => Promise<string>)(opened)`;
+function sequence(steps, shape) {
+    const runs = [];
+    let last;
+    for (const [order, row] of steps.entries()) {
+        const name = row.id;
+        const from = builtFrom(row, shape.known);
+        if (from === 'nd_stop' && order !== steps.length - 1) {
+            const after = steps.slice(order + 1).map((each) => `\`${String(each.id)}\``);
+            return (`the node \`${String(name)}\` ends \`${shape.of}\`, and ${after.join(', ')} ${after.length === 1 ? 'is' : 'are'} declared after it. ` +
+                'Nothing runs after the node that ends an operation — move it last, or take off what follows it');
+        }
+        if (name === undefined)
+            return `\`${shape.of}\` declares a node with no id of its own`;
+        if (row.at === undefined)
+            return `the node \`${name}\` names no file of its own`;
+        if (from === undefined)
+            return `the node \`${name}\` names no type this app declares`;
+        const path = resolve(ROOT, row.at);
+        if (!existsSync(path))
+            return `the node \`${name}\` seeds ${row.at} and nothing is there — run \`thread seed\``;
+        const held = blockIn(readFileSync(path, 'utf8'));
+        if (held === undefined)
+            return `the node \`${name}\` states no block this can read in ${row.at} — run \`thread seed\` and write it again`;
+        const kids = shape.within.get(name) ?? [];
+        const holds = HELD[from];
+        let made;
+        if (kids.length === 0) {
+            const own = (SHAPES[from] ?? ownType)(name, parts(held), shape);
+            made = typeof own === 'string' ? `the node \`${name}\` ${own}` : own;
+        }
+        else if (holds === undefined) {
+            return (`the node \`${name}\` holds ${kids.map((each) => `\`${String(each.id)}\``).join(', ')}, and it is built from \`${from}\`. ` +
+                'Only a loop built from `nd_repeat` or a branch built from `nd_branch` holds other nodes. Take each one out with ' +
+                `${kids.map((each) => `\`thread remove ${String(each.id)}\``).join(', ')}, then add it where it belongs with \`thread create operation edit\``);
+        }
+        else
+            made = holds(name, parts(held), kids, shape);
+        if (typeof made === 'string')
+            return made;
+        runs.push(`${ENTERED} = ${quoted(name)}`, ...made.runs);
+        shape.names.add(name);
+        last = from === 'nd_stop' ? undefined : name;
+    }
+    return { runs, last };
+}
+function looped(name, said, kids, shape) {
+    if (said.length !== 1) {
+        return (`the node \`${name}\` holds other nodes, so its file states how many passes it may make and nothing else, and it states ${String(said.length)} thing(s). ` +
+            'The nodes it holds are what each pass runs');
+    }
+    const tail = kids.at(-1);
+    if (tail !== undefined && builtFrom(tail, shape.known) === 'nd_stop') {
+        return (`the node \`${name}\` ends each pass with \`${String(tail.id)}\`, which ends the whole operation, so no pass could say whether the loop is done. ` +
+            'Hold last a node that answers `{ done, value }`');
+    }
+    const now = `${OWN}${name}_now`;
+    const body = sequence(kids, { ...shape, names: new Set(shape.names), aliases: new Map([...shape.aliases, [name, now]]) });
+    if (typeof body === 'string')
+        return body;
+    const { last } = body;
+    if (last === undefined)
+        return `the node \`${name}\` holds no node that answers, so no pass could say whether it is done`;
+    shape.heard.add(last);
+    const ceiling = `${OWN}${name}_ceiling`;
+    const carried = `${OWN}${name}_carried`;
+    const done = `${OWN}${name}_done`;
+    const pass = `${OWN}${name}_pass`;
+    const answer = `${OWN}${name}_said`;
+    const unread = shape.unread.has(name);
+    const reads = shape.now.has(name);
+    return {
+        runs: [
+            ...(unread ? [] : [`let ${name}: unknown`]),
+            `const ${ceiling}: number = ${said[0] ?? ''}`,
+            ...(reads ? [`let ${carried}: unknown`] : []),
+            `let ${done} = false`,
+            `for (let ${pass} = 0; ${pass} < ${ceiling}; ${pass} += 1) {`,
+            ...(reads ? [`  const ${now} = { pass: ${pass}, carried: ${carried} }`] : []),
+            ...body.runs.map((line) => `  ${line}`),
+            `  const ${answer} = ${last} as { readonly done: boolean; readonly value: unknown }`,
+            `  if (${answer}.done) { ${unread ? '' : `${name} = ${answer}.value; `}${done} = true; break }`,
+            ...(reads ? [`  ${carried} = ${answer}.value`] : []),
+            '}',
+            `${ENTERED} = ${quoted(name)}`,
+            `if (!${done}) throw new Error(\`${name} reached its ceiling of \${String(${ceiling})} passes without answering done\`)`,
+        ],
+    };
+}
+function chosen(name, said, kids, shape) {
+    if (said.length !== 1) {
+        return (`the node \`${name}\` holds other nodes, so its file states the block that chooses between them and nothing else, and it states ${String(said.length)} thing(s). ` +
+            'Each node it holds is one way it can go');
+    }
+    const chose = spliced(said[0] ?? '', shape, ROLES.block);
+    if (typeof chose === 'string')
+        return `the node \`${name}\` chooses with a block that ${chose}`;
+    const unread = shape.unread.has(name);
+    const picked = `${OWN}${name}_said`;
+    const runs = [...(unread ? [] : [`let ${name}: unknown`]), choosing(chose, shape, picked), `switch (${picked}) {`];
+    for (const kid of kids) {
+        const way = String(kid.id);
+        const body = sequence([kid], { ...shape, names: new Set(shape.names) });
+        if (typeof body === 'string')
+            return body;
+        runs.push(`  case ${quoted(way)}: {`, ...body.runs.map((line) => `    ${line}`));
+        if (body.last !== undefined) {
+            shape.heard.add(way);
+            runs.push(unread ? `    void ${way}` : `    ${name} = ${way}`, '    break');
+        }
+        runs.push('  }');
+    }
+    runs.push(`  default: throw new Error(\`${name} chose \${${picked}}, which names no node it holds\`)`, '}');
+    return { runs };
+}
+const HELD = {
+    nd_repeat: looped,
+    nd_branch: chosen,
+};
 async function planned() {
     const pass = descend();
     const known = types(pass);

package/dist/operations/generators/seed.d.ts

@@ -9,10 +9,13 @@ interface Woven {
     readonly nodes: readonly Row[];
     readonly takes: readonly Row[];
     readonly body?: string;
+    readonly within: ReadonlyMap<string, readonly Row[]>;
     readonly requires: readonly string[];
     readonly stray: readonly string[];
     readonly timeout?: number;
 }
+export declare const HOLDING: Readonly<Record<string, (first: string) => string>>;
+export declare const stepsOf: (one: Woven) => readonly Row[];
 export declare function operations(pass: Pass, known: ReadonlySet<string>): ReadonlyMap<string, Woven>;
 export declare const problem: (id: string, one: Woven) => string | undefined;
 export declare function blockIn(text: string): string | undefined;

package/dist/operations/generators/seed.js

@@ -50,6 +50,11 @@ export function builtFrom(row, known) {
     const found = (row.requires ?? []).filter((one) => known.has(one));
     return found.length === 1 ? found[0] : undefined;
 }
+export const HOLDING = {
+    nd_repeat: () => '1',
+    nd_branch: (first) => `async () => ${quoted(first)}`,
+};
+export const stepsOf = (one) => [...one.nodes, ...[...one.within.values()].flat()];
 const reaches = (pass, one) => pass.stated.has(one) && !under(pass, one, NODES_ID);
 const waiting = (held) => held !== undefined && ts.isNumericLiteral(held) ? Number(held.text.replace(/_/g, '')) : undefined;
 export function operations(pass, known) {
@@ -64,6 +69,7 @@ export function operations(pass, known) {
             nodes: [],
             takes: [],
             body: undefined,
+            within: new Map(),
             wants: new Set(stated?.takes ?? []),
             requires: asked.filter((one) => reaches(pass, one)),
             stray: asked.filter((one) => !reaches(pass, one)),
@@ -72,8 +78,17 @@ export function operations(pass, known) {
         found.set(id, made);
         return made;
     };
+    const steps = new Map();
     for (const [at, threadings] of pass.threaded) {
         for (const one of threadings) {
+            const holder = steps.get(one.by);
+            if (holder !== undefined && one.list === 'seeds') {
+                const within = held(holder).within;
+                within.set(one.by, [...(within.get(one.by) ?? []), one.row]);
+                if (one.row.id !== undefined)
+                    steps.set(one.row.id, holder);
+                continue;
+            }
             if (!isOperation(pass, one.by))
                 continue;
             if (one.list === 'derives' && one.row.by === COMPILES)
@@ -82,8 +97,11 @@ export function operations(pass, known) {
                 const mine = held(one.by);
                 if (mine.wants.has(one.row.id ?? ''))
                     mine.takes.push(one.row);
-                else
+                else {
                     mine.nodes.push(one.row);
+                    if (one.row.id !== undefined)
+                        steps.set(one.row.id, one.by);
+                }
             }
         }
     }
@@ -166,14 +184,18 @@ function planned(bodies) {
         for (const row of one.takes)
             if (row.at !== undefined)
                 found.push({ at: row.at, derived: false, text: takesFile(row.at) });
-        for (const row of one.nodes) {
+        for (const row of stepsOf(one)) {
             const from = builtFrom(row, known);
             const takes = one.takes[0]?.at;
             if (row.at === undefined || from === undefined || takes === undefined)
                 continue;
             const path = resolve(ROOT, row.at);
             const held = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
-            const block = bodies.get(row.at) ?? (held === undefined ? undefined : blockIn(held));
+            const first = one.within.get(String(row.id))?.[0]?.id;
+            const fresh = first === undefined ? undefined : HOLDING[from]?.(first);
+            const written = held === undefined ? undefined : blockIn(held);
+            const untouched = held === undefined || written === scaffold(from, String(row.id));
+            const block = bodies.get(row.at) ?? (fresh !== undefined && untouched ? fresh : written);
             if (held !== undefined && block === undefined) {
                 found.push({
                     at: row.at,