@volter/world-core 3.0.154 → 3.0.156

package/src/derived-core.ts

@@ -6,8 +6,9 @@ import { parseExactJson, compareExactNumbers, exactInteger, isExactIntegerValue
 // serves CRUD generically and applies declared transitions, over the kernel's tree and write path.
 // Nothing here knows a vendor: every vendor difference is a manifest value.
 
-import { applyTwinWrite, applyTwinWriteAtomic, twinResources, type TwinResource } from './serve.ts';
-import { copyResource, ownFields, parentStamp, subjectHistory, treeChangesSince, treeStamp } from './log.ts';
+import { applyTwinWrite, applyTwinWriteAtomic, applyTwinWrites, twinResources, type TwinResource } from './serve.ts';
+import { copyResource, foldLocalWrite, heldSubject, ownFields, parentStamp, subjectHistory, treeChangesSince, treeResources, treeStamp, type Subject } from './log.ts';
+import { performsAtHeadNow } from './head.ts';
 import { getActiveWorldStore } from './world-store.ts';
 import { getActiveBlobStore } from './blob-store.ts';
 import { worldPaths } from './storage.ts';
@@ -26,6 +27,7 @@ import { handlerCrypto, hmac, ksuidFrom, lettersFrom, sha256, uuidFrom, type Han
 import { hashFieldValue } from './hash.ts';
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
 import { managedDatabase, unboundDatabase, type ManagedDatabase } from './managed-database.ts';
+import { redisServiceTimes } from './redis/service-times.ts';
 import { execRedisRun, type RedisDialect, type RunItem } from './redis/engine.ts';
 import { sendMail, type Mail, type SmtpRoute } from './smtp.ts';
 import { ownField, parseBracketForm } from './form.ts';
@@ -738,13 +740,15 @@ export function resourcesOfType(service: string, type: string, root?: string): T
     for (const [k, r] of byKey) if (!delta.appended.includes(k)) (held.byType.get(r.type) ?? held.byType.set(r.type, new Map()).get(r.type)!).set(k, r);
     for (const k of delta.appended) { const r = byKey.get(k)!; (held.byType.get(r.type) ?? held.byType.set(r.type, new Map()).get(r.type)!).set(k, r); }
     held.stamp = delta.stamp;
-  } else if (!held || held.stamp !== treeStamp(service, root)) {
-    // the stamp is read before the fold, so a write between them can only leave a newer fold under an older stamp
+  } else {
+    // the stamp is read once, before the fold, so a write between them can only leave a newer fold under an older stamp
     const stamp = treeStamp(service, root);
-    const byType = new Map<string, Map<string, TwinResource>>();
-    for (const r of twinResources(service, root)) (byType.get(r.type) ?? byType.set(r.type, new Map()).get(r.type)!).set(`${r.type}:${r.id}`, r);
-    held = { stamp, byType };
-    indexes.set(key, held);
+    if (!held || held.stamp !== stamp) {
+      const byType = new Map<string, Map<string, TwinResource>>();
+      for (const r of twinResources(service, root)) (byType.get(r.type) ?? byType.set(r.type, new Map()).get(r.type)!).set(`${r.type}:${r.id}`, r);
+      held = { stamp, byType };
+      indexes.set(key, held);
+    }
   }
   return [...(held.byType.get(type)?.values() ?? [])].map(copyResource);
 }
@@ -1808,6 +1812,17 @@ export type SemanticsContext = {
   /** Decide an update from the current live stored row under the action lock; undefined leaves it unchanged. */
   change(resource: string, id: string, decide: (row: Record<string, unknown>) => Record<string, unknown> | undefined, operation: string): Promise<Record<string, unknown> | undefined>;
   write(resource: string, id: string, fields: Record<string, unknown>, operation: string): Promise<Record<string, unknown>>;
+  /**
+   * One command's writes as one group (S2 R17; docs/contributing/architecture.md, "A command's writes as one group").
+   * Inside `fn`, `write` stages its write and answers the row as it will stand; `row` and `rowsRaw` read the tree with
+   * the staged writes folded over it, as it will be once they land. When `fn` returns or throws, every staged write
+   * lands, in order, as one append; then its value is answered or its error thrown. Every other way to write, or to
+   * wait on a write, lands the staged writes first; any other read of the tree (`get`, `rows`, `tree`, `history`, ...)
+   * while writes are staged is refused, never answered without them. Each write keeps its own action, id, ordinal,
+   * moment and recorded request. Where the pack has write hooks, events, sockets or counts, a state observer is on,
+   * a head performs, or ids are aliased, `fn` simply runs, each write landing as it is made.
+   */
+  batch<T>(fn: () => Promise<T>): Promise<T>;
   /** Add numeric deltas to an existing bookkeeping row under the kernel's atomic write seam. */
   accumulate(resource: string, id: string, deltas: Record<string, number>, operation: string): Promise<void>;
   /** `write`, with what a live vendor answered when the head performed it */
@@ -1917,7 +1932,7 @@ export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically
 };
 /** What a write hook reads: the writing call's context without its ways to write, so a hook that renders an event
  *  cannot write again (and run itself again). */
-export type WriteHookContext = Omit<HandlerContext, 'write' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'at' | 'over'>;
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'at' | 'over'>;
 /** A derived pack's handler: one operation, by its operationId, over the contract's context. */
 export type Handler = (ctx: HandlerContext) => Promise<Response>;
 
@@ -1963,7 +1978,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     rawResources.set(row as Record<string, unknown>, name ?? resource);
     return row as Record<string, unknown>;
   };
-  return {
+  const context: SemanticsContext = {
     call,
     params,
     id: Object.values(call.params).at(-1),
@@ -2172,13 +2187,129 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     over: (other) => contextFor(other, { ...asAsked, request: asAsked.request.clone() }, { ...scope, clock: () => at }),
     core: async () => { const out = await serveCore(m, { ...call, request: pristine.clone() }, { ...scope, clock: () => at }); return 'served' in out ? out.served : undefined; },
     own: (row) => ownFields(row as unknown as TwinResource),
+    batch: (fn) => fn(),
+  };
+  if (batchable(m, root)) bindBatch(m, call, context, params, root, at, rawRow);
+  return context;
+}
+
+/**
+ * Whether a call's writes may be grouped (`ctx.batch`) with nothing about them changing: every effect a write has
+ * besides its action and the tree (write hooks, events, sockets, a parent's counts, a state observer, a head that
+ * performs it, an alias a read resolves through) is one the grouped path would move, so where any is present the
+ * writes land one at a time, as they always have.
+ */
+function batchable(m: DerivedManifest, root: string | undefined): boolean {
+  return !m.onWrite && !m.events && !m.sockets?.length && !transitionObserver
+    && !Object.values(m.resources).some((decl) => decl.counts && Object.keys(decl.counts).length > 0)
+    && !performsAtHeadNow(m.service, root) && subjectAliases(m.service, root).size === 0;
+}
+
+/** A staged write of `ctx.batch`, as `write` was asked it. */
+type StagedWrite = { resource: string; id: string; fields: Record<string, unknown>; operation: string };
+
+/** The members of a context that read the tree other than `row`/`rowsRaw`: refused while writes are staged. */
+const BATCH_REFUSED_READS = ['get', 'rows', 'tree', 'history', 'find', 'list', 'expand', 'mint', 'conflict', 'ownerRow', 'render'] as const;
+/** The members that write, or wait on writes, or answer as another context: each lands the staged writes first. */
+const BATCH_LANDING_MEMBERS = ['create', 'createUnique', 'change', 'accumulate', 'writeDetailed', 'record', 'atomically', 'remove', 'issue', 'at', 'over', 'core', 'awaitWrite', 'awaitCondition',
+  // a World's seed and signing keys are written when first asked (worldSeed, worldSigningKey, as a vendor's move)
+  'secret', 'signingKey'] as const;
+
+/** `ctx.batch` over a context whose writes may be grouped (see `batchable`). */
+function bindBatch(m: DerivedManifest, call: DerivedCall, context: SemanticsContext, params: Record<string, unknown>, root: string | undefined, at: string,
+  rawRow: (resource: string, row: TwinResource) => Record<string, unknown>): void {
+  let staged: StagedWrite[] | undefined;
+  // each staged subject as it will stand, by `type:id`, in the order first written
+  const subjects = new Map<string, Subject>();
+  const land = async (): Promise<void> => {
+    if (!staged?.length) return;
+    const writes = staged;
+    staged = [];
+    subjects.clear();
+    await writeGroup(m, call, writes, params, root, at);
+  };
+  const ctx = context as unknown as Record<string, unknown>;
+  for (const name of BATCH_LANDING_MEMBERS) {
+    const plain = ctx[name];
+    if (typeof plain !== 'function') continue;
+    ctx[name] = async (...args: unknown[]) => { await land(); return (plain as (...a: unknown[]) => unknown)(...args); };
+  }
+  for (const name of BATCH_REFUSED_READS) {
+    const plain = ctx[name];
+    if (typeof plain !== 'function') continue;
+    ctx[name] = (...args: unknown[]) => {
+      if (staged?.length) throw new Error(`ctx.${name} reads the tree while ctx.batch holds staged writes: only row and rowsRaw see them`);
+      return (plain as (...a: unknown[]) => unknown)(...args);
+    };
+  }
+  const plainWrite = context.write, plainRow = context.row, plainRowsRaw = context.rowsRaw;
+  context.write = async (resource, id, fields, operation) => {
+    // a vendor's own move (ctx.asVendor) is the clock's write, recorded as the system's: it lands alone, in its place
+    if (!staged || inVendorMove()) { await land(); return plainWrite(resource, id, fields, operation); }
+    const type = storedType(m, resource), key = `${type}:${id}`;
+    // the one subject, as the memoized tree holds it (readTreeMap would copy the whole tree on every staged write)
+    const subject = foldLocalWrite(subjects.get(key) ?? heldSubject(m.service, type, id, root), type, id, fields as SubjectFields, at);
+    subjects.set(key, subject);
+    staged.push({ resource, id, fields, operation });
+    return view(m, resource, treeResources(new Map([[key, subject]]))[0]!);
+  };
+  // the stored rows of a resource's type with the staged subjects folded over them, filtered as `stored` filters
+  const overlaid = (resource: string, opts?: { withDeleted?: boolean }): TwinResource[] | undefined => {
+    if (!staged?.length) return undefined;
+    const type = storedType(m, resource), prefix = `${type}:`;
+    const mine = [...subjects].filter(([key]) => key.startsWith(prefix));
+    if (!mine.length) return undefined;
+    const replaced = new Map(mine.map(([key, subject]) => [key, treeResources(new Map([[key, subject]]))[0]!]));
+    const base = resourcesOfType(m.service, type, root);
+    // a subject the tree holds stays where it stands; one new to it goes to the end, in the order first written
+    const rows = base.map((row) => replaced.get(`${prefix}${row.id}`) ?? row);
+    const held = new Set(base.map((row) => `${prefix}${row.id}`));
+    for (const [key, row] of replaced) if (!held.has(key)) rows.push(row);
+    const when = Object.entries(m.resources[resource]?.readableWhen ?? {});
+    return rows.filter((r) => (opts?.withDeleted || r.deleted !== true) && when.every(([k, v]) => (r as Record<string, unknown>)[k] === v));
   };
+  context.row = (resource, id, opts) => {
+    const rows = overlaid(resource, opts);
+    if (!rows) return plainRow(resource, id, opts);
+    const row = rows.find((r) => r.id === id);
+    return row ? rawRow(resource, row) : undefined;
+  };
+  context.rowsRaw = (resource, opts) => {
+    const rows = overlaid(resource, opts);
+    return rows ? rows.map((row) => rawRow(resource, row)) : plainRowsRaw(resource, opts);
+  };
+  context.batch = async (fn) => {
+    // a batch inside a batch is the outer one's
+    if (staged !== undefined) return fn();
+    staged = [];
+    try { return await fn(); }
+    finally {
+      // every write `write` answered lands, whether fn returned or threw: an ordered insert's prefix stays written
+      try { await land(); } finally { staged = undefined; subjects.clear(); }
+    }
+  };
+}
+
+/**
+ * A command's staged writes landed as one group: each recorded with the request as `writeDetailed` records it (one
+ * recordedInput, the same for every write of the call), the call's moment and actor, in order, under one lock and one
+ * append (serve.ts applyTwinWrites); then a held read on each written type is told, as each write tells it.
+ */
+async function writeGroup(m: DerivedManifest, call: DerivedCall, writes: readonly StagedWrite[], params: Record<string, unknown>,
+  root: string | undefined, occurredAt: string): Promise<void> {
+  const input = recordedInput(m, call, params);
+  const files = input.operationId ? await keptFiles(m, call, root) : undefined;
+  const recorded = files ? { ...input, files } : input;
+  const actor = { kind: 'agent' as const, ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) };
+  await applyTwinWrites(m.service, writes.map((write) => ({ operation: write.operation, subjectType: storedType(m, write.resource),
+    subjectId: write.id, fields: write.fields, input: recorded, occurredAt, actor })), root);
+  for (const type of new Set(writes.map((write) => storedType(m, write.resource)))) heldReadsWrite(m.service, root, type);
 }
 
 /** A pack's semantics handlers as the dispatch's handlers. */
 export function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope: CoreScope = {}): Record<string, DerivedHandler> {
   prepareViewOmissions(m);
-  return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call: DerivedCall) => h(await contextFor(m, call, scope))]));
+  return Object.fromEntries(Object.entries(handlers).map(([id, h]) => [id, async (call: DerivedCall) => { const ctx = await contextFor(m, call, scope); redisServiceTimes.lap('6c the handler\'s own context opened'); return h(ctx); }]));
 }
 
 /** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */

package/src/derived.ts

@@ -9,6 +9,7 @@ import { parseExactJson } from './exact-json.ts';
 import type { WebSocketUpgrade } from './serve-http.ts';
 import type { TwinStream } from './twin-fetch.ts';
 import { runWithRequestTrace } from './trace-context.ts';
+import { redisServiceTimes } from './redis/service-times.ts';
 
 /** The slice of a generated surface the dispatch reads. */
 export type DerivedOperation = {
@@ -285,7 +286,9 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
     if (!matched) return fallback(request, undefined, 'no operation at this path');
     for (const observer of dispatchObservers ?? []) observer({ surface: options.surface, operation: matched.operation, owner: handlers[matched.operation.id] ? 'handler' : options.core?.owns(matched.operation) ? 'core' : 'gap' });
     // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
+    redisServiceTimes.lap('6a around entered, guards and scenario passed, operation matched again');
     if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart')) tagBody(request, await request.clone().text());
+    redisServiceTimes.lap('6b the dispatch read the body as text');
     // the path prefix's named groups (pack-fetch.ts, `pathPrefix`) are the call's parameters too
     const prefixed = request.headers.get(PREFIX_PARAMS_HEADER);
     const call: DerivedCall = { request, operation: matched.operation, params: prefixed ? { ...(parseExactJson(prefixed) as Record<string, string>), ...matched.params } : matched.params };

package/src/fork.ts

@@ -76,7 +76,7 @@ export function forkTwin(opts: {
   };
   getActiveWorldStore().write(forkMetaPath(service, toRoot), `${JSON.stringify(meta, null, 2)}\n`);
   return meta;
-  });
+  }, { operation: 'pointer publication' });
 }
 
 export function readForkMeta(service: string, root: string): ForkMeta {

package/src/graphql-wire.ts

@@ -7,9 +7,9 @@
 // modeled; any other is answered by the manifest's `graphql.unmodeled`, naming the first field nothing models. An error
 // a resolver throws (`GraphqlError`) carries its `type`, as GitHub's GraphQL errors do.
 //
-// The `graphql` protocol library is loaded the first time a GraphQL request comes (installed by the pack's package.json,
-// as node-postgres is for the managed database): the kernel's own dependencies stay B1's, and importing the kernel
-// loads nothing.
+// The generated pack fetch supplies a lazy pack-local loader for the `graphql` protocol library installed by the pack's
+// package.json. Each endpoint caches its library on the first request; callers without a loader keep the kernel-relative
+// lazy import fallback. The kernel's own dependencies stay B1's, and importing the kernel loads nothing.
 
 /** A resolver of one field, `Type.field`: its parent object, its arguments, and the request's handler context. */
 export type GraphqlResolver<C = unknown> = (source: Record<string, unknown>, args: Record<string, unknown>, ctx: C) => unknown;
@@ -32,8 +32,7 @@ export class GraphqlError extends Error {
 }
 
 type GraphqlLib = typeof import('graphql');
-let lib: Promise<GraphqlLib> | undefined;
-const graphqlLib = (): Promise<GraphqlLib> => (lib ??= import('graphql') as Promise<GraphqlLib>);
+export type GraphqlLibraryLoader = () => Promise<GraphqlLib>;
 
 const snake = (s: string): string => s.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 
@@ -59,10 +58,14 @@ function connection(items: unknown[], args: Record<string, unknown>): Record<str
 export function graphqlEndpoint<C>(options: {
   sdl: string;
   part: GraphqlPart<C>;
+  /** The generated pack fetch's lazy import, resolving the library from the pack that declares it. */
+  loadLibrary?: GraphqlLibraryLoader;
   context: (request: Request) => Promise<C>;
   unmodeled: (field: { type: string; field: string }) => Response;
   mutationRefused?: (request: Request) => Response | undefined;
 }): (request: Request) => Promise<Response> {
+  let lib: Promise<GraphqlLib> | undefined;
+  const loadLibrary = options.loadLibrary ?? (() => import('graphql'));
   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
@@ -71,7 +74,7 @@ export function graphqlEndpoint<C>(options: {
   const modeled = (type: string, field: string): boolean =>
     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();
+    const g = await (lib ??= loadLibrary());
     schema ??= g.buildSchema(options.sdl, { assumeValidSDL: true });
     const payload = (await request.clone().json().catch(() => ({}))) as { query?: string; variables?: Record<string, unknown>; operationName?: string };
     let document: import('graphql').DocumentNode;

package/src/grpc-wire.ts

@@ -7,6 +7,7 @@ import { parseExactJson } from './exact-json.ts';
 // and what they answer is the pack's. Importing it does nothing.
 import { acceptH2Connection, type H2Handler } from './h2.ts';
 import { nodeBuiltin, WORLD_BOOT_PATH } from './serve-http.ts';
+import { worldBootAnswer } from './world-boot.ts';
 import { decodeMessage, encodeMessage, type ProtoSchema } from './protobuf.ts';
 
 /** gRPC's status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
@@ -151,7 +152,7 @@ export function grpcOverFetch(fetch: (request: Request) => Promise<Response>): G
 export async function serveGrpc(options: { port?: number; fetch: (request: Request) => Promise<Response>; schema: ProtoSchema }): Promise<{ port: number; stop: () => void }> {
   const net = nodeBuiltin<typeof import('node:net')>('node:net');
   const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
-  const fetch = worldBoot ? (request: Request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(Response.json({ boot: worldBoot })) : options.fetch(request)) : options.fetch;
+  const fetch = worldBoot ? (request: Request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(worldBootAnswer(worldBoot)) : options.fetch(request)) : options.fetch;
   const handler = grpcStreamHandler(options.schema, grpcOverFetch(fetch));
   const server = net.createServer((socket) => { acceptH2Connection(socket, handler, fetch); });
   await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => resolve()); });

package/src/h2.ts

@@ -25,6 +25,36 @@ const MAX_CONCURRENT_STREAMS = 1000;
 /** a request body larger than this resets its stream: a memory bound, not Temporal's message limit (the
  *  SDKs' gRPC default is 4 MiB; this server does not enforce that one) */
 const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+
+/** A chunked body (RFC 9112 §7.1) from `from`: its bytes once the last chunk and the trailer section have arrived,
+ *  'incomplete' before, 'bad' for a malformed size line or one past MAX_REQUEST_BYTES. Extensions and trailers are
+ *  read past and not kept. */
+function chunkedBody(buffer: Buffer, from: number): Uint8Array | 'incomplete' | 'bad' {
+  const parts: Buffer[] = [];
+  let at = from, total = 0;
+  for (;;) {
+    const line = buffer.indexOf('\r\n', at);
+    if (line < 0) return buffer.length - at > 4096 ? 'bad' : 'incomplete';
+    const size = /^([0-9A-Fa-f]{1,8})[ \t]*(?:;.*)?$/su.exec(buffer.subarray(at, line).toString('latin1'));
+    if (!size) return 'bad';
+    const length = parseInt(size[1]!, 16);
+    at = line + 2;
+    if (length === 0) break;
+    total += length;
+    if (total > MAX_REQUEST_BYTES) return 'bad';
+    if (buffer.length < at + length + 2) return 'incomplete';
+    if (buffer[at + length] !== 0x0d || buffer[at + length + 1] !== 0x0a) return 'bad';
+    parts.push(buffer.subarray(at, at + length));
+    at += length + 2;
+  }
+  // The trailer section: field lines up to an empty line.
+  for (;;) {
+    const line = buffer.indexOf('\r\n', at);
+    if (line < 0) return buffer.length - at > 64 * 1024 ? 'bad' : 'incomplete';
+    if (line === at) return Buffer.concat(parts);
+    at = line + 2;
+  }
+}
 /** a header block (HEADERS + CONTINUATION) larger than this closes the connection */
 const MAX_HEADER_BLOCK = 256 * 1024;
 
@@ -293,11 +323,22 @@ class H2Connection {
       this.respondHttp1(new Response('bad header', { status: 400 }));
       return;
     }
-    if (headers.get('transfer-encoding')) { this.respondHttp1(new Response('chunked request bodies are not accepted', { status: 411 })); return; }
-    const length = Number(headers.get('content-length') ?? 0);
-    if (!Number.isFinite(length) || length < 0 || length > MAX_REQUEST_BYTES) { this.respondHttp1(new Response('bad content-length', { status: 400 })); return; }
-    if (this.buffer.length < end + 4 + length) return;
-    const body = this.buffer.subarray(end + 4, end + 4 + length);
+    // A request with a Transfer-Encoding has a body framed by it, and its Content-Length is not read (RFC 9112 §6.3):
+    // undici sends a streamed body (a World's fetch forwarding a request's own body, duplex 'half') chunked.
+    const coding = headers.get('transfer-encoding');
+    let body: Uint8Array;
+    if (coding !== null) {
+      if (coding.split(',').map((each) => each.trim().toLowerCase()).at(-1) !== 'chunked') { this.respondHttp1(new Response('a transfer coding other than chunked is not read', { status: 400 })); return; }
+      const read = chunkedBody(this.buffer, end + 4);
+      if (read === 'bad') { this.respondHttp1(new Response('bad chunked body', { status: 400 })); return; }
+      if (read === 'incomplete') return;
+      body = read;
+    } else {
+      const length = Number(headers.get('content-length') ?? 0);
+      if (!Number.isFinite(length) || length < 0 || length > MAX_REQUEST_BYTES) { this.respondHttp1(new Response('bad content-length', { status: 400 })); return; }
+      if (this.buffer.length < end + 4 + length) return;
+      body = this.buffer.subarray(end + 4, end + 4 + length);
+    }
     this.buffer = Buffer.alloc(0);
     this.socket.removeAllListeners('data');
     let request: Request;

package/src/head.ts

@@ -461,6 +461,15 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
  * `auto` is performed now. Returns the vendor's id when it minted one, so the answer carries it.
  * Raises `RefusedWriteError` / `VendorWriteError` for the pack to answer in the vendor's shape.
  */
+/** Whether `performAtHead` would perform an entry now (a twin whose root says `auto`, outside a pack fetch's deferred
+ *  group): a caller appending several writes at once appends them one at a time then, each performed before the next. */
+export function performsAtHeadNow(service: string, root?: string): boolean {
+  const request = currentCorrelationId();
+  if (request !== undefined && deferred.has(request)) return false;
+  const head = headOf(service, root);
+  return head.kind === 'real' && head.deploy === 'auto';
+}
+
 export async function performAtHead(service: string, action: Pick<TwinAction, 'id'>, root?: string): Promise<{ performed: boolean; externalId?: string; data?: unknown }> {
   // a pack fetch performs its request's entries as one group after the handler (performRequestGroup)
   const request = currentCorrelationId();

package/src/history.ts

@@ -91,14 +91,14 @@ export function saveHistoryView(directory: string, view: HistoryView): string {
     getActiveWorldStore().writeAtomic(file, JSON.stringify({ ...view, dependencies }));
     for (const dependency of dependencies) commitParentPin(dependency.directory, file);
     return id;
-  });
+  }, { operation: 'view pin publication' });
 }
 /** What an inherited history's content stands on, as file facts: every segment file the view names
  *  (and the view document itself) and each named directory's ancestry record (its generation). A read cache keyed by this sees an
  *  ancestor's retained history truncated, replaced or its directory re-created, which the full read
  *  refuses (`historyEntries`), instead of serving a tree folded from the history it replaced. */
-export function inheritedHistoryKey(service: string, root?: string): string {
-  const parent = readBranchMeta(service, root)?.parent;
+export function inheritedHistoryKey(service: string, root?: string, meta?: string | null): string {
+  const parent = readBranchMeta(service, root, meta)?.parent;
   if (!parent?.view) return '';
   const store = getActiveWorldStore();
   const fact = (path: string): string => { const st = store.stat(path); return st ? `${st.size}:${st.mtimeMs}` : '-'; };
@@ -136,7 +136,7 @@ export function captureHistory(service: string, root?: string): { view: string;
       if (entries.length) descriptor.segments.push({ directory, generation, file, start: 0, count: entries.length, digest: historyDigest(entries) });
     }
     return { view: saveHistoryView(directory, descriptor), position: historyLength(descriptor.layout), descriptor };
-  });
+  }, { operation: 'capture' });
 }
 export function originHead(service: string, root?: string): { view: string; remoteView: string } | null {
   const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
@@ -162,7 +162,7 @@ export function publishOriginHistory(service: string, root: string, remoteView:
     const view = saveHistoryView(directory, { version: 1, owner: { directory, generation }, layout, segments });
     store.writeAtomic(join(directory, 'origin-head.json'), JSON.stringify({ view, remoteView }));
     return { view, appended };
-  });
+  }, { operation: 'origin fetch' });
 }
 
 /** A changeset binds the complete inherited view, including this root's observations. */
@@ -171,7 +171,7 @@ export function captureParentHistory(service: string, root?: string): HistoryRef
     const head = captureHistory(service, root);
     const position = head.position - head.descriptor.layout.branch;
     return { view: saveHistoryView(worldPaths(service, root).dir, historyPrefix(head.descriptor, position)), position };
-  });
+  }, { operation: 'capture' });
 }
 /** Compare evaluated views, so removals, reordered rows and layout changes count as drift. */
 export function historyChanges(service: string, before: HistoryView, after: HistoryView): Entry[] {
@@ -222,7 +222,7 @@ export function historyAtInstant(service: string, instant: string, root?: string
     }
     const view = saveHistoryView(directory, { version: 1, owner: source.owner, layout, segments, ...(source.origin ? { origin: { ...source.origin, ...(keep.slice(0, source.origin.position).some(v => !v) ? { incomplete: true } : {}) } } : {}) });
     return { view, position: historyLength(layout) };
-  });
+  }, { operation: 'capture' });
 }
 
 /** Replace only the tracked origin layer; inherited local layers keep their exact projection order. */

package/src/index.ts

@@ -53,7 +53,7 @@ export { VendorUnreachableError } from './vendor-call.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts';
 
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
-export { serveHttp, serveStream, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
+export { serveHttp, serveStream, nodeBuiltin, StreamListenerUnavailable, 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
@@ -79,6 +79,8 @@ export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatemen
 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")
 export * as s3 from './s3/wire.ts';
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from './xml.ts';
 export * as clickhouse from './clickhouse/index.ts';
 export { sampleFromSchema } from './schema-sample.ts';
 export * as openaiWire from './openai-wire.ts';
@@ -91,6 +93,7 @@ export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4
 export * as redis from './redis/index.ts';
 export * as mysql from './mysql/index.ts';
 export * as live from './live/index.ts';
+export * as mongodb from './mongodb/index.ts';
 export * as git from './git/index.ts';
 
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
@@ -103,3 +106,5 @@ export { browserSessionToken, startBrowserSession, endBrowserSession } from './b
 
 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';
+
+export * as managedOriginalInputs from './managed-original-inputs.ts';