akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/server/akanServer.ts

@@ -168,6 +168,8 @@ export class AkanServer {
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
   #di: DiLifecycle;
+  #openApiDocument: ReturnType<typeof createOpenApiDocument> | null = null;
+  readonly #initTimings = new Map<string, number>();
   #localPublish: LocalPublish | null = null;
   readonly #binaryPubsub = new BinaryPubsub();
   #metricsTimer: Timer | null = null;
@@ -324,7 +326,16 @@ export class AkanServer {
     };
   }
 
-  async init({ routes: initRoutes = true, web }: { routes?: boolean; web?: AkanWebOption } = {}) {
+  async init(option: { routes?: boolean; web?: AkanWebOption } = {}) {
+    const start = performance.now();
+    this.#initTimings.clear();
+    await this.#init(option);
+    const stages = [...this.#di.initTimings, ...this.#initTimings].map(([stage, ms]) => `${stage} ${ms.toFixed(1)}`);
+    this.logger.debug(`Initialized in ${(performance.now() - start).toFixed(1)}ms (${stages.join(" · ")})`);
+    return this;
+  }
+
+  async #init({ routes: initRoutes = true, web }: { routes?: boolean; web?: AkanWebOption }) {
     if (this.status !== "stopped") throw new Error("AkanServer is not able to init. It is already running.");
     this.status = "initializing";
     this.#assertPrefixClearsBasePaths();
@@ -340,7 +351,7 @@ export class AkanServer {
         routes,
         routeOptions,
         wsRoutes,
-        builtinRoutes: this.#createBuiltinRoutes(null),
+        builtinRoutes: this.#timedBuiltinRoutes(null),
         renderEnvRoutes: {},
         hmrHub: null,
         webRouter: null,
@@ -354,6 +365,7 @@ export class AkanServer {
       this.logger.debug("web off: serving api only (AKAN_SSR=false, or a build with `web: false`)");
       return noWeb();
     }
+    const webStart = performance.now();
     const { WebRouter } = await import("./webRouter");
     const webRouter = await WebRouter.create({
       web: requestedWeb,
@@ -368,12 +380,13 @@ export class AkanServer {
     this.web = webRouter.web;
     this.logger.verbose(`web on: ssr=${this.web.ssr} csr=${this.web.csr}`);
     const { renderEnvRoutes, hmrHub } = await webRouter.initializeRoute();
+    this.#initTimings.set("web", performance.now() - webStart);
     const webProxyRunner = WebProxyRunner.create(this.#di.webProxies);
     this.#prepared = {
       routes,
       routeOptions,
       wsRoutes,
-      builtinRoutes: this.#createBuiltinRoutes(webRouter),
+      builtinRoutes: this.#timedBuiltinRoutes(webRouter),
       renderEnvRoutes,
       hmrHub,
       webRouter,
@@ -666,21 +679,18 @@ export class AkanServer {
     }
   }
 
+  #timedBuiltinRoutes(webRouter: WebRouter | null): HttpRoutes {
+    const start = performance.now();
+    const builtinRoutes = this.#createBuiltinRoutes(webRouter);
+    this.#initTimings.set("builtinRoutes", performance.now() - start);
+    return builtinRoutes;
+  }
+
   #createBuiltinRoutes(webRouter: WebRouter | null): HttpRoutes {
     const { appName } = getEnv();
     const openapiRoutes: HttpRoutes = this.openapi
       ? {
-          "/openapi.json": {
-            GET: () =>
-              Response.json(
-                createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
-                  title: `${appName} API`,
-                  version: "0.0.0",
-                  servers: this.#getOpenApiServers(),
-                  resolveDescription: AkanServer.#createDescriptionResolver(),
-                }),
-              ),
-          },
+          "/openapi.json": { GET: () => Response.json(this.#getOpenApiDocument(appName)) },
         }
       : {};
     
@@ -802,6 +812,16 @@ export class AkanServer {
     this.#logForwarder = null;
   }
 
+  #getOpenApiDocument(appName: string) {
+    this.#openApiDocument ??= createOpenApiDocument(FetchSerializer.serializeRegistry(this.#di.live).signal, {
+      title: `${appName} API`,
+      version: "0.0.0",
+      servers: this.#getOpenApiServers(),
+      resolveDescription: AkanServer.#createDescriptionResolver(),
+    });
+    return this.#openApiDocument;
+  }
+
   static #createDescriptionResolver() {
     const lookup = new DictionaryLookup();
     return (key: string) => lookup.text(key);

package/server/artifact/routeClientCache.ts

@@ -105,13 +105,12 @@ export class RouteClientCache {
         continue;
       }
       const generation = this.merged.generation;
-      const promise = this.#runBuild(routeId, seeds, generation);
-      this.#building.set(routeId, { generation, promise });
+      const pending: PendingBuild = { generation, promise: this.#runBuild(routeId, seeds, generation) };
+      this.#building.set(routeId, pending);
       try {
-        await promise;
+        await pending.promise;
       } finally {
-        const current = this.#building.get(routeId);
-        if (current?.promise === promise) this.#building.delete(routeId);
+        if (this.#building.get(routeId) === pending) this.#building.delete(routeId);
         this.#prune();
       }
     }

package/server/artifact/routeSeedIndexStore.ts

@@ -1,6 +1,5 @@
 import path from "node:path";
-import { matchRoutePattern } from "akanjs/common";
-import { matchRoutePrefix } from "../../common/routeConvention";
+import { RouteSeedMatcher } from "./routeSeedMatcher";
 
 export interface RouteSeedEntry {
   routeId: string;
@@ -60,27 +59,11 @@ export class RouteSeedIndexStore {
   }
 
   static match(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null {
-    for (const entry of entries) {
-      const params = matchRoutePattern(entry.pattern ?? entry.routeId, pathname);
-      if (params) return { entry, params };
-    }
-    return null;
+    return RouteSeedMatcher.of(entries).match(pathname);
   }
 
   static matchPrefix(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null {
-    const candidates = entries
-      .map((entry) => ({
-        entry,
-        params: matchRoutePrefix(entry.pattern ?? entry.routeId, pathname),
-      }))
-      .filter((entry): entry is { entry: RouteSeedEntry; params: Record<string, string> } => Boolean(entry.params))
-      .sort((a, b) => {
-        const lengthDelta =
-          b.entry.pattern.split("/").filter(Boolean).length - a.entry.pattern.split("/").filter(Boolean).length;
-        if (lengthDelta !== 0) return lengthDelta;
-        return a.entry.pattern < b.entry.pattern ? -1 : a.entry.pattern > b.entry.pattern ? 1 : 0;
-      });
-    return candidates[0] ?? null;
+    return RouteSeedMatcher.of(entries).matchPrefix(pathname);
   }
 
   static #normalizeArtifactPath(artifactPath: string, artifactDir: string): string {

package/server/artifact/routeSeedMatcher.ts

@@ -0,0 +1,70 @@
+import type { MatchedRoute, RouteSeedEntry } from "./routeSeedIndexStore";
+
+interface CompiledEntry {
+  entry: RouteSeedEntry;
+  parts: string[];
+}
+
+export class RouteSeedMatcher {
+  static readonly #byEntries = new WeakMap<RouteSeedEntry[], RouteSeedMatcher>();
+
+  static of(entries: RouteSeedEntry[]): RouteSeedMatcher {
+    const cached = RouteSeedMatcher.#byEntries.get(entries);
+    if (cached && cached.#size === entries.length) return cached;
+    const matcher = new RouteSeedMatcher(entries);
+    RouteSeedMatcher.#byEntries.set(entries, matcher);
+    return matcher;
+  }
+
+  readonly #size: number;
+  readonly #inOrder: CompiledEntry[];
+  
+  readonly #bySpecificity: CompiledEntry[];
+
+  constructor(entries: RouteSeedEntry[]) {
+    this.#size = entries.length;
+    this.#inOrder = entries.map((entry) => ({ entry, parts: RouteSeedMatcher.#split(entry.pattern ?? entry.routeId) }));
+    this.#bySpecificity = [...this.#inOrder].sort((a, b) => {
+      const lengthDelta = b.parts.length - a.parts.length;
+      if (lengthDelta !== 0) return lengthDelta;
+      const aPattern = a.entry.pattern ?? a.entry.routeId;
+      const bPattern = b.entry.pattern ?? b.entry.routeId;
+      return aPattern < bPattern ? -1 : aPattern > bPattern ? 1 : 0;
+    });
+  }
+
+  static #split(text: string) {
+    return text.split("/").filter(Boolean);
+  }
+
+  static #paramsOf(parts: string[], pathParts: string[]): Record<string, string> | null {
+    const params: Record<string, string> = {};
+    for (let idx = 0; idx < parts.length; idx += 1) {
+      const part = parts[idx] as string;
+      const value = pathParts[idx] as string;
+      if (part.startsWith(":")) params[part.slice(1)] = decodeURIComponent(value);
+      else if (part !== value) return null;
+    }
+    return params;
+  }
+
+  match(pathname: string): MatchedRoute | null {
+    const pathParts = RouteSeedMatcher.#split(pathname);
+    for (const { entry, parts } of this.#inOrder) {
+      if (parts.length !== pathParts.length) continue;
+      const params = RouteSeedMatcher.#paramsOf(parts, pathParts);
+      if (params) return { entry, params };
+    }
+    return null;
+  }
+
+  matchPrefix(pathname: string): MatchedRoute | null {
+    const pathParts = RouteSeedMatcher.#split(pathname);
+    for (const { entry, parts } of this.#bySpecificity) {
+      if (parts.length > pathParts.length) continue;
+      const params = RouteSeedMatcher.#paramsOf(parts, pathParts);
+      if (params) return { entry, params };
+    }
+    return null;
+  }
+}

package/server/console.ts

@@ -21,7 +21,7 @@ export interface AkanConsoleOptions {
 /** `level=warn grep="payment failed" endpoint=mutation:*` → a query object the socket parses. */
 export const parseAkanConsoleQuery = (args: string): Record<string, string> => {
   const query: Record<string, string> = {};
-  for (const match of args.matchAll(/([A-Za-z]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g)) {
+  for (const match of args.matchAll(/(?<![A-Za-z])([A-Za-z]+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g)) {
     const [, key, doubleQuoted, singleQuoted, bare] = match;
     if (key) query[key] = doubleQuoted ?? singleQuoted ?? bare ?? "";
   }

package/server/di/diLifecycle.ts

@@ -68,6 +68,7 @@ export class DiLifecycle {
   readonly #middleware = new Map<string, MiddlewareCls>();
   readonly webProxies: WebProxyRegistration[] = [];
   readonly disabledModules = new Map<string, string>();
+  readonly initTimings = new Map<string, number>();
   readonly #predefinedAdaptor;
   readonly #cascade = new CascadeRunner();
 
@@ -401,21 +402,22 @@ export class DiLifecycle {
   }
 
   async #initializeAll(): Promise<SignalRoutes> {
-    await this.#initializeUses();
-    await this.#initializeAdaptor();
-    await this.#initializeServerSignal();
-    await this.#initializeService();
-    await this.#initializeInternal();
+    this.initTimings.clear();
+    await this.#initStage("uses", () => this.#initializeUses());
+    await this.#initStage("adaptors", () => this.#initializeAdaptor());
+    await this.#initStage("serverSignals", () => this.#initializeServerSignal());
+    await this.#initStage("services", () => this.#initializeService());
+    await this.#initStage("internals", () => this.#initializeInternal());
     const {
       routes: sliceRoutes,
       wsRoutes: sliceWsRoutes,
       routeOptions: sliceRouteOptions,
-    } = await this.#initializeSlice();
+    } = await this.#initStage("slices", () => this.#initializeSlice());
     const {
       routes: endpointRoutes,
       wsRoutes: endpointWsRoutes,
       routeOptions: endpointRouteOptions,
-    } = await this.#initializeEndpoint();
+    } = await this.#initStage("endpoints", () => this.#initializeEndpoint());
     const routes: SignalRoutes["routes"] = {};
     SignalResolver.mergeHttpRoutes(routes, sliceRoutes);
     SignalResolver.mergeHttpRoutes(routes, endpointRoutes);
@@ -442,6 +444,13 @@ export class DiLifecycle {
     await this.#timed("Destroying uses...", "Destroy uses", () => this.destroyUses());
   }
 
+  async #initStage<T>(stage: string, run: () => Promise<T>): Promise<T> {
+    const start = performance.now();
+    const result = await run();
+    this.initTimings.set(stage, performance.now() - start);
+    return result;
+  }
+
   async #timed(startMessage: string, doneLabel: string, run: () => Promise<unknown>) {
     const now = Date.now();
     this.logger.verbose(startMessage);

package/server/imageOptimizer.ts

@@ -294,7 +294,7 @@ export class ImageOptimizer {
 
   async #getOptimizedImage(source: ImageSource, params: ParsedImageRequest): Promise<OptimizedImage> {
     const inputType = ImageOptimizer.#detectContentType(source.buffer) || source.contentType;
-    if (!inputType || !inputType.startsWith("image/") || inputType.includes(",")) {
+    if (!inputType.startsWith("image/") || inputType.includes(",")) {
       throw new ImageOptimizerError(400, "The requested resource is not a valid image");
     }
     if (inputType === ImageOptimizer.#svg && !this.#config.dangerouslyAllowSVG) {

package/server/index.ts

@@ -8,6 +8,7 @@ export * from "./decorators";
 export * from "./devtools";
 export type { ChangeBatch, ChangeKind } from "./hmr/wsHub";
 export * from "./machine";
+export * from "./migration";
 export * from "./nativeFile";
 export * from "./oauth";
 export * from "./processMetricsCollector";

package/server/machine/machineAccount.ts

@@ -1,6 +1,12 @@
 import { getEnv } from "akanjs/base";
-import type { Middleware, SignalContext } from "akanjs/signal";
-import { MachineToken } from "./machineToken";
+import type { MachineIdentity, Middleware, SignalContext } from "akanjs/signal";
+import { type MachineProof, MachineToken } from "./machineToken";
+
+interface VerifiedMachine {
+  authorization: string | null;
+  epoch: number;
+  proof: MachineProof | null;
+}
 
 interface AccountHolder {
   headers?: Headers;
@@ -10,12 +16,18 @@ interface AccountHolder {
 export class MachineAccount implements Middleware {
   static readonly refName = "MachineAccount";
 
+  static readonly #verifiedBySocket = new WeakMap<object, VerifiedMachine>();
+
   use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
       const holder = (
         context.transport === "http" ? context.getHttpContext().req : context.getWebSocketContext().ws.data
       ) as AccountHolder;
-      const machine = MachineToken.fromAuthorization(holder.headers?.get("authorization"));
+      const authorization = holder.headers?.get("authorization") ?? null;
+      const machine =
+        context.transport === "websocket"
+          ? MachineAccount.#verifiedOnSocket(holder, authorization)
+          : MachineToken.fromAuthorization(authorization);
       const { machine: _unverified, ...account } = holder.account ?? {};
       if (machine) {
         const { appName, environment } = getEnv();
@@ -24,4 +36,17 @@ export class MachineAccount implements Middleware {
       return await next();
     };
   }
+
+  static #verifiedOnSocket(socket: object, authorization: string | null): MachineIdentity | null {
+    const epoch = MachineToken.keyEpoch();
+    const verified = MachineAccount.#verifiedBySocket.get(socket);
+    const reusable =
+      verified?.authorization === authorization &&
+      verified.epoch === epoch &&
+      (verified.proof?.expiresAt === undefined || verified.proof.expiresAt > Date.now() / 1000);
+    if (verified && reusable) return verified.proof?.identity ?? null;
+    const proof = MachineToken.proofOf(authorization);
+    MachineAccount.#verifiedBySocket.set(socket, { authorization, epoch, proof });
+    return proof?.identity ?? null;
+  }
 }

package/server/machine/machineToken.ts

@@ -12,7 +12,15 @@ export interface MachineTokenIssueOptions {
   audience?: string;
 }
 
-export type MachineTokenVerdict = { ok: true; identity: MachineIdentity } | { ok: false; reason: string };
+export type MachineTokenVerdict =
+  | { ok: true; identity: MachineIdentity; expiresAt?: number }
+  | { ok: false; reason: string };
+
+/** What a bearer machine token proves, and the second it lapses at when it was issued with an expiry. */
+export interface MachineProof {
+  identity: MachineIdentity;
+  expiresAt?: number;
+}
 
 interface KeyPair {
   privateKey: KeyObject | null;
@@ -23,6 +31,7 @@ export class MachineToken {
   static readonly type = "akan-machine+jwt";
   static readonly #logger = new Logger("MachineToken");
   static #keys: { source: string; pair: KeyPair } | null = null;
+  static #keyEpoch = 0;
   static #warnedKeyless = false;
 
   static audience() {
@@ -43,9 +52,16 @@ export class MachineToken {
         : null;
     const pair = { privateKey, publicKey };
     MachineToken.#keys = { source, pair };
+    MachineToken.#keyEpoch += 1;
     return pair;
   }
 
+  /** Moves whenever the keys read from the env change, so a verdict kept from before is known to be stale. */
+  static keyEpoch() {
+    MachineToken.#keyPair();
+    return MachineToken.#keyEpoch;
+  }
+
   static canIssue() {
     return !!MachineToken.#keyPair().privateKey;
   }
@@ -86,15 +102,23 @@ export class MachineToken {
     if (exp !== undefined && (typeof exp !== "number" || exp <= nowSec)) return { ok: false, reason: "expired" };
     const identity = { kind, id: sub, version: ver } as MachineIdentity;
     if (!MachineToken.#isIdentity(identity)) return { ok: false, reason: "sub, kind and ver are required" };
-    return { ok: true, identity: { kind: identity.kind, id: identity.id, version: identity.version } };
+    return {
+      ok: true,
+      identity: { kind: identity.kind, id: identity.id, version: identity.version },
+      ...(exp !== undefined ? { expiresAt: exp as number } : {}),
+    };
   }
 
   /** The identity a bearer machine token proves, or `null`: absent, another kind of token, or one that fails. */
   static fromAuthorization(authorization: string | null | undefined): MachineIdentity | null {
+    return MachineToken.proofOf(authorization)?.identity ?? null;
+  }
+
+  static proofOf(authorization: string | null | undefined): MachineProof | null {
     const token = bearerTokenOf(authorization);
     if (!token || !MachineToken.isMachineToken(token)) return null;
     const verdict = MachineToken.verify(token);
-    if (verdict.ok) return verdict.identity;
+    if (verdict.ok) return verdict.expiresAt === undefined ? { identity: verdict.identity } : verdict;
     if (!MachineToken.canVerify() && !MachineToken.#warnedKeyless) {
       MachineToken.#warnedKeyless = true;
       MachineToken.#logger.error(

package/server/mcp/McpDispatcher.ts

@@ -72,7 +72,7 @@ export class McpDispatcher {
   }
 
   static #restorable(error: unknown, status: number | undefined) {
-    if (!status || status >= 500 || status === 401 || status === 403 || error instanceof NoDocumentError) return null;
+    if (!status || status >= 500 || status === 401 || status === 403) return null;
     return isExceptionLike(error) ? error.toJSON() : null;
   }
 
@@ -169,8 +169,7 @@ export class McpDispatcher {
   }
 
   static #statusOf(error: unknown): number | undefined {
-    if (isExceptionLike(error) || error instanceof McpArgumentError || error instanceof NoDocumentError)
-      return error.statusCode;
+    if (isExceptionLike(error) || error instanceof McpArgumentError) return error.statusCode;
     return undefined;
   }
 

package/server/mcp/McpExecutionContext.ts

@@ -1,6 +1,6 @@
 import { type Cls, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
 import { isMcpDescribableArg } from "akanjs/common";
-import { deserialize, serialize } from "akanjs/constant";
+import { InputParser, InvalidInputError, serialize } from "akanjs/constant";
 import type { EndpointInfo } from "../../signal/endpointInfo";
 import { HttpExecutionContext } from "../../signal/signalContext";
 
@@ -28,13 +28,15 @@ export class McpExecutionContext extends HttpExecutionContext {
 
   override parseArg(arg: McpArg, value: unknown): unknown {
     try {
-      return deserialize(arg.argRef, arg.arrDepth, value, {
+      return InputParser.parse(arg.argRef, arg.arrDepth, value, {
         key: arg.name,
         nullable: arg.option?.nullable,
         enum: arg.enum,
       });
-    } catch {
+    } catch (error) {
       
+      if (error instanceof InvalidInputError && error.path !== arg.name)
+        throw new McpArgumentError(McpExecutionContext.#fieldMessage(error));
       throw new McpArgumentError(McpExecutionContext.#argumentMessage(arg, value));
     }
   }
@@ -58,6 +60,10 @@ export class McpExecutionContext extends HttpExecutionContext {
     return isMcpDescribableArg({ refName });
   }
 
+  static #fieldMessage({ path, expected }: InvalidInputError) {
+    return expected ? `Invalid field "${path}": expected ${expected}.` : `Missing required field "${path}".`;
+  }
+
   static #argumentMessage(arg: McpArg, value: unknown) {
     if (value === null) return `Missing required argument "${arg.name}".`;
     if (arg.enum) return `Invalid argument "${arg.name}": expected one of ${arg.enum.values.join(", ")}.`;

package/server/migration/docPath.ts

@@ -0,0 +1,121 @@
+import { sanitizeJson } from "akanjs/document";
+import { stableJson } from "akanjs/service";
+
+/** What a path holds: `[value]`, or `[]` when it holds nothing — a stored `null` is a value. */
+export type DocSlot = [unknown] | [];
+
+/** Dot paths over a parsed `_doc`; a numeric segment indexes an array. */
+export class DocPath {
+  static readonly #unsafe = new Set(["__proto__", "constructor", "prototype"]);
+  
+  static readonly #index = /^(0|[1-9]\d*)$/;
+
+  static segments(path: string) {
+    const segments = path.split(".");
+    if (segments.some((segment) => !segment || DocPath.#unsafe.has(segment)))
+      throw new Error(`Invalid document path "${path}"`);
+    return segments;
+  }
+
+  static read(doc: Record<string, unknown>, path: string): DocSlot {
+    let node: unknown = doc;
+    for (const segment of DocPath.segments(path)) {
+      if (!node || typeof node !== "object" || !DocPath.#holds(node, segment)) return [];
+      node = (node as Record<string, unknown>)[segment];
+    }
+    return [node];
+  }
+
+  /** Whether every container above `path` is still there, so that writing it would change nothing else. */
+  static hasParent(doc: Record<string, unknown>, path: string) {
+    const segments = DocPath.segments(path);
+    let node: unknown = doc;
+    for (const segment of segments.slice(0, -1)) {
+      if (!node || typeof node !== "object" || !DocPath.#holds(node, segment)) return false;
+      node = (node as Record<string, unknown>)[segment];
+    }
+    return !!node && typeof node === "object";
+  }
+
+  /**
+   * The paths a write of `paths` changes as whole values: each path, or the nearest one above it that the write
+   * creates, replaces a `null` at, or appends to as an array, so the logged slot holds everything to put back.
+   */
+  static anchors(doc: Record<string, unknown>, paths: string[]) {
+    const anchors = [...new Set(paths.map((path) => DocPath.#anchor(doc, path)))];
+    return anchors.filter((anchor) => !anchors.some((other) => anchor.startsWith(`${other}.`)));
+  }
+
+  static #anchor(doc: Record<string, unknown>, path: string) {
+    const segments = DocPath.segments(path);
+    let node: unknown = doc;
+    for (const [idx, segment] of segments.entries()) {
+      if (Array.isArray(node) && !DocPath.#holds(node, segment)) return segments.slice(0, idx).join(".");
+      if (idx === segments.length - 1) break;
+      const next = DocPath.#holds(node as object, segment) ? (node as Record<string, unknown>)[segment] : undefined;
+      if (!next || typeof next !== "object") return segments.slice(0, idx + 1).join(".");
+      node = next;
+    }
+    return path;
+  }
+
+  static #holds(node: object, segment: string) {
+    if (!Array.isArray(node)) return Object.hasOwn(node, segment);
+    return DocPath.#index.test(segment) && Number(segment) < node.length;
+  }
+
+  static write(doc: Record<string, unknown>, path: string, value: unknown) {
+    const segments = DocPath.segments(path);
+    let node: Record<string, unknown> | unknown[] = doc;
+    for (const segment of segments.slice(0, -1)) {
+      const next = DocPath.#holds(node, segment) ? (node as Record<string, unknown>)[segment] : undefined;
+      if (next && typeof next === "object") {
+        node = next as Record<string, unknown>;
+        continue;
+      }
+      if (next !== undefined && next !== null)
+        throw new Error(`Cannot write "${path}": "${segment}" holds a ${typeof next}, not an object`);
+      const created: Record<string, unknown> = {};
+      DocPath.#assign(node, segment, created, path);
+      node = created;
+    }
+    DocPath.#assign(node, segments[segments.length - 1] ?? "", sanitizeJson(value) ?? null, path);
+  }
+
+  static remove(doc: Record<string, unknown>, path: string) {
+    const segments = DocPath.segments(path);
+    let node: unknown = doc;
+    for (const segment of segments.slice(0, -1)) {
+      if (!node || typeof node !== "object" || !DocPath.#holds(node, segment)) return;
+      node = (node as Record<string, unknown>)[segment];
+    }
+    if (!node || typeof node !== "object") return;
+    
+    if (Array.isArray(node)) throw new Error(`Cannot unset "${path}" inside an array; set the whole array instead`);
+    delete (node as Record<string, unknown>)[segments[segments.length - 1] ?? ""];
+  }
+
+  static same(a: DocSlot, b: DocSlot) {
+    if (a.length !== b.length) return false;
+    return !a.length || stableJson(a[0]) === stableJson(b[0]);
+  }
+
+  /** Two paths of one write where one sits inside the other would log a value the other already changed. */
+  static assertDisjoint(paths: string[]) {
+    for (const path of paths) {
+      const inner = paths.find((other) => other.startsWith(`${path}.`));
+      if (inner) throw new Error(`"${path}" and "${inner}" overlap; write them in separate calls`);
+    }
+  }
+
+  static #assign(node: Record<string, unknown> | unknown[], segment: string, value: unknown, path: string) {
+    if (!Array.isArray(node)) {
+      node[segment] = value;
+      return;
+    }
+    const idx = DocPath.#index.test(segment) ? Number(segment) : -1;
+    if (idx < 0 || idx > node.length)
+      throw new Error(`Cannot write "${path}": "${segment}" is not an index within the array`);
+    node[idx] = value;
+  }
+}

package/server/migration/index.ts

@@ -0,0 +1,15 @@
+export * from "./docPath";
+export * from "./migrationChangeLog";
+export * from "./migrationChanges";
+export * from "./migrationCommand";
+export * from "./migrationContext";
+export * from "./migrationDefinition";
+export * from "./migrationError";
+export * from "./migrationLedger";
+export * from "./migrationLock";
+export * from "./migrationParams";
+export * from "./migrationPulse";
+export * from "./migrationRunner";
+export * from "./migrationScope";
+export * from "./migrations";
+export * from "./migrationTable";