@volter/world-core 3.0.38 → 3.0.40

package/src/file-response.ts

@@ -33,7 +33,7 @@ export function bytesResponse(request: Request, bytes: Uint8Array, contentType:
   const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
   let start = 0;
   let end = total - 1;
-  const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && Number(range[1]) > Number(range[2]));
+  const valid = range !== null && (range[1] !== '' || range[2] !== '') && !(range[1] !== '' && range[2] !== '' && BigInt(range[1]) > BigInt(range[2]));
   if (valid) {
     if (range[1] === '') { start = Math.max(0, total - Number(range[2])); } else {
       start = Number(range[1]);

package/src/form.ts

@@ -0,0 +1,66 @@
+import { exactInteger } from './exact-json.ts';
+// Side-effect-free URL-encoded form reading, shared by requests and published examples.
+
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export function ownField(node: Record<string, unknown> | unknown[], key: string, value: unknown): void {
+  Object.defineProperty(node, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A field the object holds as its own, never one it inherits (`constructor` is every object's). */
+const ownValue = (node: Record<string, unknown> | unknown[], key: string): unknown => (Object.hasOwn(node, key) ? (node as Record<string, unknown>)[key] : undefined);
+
+/** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
+ *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
+ *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
+ *  (`metadata[order]=007`, `name=2024`). */
+export function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [rawKey, raw] of new URLSearchParams(text)) {
+    const parts = rawKey.replace(/\]/g, '').split('[');
+    const kind = scalars && scalarAt(scalars, parts);
+    const value: unknown = kind === 'boolean' ? (raw === 'true' ? true : raw === 'false' ? false : raw)
+      : kind === 'integer' ? (/^-?\d+$/.test(raw) ? exactInteger(raw) : raw)
+      : kind === 'number' ? (/^-?\d+$/.test(raw) ? exactInteger(raw) : /^-?\d+\.\d+$/.test(raw) ? Number(raw) : raw)
+      : raw;
+    // every field is the node's own, read and written as such: a key naming an object's machinery (`__proto__[x]`,
+    // `constructor[prototype][x]`) is a field of that name, never a walk into what every object inherits
+    let node: Record<string, unknown> | unknown[] = out;
+    for (const [i, key] of parts.entries()) {
+      // an array holds its items by index (`a[]`, `a[0]`): a named key under one (`a[]=1&a[length]=-1`) has nowhere to
+      // go, as a key under text has none (`a=1&a[b]=2`): the first shape stands
+      if (Array.isArray(node) && key !== '' && !/^\d+$/.test(key)) break;
+      if (i === parts.length - 1) {
+        if (key === '') {
+          if (Array.isArray(node)) node.push(value);
+        } else {
+          const held = ownValue(node, key);
+          if (held === undefined) ownField(node, key, value);
+          else if (Array.isArray(held)) held.push(value);
+          else ownField(node, key, [held, value]);
+        }
+        break;
+      }
+      const next = parts[i + 1]!;
+      if (key === '') break;
+      let child = ownValue(node, key);
+      if (child === undefined) { child = next === '' || /^\d+$/.test(next) ? [] : {}; ownField(node, key, child); }
+      if (child === null || typeof child !== 'object') break;
+      node = child as Record<string, unknown> | unknown[];
+    }
+  }
+  return out;
+}
+
+/** The type `scalars` gives a form key's parts: a segment is a property name, `[]` an array's item (an index or empty),
+ *  `*` a map's key. */
+function scalarAt(scalars: Readonly<Record<string, string | undefined>>, parts: string[]): string | undefined {
+  let paths = [''];
+  for (const [i, part] of parts.entries()) {
+    const segs = part === '' || /^\d+$/.test(part) ? ['[]', '*'] : [part, '*'];
+    paths = paths.flatMap((p) => segs.map((seg) => (i === 0 ? seg : `${p}.${seg}`)));
+    if (paths.length > 64) paths = paths.filter((p) => Object.keys(scalars).some((k) => k === p || k.startsWith(`${p}.`)));
+  }
+  for (const p of paths) if (scalars[p]) return scalars[p];
+  return undefined;
+}
+

package/src/git/format.ts

@@ -0,0 +1,89 @@
+// Git text representations over the object store (architecture, The engine slot).
+import { decodeCommit, type GitObjectStore, type Ident } from './objects.ts';
+import { diffTrees, lineDiff, unifiedPatch, type TreeChange } from './history.ts';
+
+const decoder = new TextDecoder();
+const binary = (bytes: Uint8Array): boolean => bytes.slice(0, 8000).includes(0);
+const pathName = (path: string): string => /[\s"\\\x00-\x1f]/.test(path) ? JSON.stringify(path) : path;
+async function bytesOf(store: GitObjectStore, sha?: string, mode?: string): Promise<Uint8Array> {
+  if (!sha) return new Uint8Array();
+  if (mode === '160000') return new TextEncoder().encode(`Subproject commit ${sha}\n`);
+  return (await store.read(sha))?.payload ?? new Uint8Array();
+}
+async function fileDiff(store: GitObjectStore, change: TreeChange): Promise<{ text: string; additions: number; deletions: number }> {
+  const oldBytes = await bytesOf(store, change.oldSha, change.oldMode);
+  const newBytes = await bytesOf(store, change.newSha, change.newMode);
+  const left = pathName(`a/${change.path}`), right = pathName(`b/${change.path}`);
+  let text = `diff --git ${left} ${right}\n`;
+  if (!change.oldSha) text += `new file mode ${change.newMode}\n`;
+  else if (!change.newSha) text += `deleted file mode ${change.oldMode}\n`;
+  else if (change.oldMode !== change.newMode) text += `old mode ${change.oldMode}\nnew mode ${change.newMode}\n`;
+  if (change.oldSha === change.newSha) return { text, additions: 0, deletions: 0 };
+  text += `index ${(change.oldSha ?? '0000000').slice(0, 7)}..${(change.newSha ?? '0000000').slice(0, 7)}${change.oldSha && change.newSha && change.oldMode === change.newMode ? ` ${change.newMode}` : ''}\n`;
+  if (binary(oldBytes) || binary(newBytes)) return { text: `${text}Binary files ${change.oldSha ? left : '/dev/null'} and ${change.newSha ? right : '/dev/null'} differ\n`, additions: 0, deletions: 0 };
+  const oldText = decoder.decode(oldBytes), newText = decoder.decode(newBytes);
+  const edits = lineDiff(oldText, newText);
+  text += `--- ${change.oldSha ? left : '/dev/null'}\n+++ ${change.newSha ? right : '/dev/null'}\n${unifiedPatch(oldText, newText)}\n`;
+  return { text, additions: edits.filter((edit) => edit.kind === '+').length, deletions: edits.filter((edit) => edit.kind === '-').length };
+}
+/** A complete unified diff between two trees or commits, with null as the empty preimage. */
+export async function diffText(store: GitObjectStore, from: string | null, to: string): Promise<string> {
+  const changes = await diffTrees(store, from, to);
+  return (await Promise.all(changes.map((change) => fileDiff(store, change)))).map((file) => file.text).join('');
+}
+function mailDate(author: Ident): string {
+  const sign = author.tz.startsWith('-') ? -1 : 1;
+  const offset = sign * (Number(author.tz.slice(1, 3)) * 60 + Number(author.tz.slice(3, 5)));
+  const date = new Date((author.time + offset * 60) * 1000);
+  const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const pad = (n: number): string => String(n).padStart(2, '0');
+  return `${weekdays[date.getUTCDay()]}, ${date.getUTCDate()} ${months[date.getUTCMonth()]} ${date.getUTCFullYear()} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} ${author.tz}`;
+}
+/** One commit as an email patch; series metadata numbers the subject for a comparison's commits. */
+export async function formatPatch(store: GitObjectStore, sha: string, series?: { number: number; total: number }): Promise<string | null> {
+  const object = await store.read(sha);
+  if (!object || object.type !== 'commit') return null;
+  const commit = decodeCommit(object.payload);
+  const changes = await diffTrees(store, commit.parents[0] ?? null, sha);
+  const files = await Promise.all(changes.map((change) => fileDiff(store, change)));
+  const width = Math.max(0, ...changes.map((change) => change.path.length));
+  const stats = changes.map((change, i) => {
+    const file = files[i]!;
+    return ` ${change.path.padEnd(width)} | ${file.additions + file.deletions} ${'+'.repeat(file.additions)}${'-'.repeat(file.deletions)}\n`;
+  }).join('');
+  const additions = files.reduce((sum, file) => sum + file.additions, 0), deletions = files.reduce((sum, file) => sum + file.deletions, 0);
+  const summary = `${changes.length} file${changes.length === 1 ? '' : 's'} changed${additions ? `, ${additions} insertion${additions === 1 ? '' : 's'}(+)` : ''}${deletions ? `, ${deletions} deletion${deletions === 1 ? '' : 's'}(-)` : ''}`;
+  const [title = '', ...rest] = commit.message.trimEnd().split('\n');
+  const body = rest.join('\n').trim();
+  const numbered = series && series.total > 1 ? ` ${series.number}/${series.total}` : '';
+  return `From ${sha} Mon Sep 17 00:00:00 2001\nFrom: ${commit.author.name} <${commit.author.email}>\nDate: ${mailDate(commit.author)}\nSubject: [PATCH${numbered}] ${title}\n\n${body ? `${body}\n\n` : ''}---\n${stats} ${summary}\n\n${files.map((file) => file.text).join('')}`;
+}
+
+/** Submodule paths and URLs declared by a .gitmodules file (git configuration syntax). */
+export function parseSubmodules(text: string): Array<{ name: string; path: string; url: string }> {
+  const modules: Array<{ name: string; path: string; url: string }> = [];
+  let current: { name: string; path: string; url: string } | undefined;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    const section = /^\[submodule\s+"((?:[^"\\]|\\.)*)"\]\s*(?:[#;].*)?$/.exec(line);
+    if (section) { current = { name: section[1]!.replace(/\\(.)/g, '$1'), path: '', url: '' }; modules.push(current); continue; }
+    if (line.startsWith('[')) { current = undefined; continue; }
+    const field = /^(path|url)\s*=\s*(.*)$/i.exec(line);
+    if (!current || !field) continue;
+    const value = field[2]!.replace(/\s+[#;].*$/, '').trim();
+    current[field[1]!.toLowerCase() as 'path' | 'url'] = value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1).replace(/\\(.)/g, '$1') : value;
+  }
+  return modules.filter((module) => module.path && module.url);
+}
+
+/** A repository-relative symbolic-link target; targets escaping the repository have no local path. */
+export function symlinkPath(path: string, target: string): string | undefined {
+  if (target.startsWith('/')) return undefined;
+  const segments = path.split('/').slice(0, -1);
+  for (const part of target.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') { if (!segments.length) return undefined; segments.pop(); } else segments.push(part);
+  }
+  return segments.join('/');
+}

package/src/git/index.ts

@@ -5,3 +5,4 @@ export * from './refs.ts';
 export * from './smart-http.ts';
 export * from './history.ts';
 export * from './lfs.ts';
+export * from './format.ts';

package/src/git/lfs.ts

@@ -1,3 +1,4 @@
+import { exactInteger } from '../exact-json.ts';
 // GIT LFS (architecture, "The tree contract": Git LFS is the git library's too): the batch API git-lfs speaks
 // (https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md, the basic transfer), a pointer file read
 // (https://github.com/git-lfs/git-lfs/blob/main/docs/spec.md), and an upload accepted only when its bytes hash to the
@@ -6,7 +7,7 @@
 // Importing it does nothing.
 
 export const LFS_TYPE = 'application/vnd.git-lfs+json';
-export type LfsObject = { oid: string; size: number };
+export type LfsObject = { oid: string; size: number | string };
 /** Where a pack keeps its objects: by oid. */
 export type LfsStore = { get(oid: string): Promise<Uint8Array | null>; put(oid: string, bytes: Uint8Array): Promise<void> };
 
@@ -20,7 +21,7 @@ export function parseLfsPointer(file: Uint8Array | string): LfsObject | null {
   if (!text.startsWith('version https://git-lfs.github.com/spec/')) return null;
   const oid = /^oid sha256:([0-9a-f]{64})$/m.exec(text)?.[1];
   const size = /^size (\d+)$/m.exec(text)?.[1];
-  return oid && size ? { oid, size: Number(size) } : null;
+  return oid && size ? { oid, size: exactInteger(size) } : null;
 }
 
 /** A pointer file's text for an object. */
@@ -44,9 +45,9 @@ export async function lfsBatch(body: unknown, opts: { store: LfsStore; href: (op
   const operation = b.operation;
   const objects = [];
   for (const raw of b.objects as Array<{ oid?: unknown; size?: unknown }>) {
-    const o = { oid: String(raw?.oid ?? ''), size: Number(raw?.size) };
+    const o = { oid: String(raw?.oid ?? ''), size: /^-?\d+$/.test(String(raw?.size)) ? exactInteger(String(raw?.size)) : Number(raw?.size) };
     // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object is invalid (for example, an invalid oid or size)."
-    if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || o.size < 0) { objects.push({ ...o, error: { code: 422, message: 'Invalid object' } }); continue; }
+    if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || Number(o.size) < 0) { objects.push({ ...o, error: { code: 422, message: 'Invalid object' } }); continue; }
     const held = await opts.store.get(o.oid);
     if (operation === 'upload') {
       objects.push(held ? { ...o, authenticated: true } : { ...o, authenticated: true, actions: { upload: { href: opts.href('upload', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } });

package/src/graphql-wire.ts

@@ -16,6 +16,8 @@ export type GraphqlResolver<C = unknown> = (source: Record<string, unknown>, arg
 
 /** What a pack's `semantics/graphql.ts` exports as `graphql`. */
 export type GraphqlPart<C = unknown> = {
+  /** The root operations derived from the SDL, for dispatch ownership and gap reporting. */
+  operations?: ReadonlyArray<{ id: string; kind: 'query' | 'mutation'; field: string }>;
   /** resolvers by `Type.field` (`Query.repository`, `PullRequest.state`) */
   resolvers: Record<string, GraphqlResolver<C>>;
   /** per type, a GraphQL field name → the object's field that holds it (`nameWithOwner` → `full_name`) */
@@ -63,8 +65,11 @@ export function graphqlEndpoint<C>(options: {
 }): (request: Request) => Promise<Response> {
   let schema: import('graphql').GraphQLSchema | undefined;
   const { resolvers, aliases, stored } = options.part;
+  // introspection (`__typename`, `__type`, `__schema` and the `__Type`/`__Field`/… meta types) is the vendor's schema
+  // describing itself, answered by graphql-js from the SDL: modeled as the schema is (gh asks `__type(name:"PullRequest")`
+  // before it merges)
   const modeled = (type: string, field: string): boolean =>
-    field === '__typename' || `${type}.${field}` in resolvers || !!aliases?.[type]?.[field] || !!stored?.[type]?.includes(field) || !!stored?.[type]?.includes(snake(field));
+    field.startsWith('__') || type.startsWith('__') || `${type}.${field}` in resolvers || !!aliases?.[type]?.[field] || !!stored?.[type]?.includes(field) || !!stored?.[type]?.includes(snake(field));
   return async (request) => {
     const g = await graphqlLib();
     schema ??= g.buildSchema(options.sdl, { assumeValidSDL: true });
@@ -87,10 +92,10 @@ export function graphqlEndpoint<C>(options: {
     const ctx = await options.context(request);
     const result = await g.execute({
       schema, document, variableValues: payload.variables ?? {}, ...(payload.operationName ? { operationName: payload.operationName } : {}), contextValue: ctx,
-      fieldResolver: (source, args, context, info) => {
+      fieldResolver: async (source, args, context, info) => {
         const own = resolvers[`${info.parentType.name}.${info.fieldName}`];
         const obj = (source ?? {}) as Record<string, unknown>;
-        let value = own ? own(obj, args as Record<string, unknown>, context as C) : (obj[aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
+        let value = own ? await own(obj, args as Record<string, unknown>, context as C) : (obj[aliases?.[info.parentType.name]?.[info.fieldName] ?? info.fieldName] ?? obj[snake(info.fieldName)] ?? null);
         const named = g.getNamedType(info.returnType);
         if (Array.isArray(value) && g.isObjectType(named) && named.name.endsWith('Connection')) value = connection(value, args as Record<string, unknown>);
         if (typeof value === 'string' && g.isEnumType(named)) value = named.getValues().find((v) => v.name.toLowerCase() === String(value).toLowerCase())?.name ?? value;

package/src/grpc-wire.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 // THE gRPC WIRE (architecture, "Other wires": gRPC): unary gRPC calls over the kernel's HTTP/2 server (./h2.ts), each
 // request's one length-prefixed message decoded by the proto unit's schema (./protobuf.ts) and handed to the pack's
 // handler for its operation, whose JSON answer is encoded back with the status trailers
@@ -137,7 +138,7 @@ export function grpcOverFetch(fetch: (request: Request) => Promise<Response>): G
     const res = await fetch(new Request(`http://twin${call.path}`, { method: 'POST', headers: { ...call.metadata, 'content-type': 'application/json' }, body: JSON.stringify(call.request), signal: call.signal }));
     const text = await res.text();
     let body: unknown;
-    try { body = text ? JSON.parse(text) : {}; } catch { body = undefined; }
+    try { body = text ? parseExactJson(text) : {}; } catch { body = undefined; }
     if (res.ok) return (body ?? {}) as Record<string, unknown>;
     const message = (body as { error?: { message?: unknown }; message?: unknown } | undefined)?.error?.message ?? (body as { message?: unknown } | undefined)?.message ?? text;
     throw new GrpcError(codeOf(res.status, body), String(message).slice(0, 500));

package/src/head.ts

@@ -31,7 +31,7 @@ export type PushOutcome = {
   /** the group's entry the id is for, when it is not the group's first (a cascade writes children first) */
   actionId?: string;
   /** the group's other entries the answer named an id for (a resource's `companions`) */
-  also?: Array<{ actionId: string; externalId: string }>;
+  also?: Array<{ actionId: string; externalId: string; data?: Record<string, unknown> }>;
 };
 /** What a perform is handed beside the executor: a resolver from a local id to the vendor's (an
  *  entry authored against `twin-1` crosses against `REAL-42` once that subject's landing adopted it). */
@@ -377,6 +377,14 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
   let stopped = false;
   for (const group of groupsOf(pick(settling.offered))) {
     if (stopped) { report.skipped.push(...group.map((a) => a.id)); continue; }
+    // a write of a unit the pack sends nowhere (`vendorBacked.none` beside vendor-backed lanes) is the World's alone
+    const unsent = adapters.unsent?.(group[0]!.input as Record<string, unknown> | undefined);
+    if (unsent) {
+      const at = opts.at ?? worldNow();
+      for (const action of group) settle(action, at, { status: 'landed', reason: unsent });
+      report.worldOnly.push(...group.map((a) => a.id));
+      continue;
+    }
     if (named(group[0]!).some((v) => refusedIds.has(v))) {
       const at = opts.at ?? worldNow();
       for (const action of group) { settle(action, at, { status: 'landed', reason: 'names a subject the vendor refused: the World\'s alone' }); refusedIds.add(action.subject.id); }
@@ -402,12 +410,14 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
       // the vendor's answer, when the adapter returned one as fields, is what the primary entry's landed copy holds
       const answered = outcome.data !== null && typeof outcome.data === 'object' && !Array.isArray(outcome.data) ? (outcome.data as Record<string, unknown>) : {};
       const primary = resolved.find((a) => a.id === outcome.actionId) ?? resolved[0]!;
-      const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a.externalId]));
+      const also = new Map((outcome.also ?? []).map((a) => [a.actionId, a]));
       for (const action of resolved) {
-        const externalId = action === primary ? outcome.externalId : also.get(action.id);
-        settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, action === primary ? { ...action.fields, ...answered } : action.fields ?? {}, externalId || undefined);
+        const answeredId = action === primary ? outcome.externalId : also.get(action.id)?.externalId;
+        const externalId = answeredId || aliases.get(`${action.subject.type}:${action.subject.id}`);
+        settle(action, at, { status: 'deployed', ...(action === primary && outcome.url ? { url: outcome.url } : {}) }, { ...action.fields, ...(action === primary ? answered : also.get(action.id)?.data ?? {}) }, externalId || undefined);
+        const data = action === primary ? outcome.data : also.get(action.id)?.data;
         report.pushed += 1;
-        report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(action === primary && outcome.data !== undefined ? { data: outcome.data } : {}) });
+        report.deployed.push({ actionId: action.id, at, ...(externalId ? { externalId } : {}), ...(data !== undefined ? { data } : {}) });
       }
     } catch (error) {
       // a write the vendor refuses (a 4xx: it can never be sent as it is) settles the group refused, as a check's

package/src/held-reads.ts

@@ -0,0 +1,54 @@
+// A read held until the World writes (architecture, "Other wires": a read held until the World writes): HTTP long
+// polling, as Telegram's getUpdates is, where a client asks again at once on an empty answer. A handler that finds
+// nothing to answer awaits `ctx.awaitWrite(types, ms)`: it settles true when a write of one of the stored types lands in
+// the same World (the derived core's one write path tells it, as it tells the open sockets), false when the time runs
+// out or the client hangs up. The wait is the connection's, never World state: the handler reads the tree again and
+// answers what it holds. Nothing here runs at module scope beyond the empty registry.
+
+type Waiter = { types: ReadonlySet<string>; settle: (wrote: boolean) => void };
+const waiting = new Map<string, Set<Waiter>>();
+const keyOf = (service: string, root: string | undefined): string => `${service}\0${root ?? ''}`;
+
+/** Tell every read held in this World that a subject of `storedType` was written. */
+export function heldReadsWrite(service: string, root: string | undefined, storedType: string): void {
+  const held = waiting.get(keyOf(service, root));
+  if (!held?.size) return;
+  for (const w of [...held]) if (w.types.has(storedType)) w.settle(true);
+}
+
+/** Wait until a write of one of `storedTypes` lands in this World (true), or `ms` pass or `signal` aborts (false). */
+export function awaitWrite(service: string, root: string | undefined, storedTypes: ReadonlyArray<string>, ms: number, signal?: AbortSignal): Promise<boolean> {
+  if (!(ms > 0) || signal?.aborted) return Promise.resolve(false);
+  const key = keyOf(service, root);
+  return new Promise((resolve) => {
+    let held = waiting.get(key);
+    if (!held) { held = new Set(); waiting.set(key, held); }
+    const set = held;
+    const waiter: Waiter = {
+      types: new Set(storedTypes),
+      settle: (wrote) => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        set.delete(waiter);
+        if (!set.size) waiting.delete(key);
+        resolve(wrote);
+      },
+    };
+    const onAbort = (): void => waiter.settle(false);
+    const timer = setTimeout(() => waiter.settle(false), ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    set.add(waiter);
+  });
+}
+
+/** Hold a read until its condition holds, within the caller's timeout. The kernel owns elapsed time. */
+export async function awaitCondition(service: string, root: string | undefined, storedTypes: ReadonlyArray<string>, ms: number, pollMs: number, condition: () => Promise<boolean>, signal?: AbortSignal): Promise<boolean> {
+  if (!(pollMs > 0)) throw new Error('a held condition requires a positive observation cadence');
+  const deadline = Date.now() + Math.max(0, ms);
+  for (;;) {
+    if (await condition()) return true;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0 || signal?.aborted) return false;
+    await awaitWrite(service, root, storedTypes, Math.min(remaining, pollMs), signal);
+  }
+}

package/src/history.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 // Immutable views over shared append-only segments. A position is meaningful within a view.
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
@@ -34,7 +35,7 @@ const viewPath = (directory: string, id: string) => {
   return join(directory, 'views', `${id}.json`);
 };
 function rows(directory: string, file: Segment['file']): Entry[] {
-  return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(JSON.parse(line)));
+  return getActiveWorldStore().readLines(join(directory, file)).filter(line => line.trim()).map(line => toEntry(parseExactJson(line)));
 }
 function sliceLayout(layout: HistoryLayout, at: number): HistoryLayout {
   const base = layout.base ? historyLength(layout.base) : 0;
@@ -43,7 +44,7 @@ function sliceLayout(layout: HistoryLayout, at: number): HistoryLayout {
 export function readHistoryView(directory: string, id: string): HistoryView {
   const raw = getActiveWorldStore().read(viewPath(directory, id));
   if (raw === null) throw new Error(`Missing retained history view ${id}`);
-  const { dependencies: _dependencies, ...view } = JSON.parse(raw) as HistoryView & { dependencies?: unknown };
+  const { dependencies: _dependencies, ...view } = parseExactJson(raw) as HistoryView & { dependencies?: unknown };
   if (view.version !== 1 || historyDigest({ ...view, dependencies: _dependencies }) !== id) throw new Error(`Invalid retained history view ${id}`);
   historyLength(view.layout);
   if (view.origin) validateHistoryOrigin(view.origin, view.layout);
@@ -99,7 +100,7 @@ export function inheritedHistoryKey(service: string, root?: string): string {
   let raw: string | null; let at: string;
   try { at = viewPath(directory, parent.view); raw = store.read(at); } catch { return 'invalid-view'; }
   if (raw === null) return 'missing-view';
-  const view = JSON.parse(raw) as HistoryView;
+  const view = parseExactJson(raw) as HistoryView;
   const directories = new Set<string>([view.owner?.directory ?? '', ...(view.segments ?? []).map((sp) => sp.directory)]);
   if (!isUrlParent(parent.at)) directories.add(worldPaths(service, parent.at).dir);
   const files = [...new Set((view.segments ?? []).map((sp) => join(sp.directory, sp.file)))].sort();
@@ -133,7 +134,7 @@ export function captureHistory(service: string, root?: string): { view: string;
 }
 export function originHead(service: string, root?: string): { view: string; remoteView: string } | null {
   const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
-  return raw === null ? null : JSON.parse(raw);
+  return raw === null ? null : parseExactJson(raw);
 }
 /** A complete remote view shares cached rows by content, never by mutable offsets or entry ID. */
 export function publishOriginHistory(service: string, root: string, remoteView: string, layout: HistoryLayout, entries: Entry[]): { view: string; appended: number } {

package/src/host-port.ts

@@ -0,0 +1,9 @@
+/** Read a Host authority with the platform URL parser; bracketed IPv6 retains its address. */
+export function readHostPort(authority: string): { host: string; port: string } | undefined {
+  try {
+    if (!authority || /[\s/\\?#@]/.test(authority)) return undefined;
+    const url = new URL(`http://${authority}`);
+    if (url.username || url.password) return undefined;
+    return { host: url.hostname.toLowerCase(), port: url.port };
+  } catch { return undefined; }
+}

package/src/index.ts

@@ -16,7 +16,9 @@ export type { PackDescriptor, PackTransport } from './packRegistry.ts';
 export const packOf = (
   manifest: { vendor: string; descriptor?: Omit<PackDescriptor, 'vendor'> },
   surface?: DerivedSurface | Record<string, { manifest: DerivedManifest; surface: DerivedSurface }>,
-): PackDescriptor => packOfAny(manifest, surface);
+  /** the lanes beside a pack that has an API of its own (Clerk's `fapi`, PlanetScale's `api`) */
+  beside?: Record<string, { manifest: DerivedManifest; surface: DerivedSurface }>,
+): PackDescriptor => packOfAny(manifest, surface, beside);
 /** The pack registered, so the World finds it. */
 export const registerPack = (pack: PackDescriptor): PackDescriptor => registerAny(pack);
 
@@ -27,7 +29,7 @@ export { verifyEvent } from './events.ts';
 export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.ts';
 export type { IngestDecl } from './derived-core.ts';
 export type { SocketDecl, SocketEngine, SocketSession } from './sockets.ts';
-export { machinePool, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec } from './machines.ts';
+export { machinePool, isMachineCapabilityGap, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec, type MachineStatus, type MachineFiles, type MachineFileStat } from './machines.ts';
 export type { CorsDecl } from './cors.ts';
 
 // ── the handler contract ───────────────────────────────────────────────────────────────────────
@@ -51,6 +53,7 @@ export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts'
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
 export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
+export { privateTransportKey } from './private-transport.ts';
 // where a page links a hostname its twin answers, inside the World that shows it
 export { siteLabel, siteUrlOf, twinSiteUrl, twinVendorUrl } from './twin-fetch.ts';
 export { statefulTwinManifest, twinManifest } from './scenario.ts';
@@ -58,7 +61,7 @@ export { assetContentType, packAsset } from './pack-assets.ts';
 export { bytesResponse, contentTypeOf, fileResponse } from './file-response.ts';
 
 // ── the kernel's deterministic helpers ─────────────────────────────────────────────────────────
-export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.ts';
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, base62From, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.ts';
 export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
 export { blobDigest } from './blob-store.ts';
 // compressed bytes a wire carries (a SARIF upload), over web streams
@@ -69,7 +72,7 @@ export type { TwinResource } from './serve.ts';
 // the people a vendor's pages sign in (a `_person` row with its password's hash)
 export { passwordHash, personOf, personWith, recordPerson, type Person } from './people.ts';
 // the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
-export { EngineDatabaseError, EngineUnavailableError, quoteIdent, worldClockSql } from './managed-database.ts';
+export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
 export type { Mail, SmtpRoute } from './smtp.ts';
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
@@ -90,6 +93,9 @@ export * as git from './git/index.ts';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.ts';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
 
+export { verifyAttestationBundle } from './attestation.ts';
+
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
 
+export { readHostPort } from './host-port.ts';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.ts';

package/src/log.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 // THE LOG (docs/concepts/the-model.md). One kind of entry, one log per
 // branch, and a branch is a parent plus a position in the parent's log:
 //
@@ -116,7 +117,7 @@ const parsedRows = new WeakMap<object, Map<string, ParsedLog>>();
 function parseLines<T>(path: string, lines: string[], offset: number, out: T[]): void {
   for (const [i, line] of lines.entries()) {
     if (!line.trim()) continue;
-    try { out.push(JSON.parse(line) as T); } catch (error) { throw new Error(`${path}:${offset + i + 1}: invalid JSONL row: ${(error as Error).message}`); }
+    try { out.push(parseExactJson(line) as T); } catch (error) { throw new Error(`${path}:${offset + i + 1}: invalid JSONL row: ${(error as Error).message}`); }
   }
 }
 
@@ -173,7 +174,7 @@ function readRows<T>(path: string): T[] {
 export function readBranchMeta(service: string, root?: string): BranchMeta | null {
   const raw = getActiveWorldStore().read(branchMetaPath(service, root));
   if (raw === null) return null;
-  const meta = JSON.parse(raw) as BranchMeta & { parent?: { root?: string; parentCount?: number; branchCount?: number } };
+  const meta = parseExactJson(raw) as BranchMeta & { parent?: { root?: string; parentCount?: number; branchCount?: number } };
   // a pointer written before positions were one number: the parent's whole log is parent then branch
   if (meta.parent && meta.parent.at === undefined && meta.parent.root !== undefined) meta.parent = { at: meta.parent.root, position: (meta.parent.parentCount ?? 0) + (meta.parent.branchCount ?? 0) };
   return meta as BranchMeta;
@@ -324,7 +325,7 @@ export function landedIds(parent: Entry[]): Set<string> {
  *  the vendor's subject onto the landed one, nor send a caller who addresses the vendor's id there. */
 export function aliasesFrom(parent: Entry[]): Map<string, string> {
   const vendorHeld = new Set<string>();
-  for (const e of parent) if (e.batch !== undefined || e.operation === 'observed' || e.event !== undefined || e.landsId !== undefined) vendorHeld.add(`${e.subject.type}:${e.subject.id}`);
+  for (const e of parent) if (e.batch !== undefined || e.operation === 'observed' || e.event !== undefined || (e.landsId !== undefined && e.receipt?.status === 'deployed')) vendorHeld.add(`${e.subject.type}:${e.subject.id}`);
   const out = new Map<string, string>();
   for (const e of parent) {
     if (!e.aliasOf || e.aliasOf === e.subject.id) continue;
@@ -397,7 +398,7 @@ export function treeResources(tree: Tree): TwinResource[] {
   return [...tree.values()].map((s) => {
     const out: Record<string, unknown> = { id: s.id, type: s.type, updatedAt: s.updatedAt };
     const own: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(s.fields)) { if (!META.has(k)) out[k] = v; else if (v !== undefined && v !== (out[k] as unknown)) own[k] = v; }
+    for (const [k, v] of Object.entries(s.fields)) { if (!META.has(k)) out[k] = v; else if (v !== undefined) own[k] = v; }
     if (Object.keys(own).length) Object.defineProperty(out, OWN, { value: own, enumerable: false });
     return out as TwinResource;
   });
@@ -416,7 +417,10 @@ export function ownFields(r: TwinResource): Record<string, unknown> {
   const { id: _id, type: _type, updatedAt: _at, ...rest } = r;
   const own = ((r as unknown as Record<symbol, unknown>)[OWN] ?? {}) as { id?: unknown; type?: unknown; updatedAt?: unknown };
   // restored first: a vendor's object leads with its id, and a reader's grep may count on the order
-  return { ...(own.id !== undefined ? { id: own.id } : {}), ...(own.type !== undefined ? { type: own.type } : {}), ...rest, ...(own.updatedAt !== undefined ? { updatedAt: own.updatedAt } : {}) };
+  const out = { ...(own.id !== undefined ? { id: own.id } : {}), ...(own.type !== undefined ? { type: own.type } : {}), ...rest, ...(own.updatedAt !== undefined ? { updatedAt: own.updatedAt } : {}) };
+  // the own record rides along unseen, so an own view taken of an own view is the same view (never one that drops them)
+  if ((r as unknown as Record<symbol, unknown>)[OWN] !== undefined) Object.defineProperty(out, OWN, { value: own, enumerable: false });
+  return out;
 }
 
 /** `facts`, when present, is the parent and branch logs' size and version with branch.json at the cut
@@ -598,7 +602,7 @@ function readTreeMapFull(service: string, root?: string, opts: { until?: string;
   const facts = opts.until === undefined ? `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}` : null;
   if (facts !== null) {
     const held = getActiveWorldStore().read(checkpointPath(service, root));
-    const cut = held === null ? null : JSON.parse(held) as Checkpoint;
+    const cut = held === null ? null : parseExactJson(held) as Checkpoint;
     if (cut?.facts === facts) return new Map(cut.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
   }
   const inherited = inheritedHistory(service, root);
@@ -610,7 +614,7 @@ function readTreeMapFull(service: string, root?: string, opts: { until?: string;
   const branch = until < 0 ? branchAll : branchAll.slice(0, until);
   const parentDigest = hashFieldValue({ inherited, own }); const branchDigest = hashFieldValue(branch);
   const raw = opts.until === undefined ? getActiveWorldStore().read(checkpointPath(service, root)) : null;
-  const cp = raw === null ? null : JSON.parse(raw) as Checkpoint;
+  const cp = raw === null ? null : parseExactJson(raw) as Checkpoint;
   if (cp?.parentDigest === parentDigest && cp.branchDigest === branchDigest) return new Map(cp.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
   const layout: HistoryLayout = { ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: branch.length };
   const incremental = cp?.parentDigest === parentDigest && cp.branchCount <= branch.length && hashFieldValue(branch.slice(0, cp.branchCount)) === cp.branchDigest && !branch.slice(cp.branchCount).some(e => e.op === 'revert');