@prestack/thread 0.1.3 → 0.1.4

package/dist/core/errors/catalogue.d.ts

@@ -0,0 +1,52 @@
+export declare const AuthUnauthenticated: import("./error.ts").ErrorFactory<"auth.unauthenticated">;
+export declare const AuthInvalidCredentials: import("./error.ts").ErrorFactory<"auth.invalid_credentials">;
+export declare const AuthTokenExpired: import("./error.ts").ErrorFactory<"auth.token_expired">;
+export declare const AuthTokenReused: import("./error.ts").ErrorFactory<"auth.token_reused">;
+export declare const AuthSessionRevoked: import("./error.ts").ErrorFactory<"auth.session_revoked">;
+export declare const AuthDenied: import("./error.ts").ErrorFactory<"auth.denied">;
+export declare const QuotaExceeded: import("./error.ts").ErrorFactory<"quota.exceeded">;
+export declare const QuotaReservationExpired: import("./error.ts").ErrorFactory<"quota.reservation_expired">;
+export declare const RateLimitExceeded: import("./error.ts").ErrorFactory<"rate_limit.exceeded">;
+export declare const FeatureNotInPlan: import("./error.ts").ErrorFactory<"feature.not_in_plan">;
+export declare const DbNotFound: import("./error.ts").ErrorFactory<"db.not_found">;
+export declare const DbConstraintViolation: import("./error.ts").ErrorFactory<"db.constraint_violation">;
+export declare const DbAlreadyExists: import("./error.ts").ErrorFactory<"db.already_exists">;
+export declare const DbConflict: import("./error.ts").ErrorFactory<"db.conflict">;
+export declare const DbMigrationChecksumMismatch: import("./error.ts").ErrorFactory<"db.migration_checksum_mismatch">;
+export declare const DbDestructiveWithoutDryRun: import("./error.ts").ErrorFactory<"db.destructive_without_dry_run">;
+export declare const DbRoundTripBudgetExceeded: import("./error.ts").ErrorFactory<"db.round_trip_budget_exceeded">;
+export declare const DbCursorInvalid: import("./error.ts").ErrorFactory<"db.cursor_invalid">;
+export declare const DbCursorExpired: import("./error.ts").ErrorFactory<"db.cursor_expired">;
+export declare const WorkflowNodeFailed: import("./error.ts").ErrorFactory<"workflow.node_failed">;
+export declare const WorkflowInvalidTransition: import("./error.ts").ErrorFactory<"workflow.invalid_transition">;
+export declare const WorkflowCompensationFailed: import("./error.ts").ErrorFactory<"workflow.compensation_failed">;
+export declare const WorkflowAlreadyRunning: import("./error.ts").ErrorFactory<"workflow.already_running">;
+export declare const QueueJobFailed: import("./error.ts").ErrorFactory<"queue.job_failed">;
+export declare const QueueDlqExhausted: import("./error.ts").ErrorFactory<"queue.dlq_exhausted">;
+export declare const AiProviderUnavailable: import("./error.ts").ErrorFactory<"ai.provider_unavailable">;
+export declare const AiSchemaValidationFailed: import("./error.ts").ErrorFactory<"ai.schema_validation_failed">;
+export declare const AiToolNotInMask: import("./error.ts").ErrorFactory<"ai.tool_not_in_mask">;
+export declare const AiNodeCapExceeded: import("./error.ts").ErrorFactory<"ai.node_cap_exceeded">;
+export declare const SearchIndexFailed: import("./error.ts").ErrorFactory<"search.index_failed">;
+export declare const SearchQueryInvalid: import("./error.ts").ErrorFactory<"search.query_invalid">;
+export declare const CommsChannelKindUndeclared: import("./error.ts").ErrorFactory<"comms.channel_kind_undeclared">;
+export declare const CommsChannelKindUndescribed: import("./error.ts").ErrorFactory<"comms.channel_kind_undescribed">;
+export declare const CommsChannelKindUnlabelled: import("./error.ts").ErrorFactory<"comms.channel_kind_unlabelled">;
+export declare const CommsChannelKindUndocumented: import("./error.ts").ErrorFactory<"comms.channel_kind_undocumented">;
+export declare const CommsChannelKindDuplicate: import("./error.ts").ErrorFactory<"comms.channel_kind_duplicate">;
+export declare const ConfigInvalid: import("./error.ts").ErrorFactory<"config.invalid">;
+export declare const ConfigMissingEnv: import("./error.ts").ErrorFactory<"config.missing_env">;
+export declare const ConfigSecretInPublicVar: import("./error.ts").ErrorFactory<"config.secret_in_public_var">;
+export declare const ConfigCredentialInvalid: import("./error.ts").ErrorFactory<"config.credential_invalid">;
+export declare const ConfigScopeMissing: import("./error.ts").ErrorFactory<"config.scope_missing">;
+export declare const ConfigResourceNotFound: import("./error.ts").ErrorFactory<"config.resource_not_found">;
+export declare const ConfigDestinationIncompatible: import("./error.ts").ErrorFactory<"config.destination_incompatible">;
+export declare const ConfigBlocksExit: import("./error.ts").ErrorFactory<"config.blocks_exit">;
+export declare const NetTimeout: import("./error.ts").ErrorFactory<"net.timeout">;
+export declare const NetUpstreamUnavailable: import("./error.ts").ErrorFactory<"net.upstream_unavailable">;
+export declare const NetDestinationRefused: import("./error.ts").ErrorFactory<"net.destination_refused">;
+export declare const InternalUnexpected: import("./error.ts").ErrorFactory<"internal.unexpected">;
+export declare const InternalNotImplemented: import("./error.ts").ErrorFactory<"internal.not_implemented">;
+export declare const InternalInvalidArgument: import("./error.ts").ErrorFactory<"internal.invalid_argument">;
+export declare const PLATFORM_ERRORS: readonly [import("./error.ts").ErrorFactory<"auth.unauthenticated">, import("./error.ts").ErrorFactory<"auth.invalid_credentials">, import("./error.ts").ErrorFactory<"auth.token_expired">, import("./error.ts").ErrorFactory<"auth.token_reused">, import("./error.ts").ErrorFactory<"auth.session_revoked">, import("./error.ts").ErrorFactory<"auth.denied">, import("./error.ts").ErrorFactory<"quota.exceeded">, import("./error.ts").ErrorFactory<"quota.reservation_expired">, import("./error.ts").ErrorFactory<"rate_limit.exceeded">, import("./error.ts").ErrorFactory<"feature.not_in_plan">, import("./error.ts").ErrorFactory<"db.not_found">, import("./error.ts").ErrorFactory<"db.constraint_violation">, import("./error.ts").ErrorFactory<"db.already_exists">, import("./error.ts").ErrorFactory<"db.conflict">, import("./error.ts").ErrorFactory<"db.migration_checksum_mismatch">, import("./error.ts").ErrorFactory<"db.destructive_without_dry_run">, import("./error.ts").ErrorFactory<"db.round_trip_budget_exceeded">, import("./error.ts").ErrorFactory<"db.cursor_invalid">, import("./error.ts").ErrorFactory<"db.cursor_expired">, import("./error.ts").ErrorFactory<"workflow.node_failed">, import("./error.ts").ErrorFactory<"workflow.invalid_transition">, import("./error.ts").ErrorFactory<"workflow.compensation_failed">, import("./error.ts").ErrorFactory<"workflow.already_running">, import("./error.ts").ErrorFactory<"queue.job_failed">, import("./error.ts").ErrorFactory<"queue.dlq_exhausted">, import("./error.ts").ErrorFactory<"ai.provider_unavailable">, import("./error.ts").ErrorFactory<"ai.schema_validation_failed">, import("./error.ts").ErrorFactory<"ai.tool_not_in_mask">, import("./error.ts").ErrorFactory<"ai.node_cap_exceeded">, import("./error.ts").ErrorFactory<"search.index_failed">, import("./error.ts").ErrorFactory<"search.query_invalid">, import("./error.ts").ErrorFactory<"comms.channel_kind_undeclared">, import("./error.ts").ErrorFactory<"comms.channel_kind_undescribed">, import("./error.ts").ErrorFactory<"comms.channel_kind_unlabelled">, import("./error.ts").ErrorFactory<"comms.channel_kind_undocumented">, import("./error.ts").ErrorFactory<"comms.channel_kind_duplicate">, import("./error.ts").ErrorFactory<"config.invalid">, import("./error.ts").ErrorFactory<"config.missing_env">, import("./error.ts").ErrorFactory<"config.secret_in_public_var">, import("./error.ts").ErrorFactory<"config.credential_invalid">, import("./error.ts").ErrorFactory<"config.scope_missing">, import("./error.ts").ErrorFactory<"config.resource_not_found">, import("./error.ts").ErrorFactory<"config.destination_incompatible">, import("./error.ts").ErrorFactory<"config.blocks_exit">, import("./error.ts").ErrorFactory<"net.timeout">, import("./error.ts").ErrorFactory<"net.upstream_unavailable">, import("./error.ts").ErrorFactory<"net.destination_refused">, import("./error.ts").ErrorFactory<"internal.unexpected">, import("./error.ts").ErrorFactory<"internal.not_implemented">, import("./error.ts").ErrorFactory<"internal.invalid_argument">];
+export type PlatformErrorCode = (typeof PLATFORM_ERRORS)[number]['def']['code'];

package/dist/{operations/errors/errors.js → core/errors/catalogue.js}

@@ -1,4 +1,4 @@
-import { defineError } from "./catalog.js";
+import { defineError } from './error.js';
 export const AuthUnauthenticated = defineError({
     code: 'auth.unauthenticated',
     class: 'UNAUTHENTICATED',

package/dist/{operations/errors/errors.ts → core/errors/catalogue.ts}

@@ -1,6 +1,6 @@
 
 
-import { defineError } from './catalog.ts'
+import { defineError } from './error.ts'
 
 export const AuthUnauthenticated = defineError({
   code: 'auth.unauthenticated',

package/dist/{operations/errors/catalog.d.ts → core/errors/error.d.ts}

@@ -1,7 +1,6 @@
 import { type ErrorClass } from './classes.ts';
-export declare const NAMESPACES: readonly ["auth", "quota", "rate_limit", "feature", "db", "workflow", "queue", "ai", "search", "comms", "config", "net", "internal"];
-export type Namespace = (typeof NAMESPACES)[number];
-export type ErrorCode = `${Namespace}.${string}`;
+import type { ErrorCode } from './namespaces.ts';
+export type { ErrorCode } from './namespaces.ts';
 export interface ErrorDef<C extends ErrorCode = ErrorCode> {
     readonly code: C;
     readonly class: ErrorClass;

package/dist/{operations/errors/catalog.js → core/errors/error.js}

@@ -1,19 +1,4 @@
-import { classDef } from "./classes.js";
-export const NAMESPACES = [
-    'auth',
-    'quota',
-    'rate_limit',
-    'feature',
-    'db',
-    'workflow',
-    'queue',
-    'ai',
-    'search',
-    'comms',
-    'config',
-    'net',
-    'internal',
-];
+import { classDef } from './classes.js';
 export class PlatformError extends Error {
     def;
     detail;

package/dist/{operations/errors/catalog.ts → core/errors/error.ts}

@@ -2,25 +2,9 @@
 
 import { classDef, type ErrorClass } from './classes.ts'
 
-export const NAMESPACES = [
-  'auth',
-  'quota',
-  'rate_limit',
-  'feature',
-  'db',
-  'workflow',
-  'queue',
-  'ai',
-  'search',
-  'comms',
-  'config',
-  'net',
-  'internal',
-] as const
-
-export type Namespace = (typeof NAMESPACES)[number]
-
-export type ErrorCode = `${Namespace}.${string}`
+import type { ErrorCode } from './namespaces.ts'
+
+export type { ErrorCode } from './namespaces.ts'
 
 export interface ErrorDef<C extends ErrorCode = ErrorCode> {
   readonly code: C

package/dist/core/errors/namespaces.d.ts

@@ -0,0 +1,3 @@
+export declare const NAMESPACES: readonly ['auth', 'quota', 'rate_limit', 'feature', 'db', 'workflow', 'queue', 'ai', 'search', 'comms', 'config', 'net', 'internal'];
+export type Namespace = (typeof NAMESPACES)[number];
+export type ErrorCode = `${Namespace}.${string}`;

package/dist/core/errors/namespaces.js

@@ -0,0 +1,15 @@
+export const NAMESPACES = [
+    'auth',
+    'quota',
+    'rate_limit',
+    'feature',
+    'db',
+    'workflow',
+    'queue',
+    'ai',
+    'search',
+    'comms',
+    'config',
+    'net',
+    'internal',
+];

package/dist/core/errors/namespaces.ts

@@ -0,0 +1,19 @@
+export const NAMESPACES = [
+  'auth',
+  'quota',
+  'rate_limit',
+  'feature',
+  'db',
+  'workflow',
+  'queue',
+  'ai',
+  'search',
+  'comms',
+  'config',
+  'net',
+  'internal',
+] as const
+
+export type Namespace = (typeof NAMESPACES)[number]
+
+export type ErrorCode = `${Namespace}.${string}`

package/dist/core/finding.js

@@ -11,7 +11,6 @@ function locate(finding) {
 export function runChecker(name, findings, measured) {
     if (findings.length === 0) {
         stdout.write(`${name}: ${measured} — no findings.\n`);
-        process.exitCode = 0;
         return;
     }
     const lines = findings.map((finding) => `  ${forbids(finding) ? '' : 'warning: '}${finding.detail}${locate(finding)}\n    Instead: ${finding.instead}`);
@@ -19,5 +18,6 @@ export function runChecker(name, findings, measured) {
     stdout.write(`${name}: ${String(findings.length)} finding${findings.length === 1 ? '' : 's'}` +
         `${forbidding === findings.length ? '' : `, ${String(findings.length - forbidding)} of them warnings`} — ${measured}\n\n` +
         `${lines.join('\n')}\n`);
-    process.exitCode = forbidding === 0 ? 0 : 1;
+    if (forbidding > 0)
+        process.exitCode = 1;
 }

package/dist/core/finding.ts

@@ -21,7 +21,6 @@ function locate(finding: Finding): string {
 export function runChecker(name: string, findings: readonly Finding[], measured: string): void {
   if (findings.length === 0) {
     stdout.write(`${name}: ${measured} — no findings.\n`)
-    process.exitCode = 0
     return
   }
 
@@ -34,5 +33,5 @@ export function runChecker(name: string, findings: readonly Finding[], measured:
       `${forbidding === findings.length ? '' : `, ${String(findings.length - forbidding)} of them warnings`} — ${measured}\n\n` +
       `${lines.join('\n')}\n`,
   )
-  process.exitCode = forbidding === 0 ? 0 : 1
+  if (forbidding > 0) process.exitCode = 1
 }

package/dist/core/init.d.ts

@@ -5,7 +5,6 @@ export declare class AlreadyThreadedError extends Error {
     constructor(at: string);
 }
 export declare const COMPILER = "tsconfig.json";
-export declare const LOCKFILES: readonly ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb"];
 export declare const MANIFEST = "package.json";
 export declare const REGISTRY: string;
 export declare const IGNORED: string;

package/dist/core/init.js

@@ -1,6 +1,9 @@
-import { existsSync, readFileSync, writeFileSync } from "./files.js";
+import { LOCKFILES, installing, manager } from '../integrations/cli.js';
+import { existsSync, readFileSync, writeFileSync } from '../integrations/disk.js';
+import { createRequire } from 'node:module';
 import { join, relative, resolve } from 'node:path';
-import { quoted } from "./rows.js";
+import { fileURLToPath } from 'node:url';
+import { quoted } from './rows.js';
 export const TREE = '_threads';
 export const ROOT = 'thread.ts';
 export class AlreadyThreadedError extends Error {
@@ -14,9 +17,11 @@ export class AlreadyThreadedError extends Error {
     }
 }
 export const COMPILER = 'tsconfig.json';
-export const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb'];
 export const MANIFEST = 'package.json';
+const BUILT = '_gener' + 'ated/packages/core';
 const MODULE = 'module';
+const NPM = 'npm';
+const LATEST = 'latest';
 export const REGISTRY = '.npm' + 'rc';
 export const IGNORED = '.git' + 'ignore';
 export function ignored() {
@@ -46,7 +51,7 @@ export function compiler() {
     }, null, 2)}\n`;
 }
 function owned(into) {
-    const held = LOCKFILES.filter((one) => existsSync(join(into, one)));
+    const held = Object.keys(LOCKFILES).filter((one) => existsSync(join(into, one)));
     return [
         {
             id: 'manifest',
@@ -99,6 +104,35 @@ export function root(into) {
         '',
     ].join('\n');
 }
+const own = createRequire(import.meta.url);
+function manifested(at) {
+    try {
+        return own(at);
+    }
+    catch {
+        return undefined;
+    }
+}
+function shipped() {
+    let at = fileURLToPath(new URL('.', import.meta.url));
+    for (;;) {
+        const read = manifested(join(at, MANIFEST));
+        if (read !== undefined) {
+            if (read.name !== undefined && read.version !== undefined)
+                return [read.name, read.version];
+            const core = manifested(join(at, BUILT, MANIFEST));
+            if (core?.name !== undefined && core.version !== undefined)
+                return [core.name, core.version];
+        }
+        const up = resolve(at, '..');
+        if (up === at) {
+            throw new Error('this framework cannot find the package it is running from, so it has no name to install into your project. ' +
+                'That name is read off the manifest beside this code rather than written down anywhere, which is what keeps it ' +
+                'right when the package is renamed.');
+        }
+        at = up;
+    }
+}
 export function init(into) {
     const dir = resolve(into, TREE);
     const at = join(dir, ROOT);
@@ -121,11 +155,21 @@ export function init(into) {
         writeFileSync(manifest, `${JSON.stringify({ ...stated, type: MODULE }, null, 2)}\n`, 'utf8');
         written.push(MANIFEST);
     }
+    const [from, version] = shipped();
+    const holds = JSON.parse(readFileSync(manifest, 'utf8'));
+    const dev = holds.devDependencies ?? {};
+    const wanted = { [from]: '^' + version, ...(manager(into) === NPM ? { [NPM]: LATEST } : {}) };
+    const missing = Object.entries(wanted).filter(([name]) => dev[name] === undefined);
+    if (missing.length > 0) {
+        writeFileSync(manifest, JSON.stringify({ ...holds, devDependencies: { ...dev, ...Object.fromEntries(missing) } }, null, 2) + '\n', 'utf8');
+        written.push(MANIFEST);
+    }
     const ignore = join(into, IGNORED);
     if (!existsSync(ignore)) {
         writeFileSync(ignore, ignored(), 'utf8');
         written.push(IGNORED);
     }
+    installing(into);
     for (const [name, text] of [[ROOT, root(into)]]) {
         writeFileSync(join(dir, name), text, 'utf8');
         written.push(relative(into, join(dir, name)));

package/dist/core/init.ts

@@ -1,5 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from './files.ts'
+import { LOCKFILES, installing, manager } from '../integrations/cli.ts'
+import { existsSync, readFileSync, writeFileSync } from '../integrations/disk.ts'
+import { createRequire } from 'node:module'
 import { join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import { quoted } from './rows.ts'
 
@@ -23,12 +26,16 @@ export class AlreadyThreadedError extends Error {
 
 export const COMPILER = 'tsconfig.json'
 
-export const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lockb'] as const
-
 export const MANIFEST = 'package.json'
 
+const BUILT = '_gener' + 'ated/packages/core'
+
 const MODULE = 'module'
 
+const NPM = 'npm'
+
+const LATEST = 'latest'
+
 export const REGISTRY = '.npm' + 'rc'
 
 export const IGNORED = '.git' + 'ignore'
@@ -71,7 +78,7 @@ export function compiler(): string {
 }
 
 function owned(into: string): readonly { readonly id: string; readonly at: string; readonly describes: string; readonly runs?: string }[] {
-  const held = LOCKFILES.filter((one) => existsSync(join(into, one)))
+  const held = Object.keys(LOCKFILES).filter((one) => existsSync(join(into, one)))
   return [
     {
       id: 'manifest',
@@ -131,6 +138,37 @@ export function root(into: string): string {
   ].join('\n')
 }
 
+const own = createRequire(import.meta.url)
+
+function manifested(at: string): { readonly name?: string; readonly version?: string } | undefined {
+  try {
+    return own(at) as { readonly name?: string; readonly version?: string }
+  } catch {
+    return undefined
+  }
+}
+
+function shipped(): readonly [string, string] {
+  let at = fileURLToPath(new URL('.', import.meta.url))
+  for (;;) {
+    const read = manifested(join(at, MANIFEST))
+    if (read !== undefined) {
+      if (read.name !== undefined && read.version !== undefined) return [read.name, read.version]
+      const core = manifested(join(at, BUILT, MANIFEST))
+      if (core?.name !== undefined && core.version !== undefined) return [core.name, core.version]
+    }
+    const up = resolve(at, '..')
+    if (up === at) {
+      throw new Error(
+        'this framework cannot find the package it is running from, so it has no name to install into your project. ' +
+          'That name is read off the manifest beside this code rather than written down anywhere, which is what keeps it ' +
+          'right when the package is renamed.',
+      )
+    }
+    at = up
+  }
+}
+
 export function init(into: string): readonly string[] {
   const dir = resolve(into, TREE)
   const at = join(dir, ROOT)
@@ -155,12 +193,24 @@ export function init(into: string): readonly string[] {
     written.push(MANIFEST)
   }
 
+  const [from, version] = shipped()
+  const holds = JSON.parse(readFileSync(manifest, 'utf8')) as { devDependencies?: Record<string, string> }
+  const dev = holds.devDependencies ?? {}
+  const wanted: Readonly<Record<string, string>> = { [from]: '^' + version, ...(manager(into) === NPM ? { [NPM]: LATEST } : {}) }
+  const missing = Object.entries(wanted).filter(([name]) => dev[name] === undefined)
+  if (missing.length > 0) {
+    writeFileSync(manifest, JSON.stringify({ ...holds, devDependencies: { ...dev, ...Object.fromEntries(missing) } }, null, 2) + '\n', 'utf8')
+    written.push(MANIFEST)
+  }
+
   const ignore = join(into, IGNORED)
   if (!existsSync(ignore)) {
     writeFileSync(ignore, ignored(), 'utf8')
     written.push(IGNORED)
   }
 
+  installing(into)
+
   for (const [name, text] of [[ROOT, root(into)]] as const) {
     writeFileSync(join(dir, name), text, 'utf8')
     written.push(relative(into, join(dir, name)))

package/dist/core/invoked.d.ts

@@ -4,6 +4,6 @@ export declare const BESIDE: (name: string) => string;
 export declare const LOADER: readonly string[];
 export declare const CLI: readonly string[];
 export declare const REFUSED: unique symbol;
-export declare const shared: (on: boolean) => void;
+export declare const shared: (on: boolean) => boolean;
 export declare function exit(code?: number): never;
 export declare const refusal: (thrown: unknown) => number | undefined;

package/dist/core/invoked.js

@@ -1,7 +1,7 @@
-import { realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { argv, exit as ending } from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { realpathSync } from '../integrations/disk.js';
 export function invoked(url) {
     const named = argv[1];
     if (named === undefined)
@@ -26,7 +26,9 @@ export const CLI = [
 export const REFUSED = Symbol.for('thread.refused');
 let sharing = false;
 export const shared = (on) => {
+    const was = sharing;
     sharing = on;
+    return was;
 };
 export function exit(code) {
     if (!sharing)

package/dist/core/invoked.ts

@@ -1,8 +1,9 @@
-import { realpathSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { argv, exit as ending } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
+import { realpathSync } from '../integrations/disk.ts'
+
 export function invoked(url: string): boolean {
   const named = argv[1]
   if (named === undefined) return false
@@ -31,8 +32,10 @@ export const REFUSED = Symbol.for('thread.refused')
 
 let sharing = false
 
-export const shared = (on: boolean): void => {
+export const shared = (on: boolean): boolean => {
+  const was = sharing
   sharing = on
+  return was
 }
 
 export function exit(code?: number): never {

package/dist/core/round.js

@@ -7,17 +7,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { resolve } from 'node:path';
-import { argv, exitCode, stdout } from 'node:process';
+import { argv, exitCode, stderr, stdout } from 'node:process';
 import { pathToFileURL } from 'node:url';
-import { generators, RAN, REFUSED_BY } from "./chain.js";
-import { forget } from "./descend.js";
-import { refusal, shared } from "./invoked.js";
-import { findTree } from "./tree.js";
+import { generators, RAN, REFUSED_BY } from './chain.js';
+import { attached, here } from '../integrations/disk.js';
+import { forget } from './descend.js';
+import { refusal, shared } from './invoked.js';
+import { findTree } from './tree.js';
 let spun = 0;
 const words = (command) => command.trim().split(/\s+/).slice(1);
 shared(true);
 const tree = findTree();
 const rows = await generators(tree);
+let stale = true;
 for (const command of argv.slice(2).filter((one) => one !== '')) {
     const said = words(command);
     const name = said[0];
@@ -25,33 +27,45 @@ for (const command of argv.slice(2).filter((one) => one !== '')) {
         continue;
     const held = rows.find((one) => one.by === `thread ${name}`);
     if (held?.at === undefined) {
-        stdout.write(`${REFUSED_BY} ${command}\n`);
         stdout.write(`round: no command named "${name}", so \`${command}\` was not run\n`);
+        stdout.write(`${REFUSED_BY} ${command}\n`);
         continue;
     }
     const found = resolve(tree.at, held.at);
-    forget();
+    if (stale)
+        forget();
     argv.length = 1;
     argv.push(found, ...said.slice(1));
     spun += 1;
     process.exitCode = 0;
-    try {
-        await import(__rewriteRelativeImportExtension(`${pathToFileURL(found).href}?round=${String(spun)}`));
-        if (exitCode !== undefined && exitCode !== 0)
-            stdout.write(`${REFUSED_BY} ${command}\n`);
-        else
-            stdout.write(`${RAN} ${command}\n`);
+    const began = Date.now();
+    stderr.write(`settle: running ${command}\n`);
+    let ok = true;
+    const ran = attached() ? here().run(found, said.slice(1)) : undefined;
+    if (ran !== undefined) {
+        stdout.write(ran.out);
+        stderr.write(ran.err);
+        ok = ran.there && ran.ok;
+        if (!ran.there)
+            stdout.write('round: ' + command + ' could not be started where the tree is: ' + ran.why + '\n');
     }
-    catch (thrown) {
-        const code = refusal(thrown);
-        if (code === undefined) {
-            stdout.write(`${REFUSED_BY} ${command}\n`);
-            stdout.write(`round: \`${command}\` threw: ${thrown instanceof Error ? thrown.message : String(thrown)}\n`);
+    else {
+        try {
+            await import(__rewriteRelativeImportExtension(`${pathToFileURL(found).href}?round=${String(spun)}`));
+            ok = exitCode === undefined || exitCode === 0;
+        }
+        catch (thrown) {
+            const code = refusal(thrown);
+            if (code === undefined) {
+                ok = false;
+                stdout.write(`round: \`${command}\` threw: ${thrown instanceof Error ? thrown.message : String(thrown)}\n`);
+            }
+            else
+                ok = code === 0;
         }
-        else if (code === 0)
-            stdout.write(`${RAN} ${command}\n`);
-        else
-            stdout.write(`${REFUSED_BY} ${command}\n`);
     }
+    stdout.write(`${ok ? RAN : REFUSED_BY} ${command}\n`);
+    stderr.write(`settle: ${command} — ${String(Date.now() - began)} ms, ${ok ? 'ran' : 'refused'}\n`);
+    stale = !command.trim().endsWith('--check');
 }
 process.exitCode = 0;

package/dist/core/round.ts

@@ -1,8 +1,9 @@
 import { resolve } from 'node:path'
-import { argv, exitCode, stdout } from 'node:process'
+import { argv, exitCode, stderr, stdout } from 'node:process'
 import { pathToFileURL } from 'node:url'
 
 import { generators, RAN, REFUSED_BY } from './chain.ts'
+import { attached, here } from '../integrations/disk.ts'
 import { forget } from './descend.ts'
 import { refusal, shared } from './invoked.ts'
 import { findTree } from './tree.ts'
@@ -16,6 +17,8 @@ shared(true)
 const tree = findTree()
 const rows = await generators(tree)
 
+let stale = true
+
 for (const command of argv.slice(2).filter((one) => one !== '')) {
   const said = words(command)
   const name = said[0]
@@ -23,14 +26,14 @@ for (const command of argv.slice(2).filter((one) => one !== '')) {
 
   const held = rows.find((one) => one.by === `thread ${name}`)
   if (held?.at === undefined) {
-    stdout.write(`${REFUSED_BY} ${command}\n`)
     stdout.write(`round: no command named "${name}", so \`${command}\` was not run\n`)
+    stdout.write(`${REFUSED_BY} ${command}\n`)
     continue
   }
 
   const found = resolve(tree.at, held.at)
 
-  forget()
+  if (stale) forget()
 
   argv.length = 1
   argv.push(found, ...said.slice(1))
@@ -39,19 +42,33 @@ for (const command of argv.slice(2).filter((one) => one !== '')) {
 
   process.exitCode = 0
 
+  const began = Date.now()
+  stderr.write(`settle: running ${command}\n`)
+
+  let ok = true
+  const ran = attached() ? here().run(found, said.slice(1)) : undefined
+  if (ran !== undefined) {
+    stdout.write(ran.out)
+    stderr.write(ran.err)
+    ok = ran.there && ran.ok
+    if (!ran.there) stdout.write('round: ' + command + ' could not be started where the tree is: ' + ran.why + '\n')
+  } else {
   try {
     await import(`${pathToFileURL(found).href}?round=${String(spun)}`)
-    if (exitCode !== undefined && exitCode !== 0) stdout.write(`${REFUSED_BY} ${command}\n`)
-    else stdout.write(`${RAN} ${command}\n`)
+    ok = exitCode === undefined || exitCode === 0
   } catch (thrown) {
     const code = refusal(thrown)
     if (code === undefined) {
-
-      stdout.write(`${REFUSED_BY} ${command}\n`)
+      ok = false
       stdout.write(`round: \`${command}\` threw: ${thrown instanceof Error ? thrown.message : String(thrown)}\n`)
-    } else if (code === 0) stdout.write(`${RAN} ${command}\n`)
-    else stdout.write(`${REFUSED_BY} ${command}\n`)
+    } else ok = code === 0
+  }
   }
+
+  stdout.write(`${ok ? RAN : REFUSED_BY} ${command}\n`)
+  stderr.write(`settle: ${command} — ${String(Date.now() - began)} ms, ${ok ? 'ran' : 'refused'}\n`)
+
+  stale = !command.trim().endsWith('--check')
 }
 
 process.exitCode = 0

package/dist/core/rows.d.ts

@@ -5,6 +5,7 @@ export interface Bounds {
 export declare function inCode(text: string): readonly boolean[];
 export declare function matched(text: string, code: readonly boolean[], from: number, open: string, close: string): number;
 export declare function listBounds(text: string, list: string): Bounds | undefined;
+export declare function nestedBounds(text: string, where: Bounds, parent: string, list: string): Bounds | undefined;
 export declare function holdsRow(text: string, where: Bounds, id: string): boolean;
 export declare function seededAt(text: string, where: Bounds, id: string): string | undefined;
 export declare function rowsIn(text: string, where: Bounds): readonly {
@@ -24,5 +25,8 @@ export declare const STATED: string[];
 export declare function reconciled(held: string, source: string, fields: readonly string[]): string;
 export declare function fieldIn(text: string, where: Bounds, id: string, field: string): string | undefined;
 export declare function withField(text: string, where: Bounds, id: string, field: string, value: string): string | undefined;
+export declare function withTopField(text: string, field: string, value: string): string | undefined;
+export declare function withoutField(text: string, where: Bounds, id: string, field: string): string;
 export declare function withoutRow(text: string, where: Bounds, id: string): string;
+export declare function marked(parts: readonly string[]): string;
 export declare function showing(row: object, only?: readonly string[]): string;