@runuai/host 0.9.150 → 0.9.152

package/lib/apple-one-off.ts

@@ -0,0 +1,277 @@
+/**
+ * A one-off container on the Apple runtime (ADR-106), and nothing of it left
+ * behind (#p2jdax).
+ *
+ * `container run --rm` removes only a container that started. A run the
+ * runtime refuses leaves a created-never-started container, and those wedge
+ * the runtime's apiserver: `run` and `delete` hang while `list` and
+ * `inspect` still answer, until the runtime's services are recycled, which
+ * restarts every Apple task (apple-runtime-recycle.ts). A client killed at
+ * its bound (no answer in time, output past its bound) can leave one too, or
+ * a container that goes on running what it was abandoned for. So every
+ * one-off container is named in the closed grammar the recycle's sweep
+ * deletes, with a random part no other run's name has, labelled as Uai's,
+ * and labelled with a token only its own run carries; and its run is
+ * settled after it ends:
+ *
+ * - absent (the runtime says it is not found): done;
+ * - its own (Uai's label and its run's token, on exactly that name):
+ *   deleted, then proven gone; deleted again if it is not; still there, it
+ *   is what wedges the runtime, so the runtime's remedy is asked for, and it
+ *   is proven gone after. Only the runtime's own activation restarts its
+ *   services (it recovers every task after); all other work, and every
+ *   watch, asks the runtime's owner for that activation instead
+ *   (askRuntimeOwnerOnce);
+ * - of that name but not its own: never touched (a name alone is no proof);
+ * - unobservable (the runtime does not answer): nothing is deleted or
+ *   recycled on a guess.
+ *
+ * Whatever is left unproven is watched a while longer, and so is the name of
+ * a run whose client never reported its end (its container can still be
+ * created after): each look that finds it its own settles it again, and the
+ * watch ends only once it is proven gone or removed, or its time is up.
+ */
+
+import { randomBytes } from "node:crypto";
+
+import { MAINTENANCE_CONTAINER_LABEL, type AppleRecycleOutcome } from "./apple-runtime-recycle";
+
+/** The label only one run's container carries: its token. */
+export const MAINTENANCE_TOKEN_LABEL = "com.uai.maintenance.token";
+
+/** One run of the Apple `container` CLI. */
+export interface AppleCliResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export type AppleCli = (args: string[], timeoutMs: number) => Promise<AppleCliResult>;
+
+export interface AppleOneOffDeps {
+  cli: AppleCli;
+  /** The runtime's remedy for a container of a run's own that will not go
+   *  (see the module comment). */
+  recycle: () => Promise<AppleRecycleOutcome>;
+  /** Tests only: how the watch waits. */
+  delay?: (ms: number) => Promise<void>;
+}
+
+/** One one-off container: its name, and the token only its run carries. */
+export interface AppleOneOff {
+  readonly name: string;
+  readonly token: string;
+}
+
+/** What a one-off container's name may name, within the recycle sweep's
+ *  grammar (MAINTENANCE_CONTAINER_NAME_RE). */
+const PURPOSE = /^[a-z]+(?:-[a-z]+)*$/;
+const INSPECT_TIMEOUT_MS = 15_000;
+const DELETE_TIMEOUT_MS = 30_000;
+const DELETE_ATTEMPTS = 2;
+/** A watched name is looked for again after each of these waits. */
+const WATCH_MS: readonly number[] = [5_000, 15_000, 60_000, 180_000, 600_000];
+
+let sequence = 0;
+
+/** A new one-off container: a name no other run has had, and its token. */
+export function newAppleOneOff(purpose: string): AppleOneOff {
+  if (!PURPOSE.test(purpose)) throw new Error(`a malformed one-off container purpose: ${purpose}`);
+  sequence += 1;
+  return {
+    name: `uai-maint-${purpose}-${process.pid}-${sequence}-${randomBytes(8).toString("hex")}`,
+    token: randomBytes(16).toString("hex"),
+  };
+}
+
+/** The `container run` arguments that name a one-off container, mark it
+ *  Uai's (what the recycle's sweep goes by) and give it its run's token
+ *  (what alone authorizes deleting it here). */
+export function appleOneOffRunArgs(oneOff: AppleOneOff): string[] {
+  return [
+    "--name",
+    oneOff.name,
+    "-l",
+    `${MAINTENANCE_CONTAINER_LABEL}=1`,
+    "-l",
+    `${MAINTENANCE_TOKEN_LABEL}=${oneOff.token}`,
+  ];
+}
+
+/** What one inspection of a one-off container's name finds. */
+export type AppleOneOffPresence = "ours" | "absent" | "foreign" | "unknown";
+
+/**
+ * One observation of `oneOff`'s name: absent only on the runtime's own "not
+ * found"; its own only with Uai's label and its run's token on exactly that
+ * container; of that name without them, foreign; anything else (no answer,
+ * an answer that does not parse), unknown.
+ */
+export async function appleOneOffPresence(cli: AppleCli, oneOff: AppleOneOff): Promise<AppleOneOffPresence> {
+  const { name } = oneOff;
+  const inspected = await cli(["inspect", name], INSPECT_TIMEOUT_MS);
+  if (inspected.code === 0) {
+    try {
+      const parsed = JSON.parse(inspected.stdout) as Array<{
+        id?: unknown;
+        configuration?: { labels?: Record<string, unknown> };
+      }>;
+      if (!Array.isArray(parsed) || parsed.length !== 1 || parsed[0]?.id !== name) return "unknown";
+      const labels = parsed[0]?.configuration?.labels;
+      return labels?.[MAINTENANCE_CONTAINER_LABEL] === "1" && labels?.[MAINTENANCE_TOKEN_LABEL] === oneOff.token
+        ? "ours"
+        : "foreign";
+    } catch {
+      return "unknown";
+    }
+  }
+  if (
+    inspected.code !== null &&
+    inspected.stdout.trim() === "" &&
+    inspected.stderr.split("\n").some((line) => line.trim() === `Error: container not found: ${name}`)
+  ) {
+    return "absent";
+  }
+  return "unknown";
+}
+
+/** How a one-off container's run was settled. */
+export type AppleOneOffSettlement =
+  /** Nothing of that name is there. */
+  | "absent"
+  /** Its own was there: deleted, and proven gone. */
+  | "removed"
+  /** Its own would not go: the runtime's remedy took it, and it is proven
+   *  gone. */
+  | "recycled"
+  /** Of that name but not its own: left untouched. */
+  | "foreign"
+  /** Neither proven gone nor removed. */
+  | "unproven";
+
+/**
+ * Settle `oneOff`'s container once (see the module comment). Never
+ * rejects.
+ */
+export async function settleAppleOneOff(deps: AppleOneOffDeps, oneOff: AppleOneOff): Promise<AppleOneOffSettlement> {
+  const { name } = oneOff;
+  try {
+    let presence = await appleOneOffPresence(deps.cli, oneOff);
+    if (presence === "absent") return "absent";
+    // Only its own is ever deleted.
+    for (let attempt = 0; attempt < DELETE_ATTEMPTS && presence === "ours"; attempt += 1) {
+      await deps.cli(["delete", "--force", name], DELETE_TIMEOUT_MS);
+      presence = await appleOneOffPresence(deps.cli, oneOff);
+    }
+    if (presence === "absent") return "removed";
+    if (presence !== "ours") return leftAlone(name, presence);
+    // Its own, and it will not go: what wedges the runtime.
+    console.warn(`[host-agent] one-off container ${name} could not be deleted; asking for the Apple runtime's remedy`);
+    const outcome = await deps.recycle();
+    presence = await appleOneOffPresence(deps.cli, oneOff);
+    if (presence === "absent") return "recycled";
+    console.warn(
+      `[host-agent] one-off container ${name} is still there (${
+        outcome.recycled ? "the runtime's services were recycled" : outcome.reason
+      }); it is watched, and removed once it can be`,
+    );
+    return "unproven";
+  } catch (error) {
+    console.warn(
+      `[host-agent] one-off container ${name} could not be settled: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return "unproven";
+  }
+}
+
+function leftAlone(name: string, presence: "foreign" | "unknown"): AppleOneOffSettlement {
+  if (presence === "foreign") {
+    console.warn(`[host-agent] a container named ${name} is not this run's own; leaving it untouched`);
+    return "foreign";
+  }
+  console.warn(`[host-agent] could not observe one-off container ${name}; nothing is deleted or recycled on a guess`);
+  return "unproven";
+}
+
+/**
+ * The runtime's remedy for work outside its activation: ask the runtime's
+ * owner, at most once for one run, to recheck the runtime
+ * (container-runtime.ts requestContainerRuntimeRecheck). Its activation
+ * restarts the services of a runtime it finds wedged, then recovers every
+ * task; this never restarts them itself.
+ */
+export function askRuntimeOwnerOnce(
+  recheck: (reason: string) => boolean,
+  reason: string,
+): () => Promise<Extract<AppleRecycleOutcome, { recycled: false }>> {
+  let asked: boolean | null = null;
+  return async () => {
+    asked ??= recheck(reason);
+    return {
+      recycled: false,
+      reason: asked ? "its owner was asked to recheck the runtime" : "no owner of the runtime was there to ask",
+    };
+  };
+}
+
+/**
+ * Whether a run's settlement leaves its name to watch: anything unproven,
+ * and, when its client never reported its end (`lateCreation`: its
+ * container can still be created after), anything short of removed.
+ */
+export function appleOneOffNeedsWatch(settled: AppleOneOffSettlement, lateCreation: boolean): boolean {
+  if (settled === "removed" || settled === "recycled") return false;
+  return settled === "unproven" || lateCreation;
+}
+
+/**
+ * Watch `oneOff`'s name: look for it again after each wait, and settle it
+ * whenever it is found its own; one that cannot be observed, or is not its
+ * own (when `lateCreation`, the name may be its own's later), is looked for
+ * again. Resolves once it is removed or proven gone (absent ends the watch
+ * only where nothing of the run can be created after), or the watch's time
+ * is up; never rejects.
+ */
+export async function watchAppleOneOff(
+  deps: AppleOneOffDeps,
+  oneOff: AppleOneOff,
+  options: { lateCreation: boolean },
+): Promise<AppleOneOffSettlement> {
+  const delay = deps.delay ?? defaultDelay;
+  let last: AppleOneOffSettlement = "unproven";
+  for (const wait of WATCH_MS) {
+    await delay(wait);
+    let presence: AppleOneOffPresence;
+    try {
+      presence = await appleOneOffPresence(deps.cli, oneOff);
+    } catch {
+      presence = "unknown";
+    }
+    if (presence === "absent" || presence === "foreign") {
+      if (!options.lateCreation) return presence;
+      last = presence;
+      continue;
+    }
+    if (presence === "unknown") {
+      last = "unproven";
+      continue;
+    }
+    const settled = await settleAppleOneOff(deps, oneOff);
+    if (settled === "removed" || settled === "recycled") return settled;
+    if (settled !== "unproven" && !options.lateCreation) return settled;
+    last = settled;
+  }
+  return last;
+}
+
+function defaultDelay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+/** Tests only: the name sequence, from the start. */
+export function resetAppleOneOffNamesForTests(): void {
+  sequence = 0;
+}

package/lib/apple-runtime-recycle.ts

@@ -103,9 +103,10 @@ export function parseAppleContainerServiceLabels(listing: string): string[] {
  * requires the label AND the closed generated grammar together. */
 export const MAINTENANCE_CONTAINER_LABEL = "com.uai.maintenance";
 
-/** The closed grammar `runMaintenanceContainer` generates:
- * uai-maint-<purpose>-<pid>-<seq>. */
-export const MAINTENANCE_CONTAINER_NAME_RE = /^uai-maint-[a-z-]+-\d+-\d+$/;
+/** The closed grammar one-off containers are named in (apple-one-off.ts):
+ * uai-maint-<purpose>-<pid>-<seq>-<16 random hex>; the random part is
+ * absent from the names of a runner that predates it. */
+export const MAINTENANCE_CONTAINER_NAME_RE = /^uai-maint-[a-z-]+-\d+-\d+(?:-[0-9a-f]{16})?$/;
 
 /**
  * The sweep deletes ONLY containers Uai provably owns: the exact generated

package/lib/attachments.ts

@@ -6,10 +6,11 @@
  * never get committed. The cloud relays bytes in/out; it never persists them.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 
 import { taskWorkspaceDir } from "./env";
+import { makeContainedDirectories, readBoundedFile, writeContainedFile } from "./task-environment/workspace-files";
 
 /** Host directory holding a task's attachments. */
 export function attachmentsDir(taskId: string): string {
@@ -21,26 +22,27 @@ export function containerAttachmentPath(filename: string): string {
   return `/workspace/.uai/attachments/${basename(filename)}`;
 }
 
-/** Resolve + harden a filename to a path inside the task's attachments dir. */
-function safePath(taskId: string, filename: string): string {
-  const dir = attachmentsDir(taskId);
-  const full = resolve(dir, basename(filename));
-  if (full !== dir && !full.startsWith(dir + "/")) {
+/** An attachment's file name, as it lands in the attachments directory. */
+function attachmentName(filename: string): string {
+  const name = basename(filename);
+  if (name === "" || name === "." || name === ".." || name.includes("\0")) {
     throw new Error("invalid attachment filename");
   }
-  return full;
+  return name;
 }
 
-export function writeAttachment(
-  taskId: string,
-  filename: string,
-  bytes: Buffer,
-): void {
-  mkdirSync(attachmentsDir(taskId), { recursive: true });
-  writeFileSync(safePath(taskId, filename), bytes);
+/** Written inside the task's workspace, never through a link a task put
+ *  there (#cb3j0z). */
+export async function writeAttachment(taskId: string, filename: string, bytes: Buffer): Promise<void> {
+  const name = attachmentName(filename);
+  // The workspace root is the runner's own path; below it, the task's.
+  await mkdir(taskWorkspaceDir(taskId), { recursive: true });
+  await makeContainedDirectories(taskWorkspaceDir(taskId), [".uai", "attachments"]);
+  await writeContainedFile(taskWorkspaceDir(taskId), [".uai", "attachments", name], bytes);
 }
 
-export function readAttachment(taskId: string, filename: string): Buffer | null {
-  const full = safePath(taskId, filename);
-  return existsSync(full) ? readFileSync(full) : null;
+/** Read the same way: a regular file inside the workspace, or null. */
+export async function readAttachment(taskId: string, filename: string): Promise<Buffer | null> {
+  const bytes = await readBoundedFile(taskWorkspaceDir(taskId), [".uai", "attachments", attachmentName(filename)]);
+  return bytes === null ? null : Buffer.from(bytes);
 }

package/lib/capture-flow.ts

@@ -0,0 +1,319 @@
+/**
+ * ADR-154 §3 on the sign-in box: write one capture as one immutable revision,
+ * exactly where the cloud's flow says, and never read it back.
+ *
+ * The cloud begins every capture (lib/credential-metadata.ts) and hands the
+ * box the revision's parameter names. The box checks them, builds the two
+ * parts from what the sign-in produced, and creates them, broker-only part
+ * first:
+ *
+ *  - lease-readable: what a task may receive: a static key as entered, or an
+ *    OAuth login's brokered copy (access token in, refresh token replaced);
+ *  - broker-only (OAuth logins only): the full material, which only the
+ *    broker reads and only the broker ever overwrites.
+ *
+ * Both are created, never overwritten (`putImmutable`), with tags naming the
+ * workspace and person the role policy checks. The answer carries names and
+ * versions, never material.
+ */
+import {
+  ENGINE_CREDENTIAL_FILES,
+  ENGINE_ENV_CREDENTIAL_KEYS,
+  MAX_CREDENTIAL_VALUE_BYTES,
+  parseCaptureFlowWire,
+  serializeLeasedValue,
+  type CaptureFlowWire,
+  type CaptureResultWire,
+  type CredentialLocation,
+} from "../src/cloud-credentials";
+import { ImmutableParameterAbortedError, storeFailureKind, type CredentialStore } from "./credential-store";
+import { laneFor } from "./token-lanes/registry";
+import {
+  emptyRefreshMeta,
+  refreshMetaFrom,
+  type CredentialFiles,
+  type RefreshMeta,
+} from "./token-lanes/types";
+
+/** What only the broker reads: the full material of an OAuth login. */
+export interface BrokerEngineValue {
+  v: 1;
+  part: "broker";
+  location: CredentialLocation;
+  class: "engine";
+  lane: string;
+  files: CredentialFiles;
+  refresh: RefreshMeta;
+}
+
+export type EngineCaptureMaterial =
+  | { authKind: "env"; env: Record<string, string> }
+  | { authKind: "config-dir"; files: CredentialFiles };
+
+export interface BuiltCapture {
+  lease: string;
+  broker: string | null;
+  expiresAt: number | null;
+  /** Metadata the lease part also carries (never material): an SSH key's
+   *  public half, so a retry can tell which key the revision holds. The
+   *  identity tags always win over these. */
+  leaseTags?: Record<string, string>;
+}
+
+export type ParsedCaptureFlow = CaptureFlowWire & { location: CredentialLocation };
+
+export function parseCaptureFlow(value: unknown): ParsedCaptureFlow | null {
+  return parseCaptureFlowWire(value);
+}
+
+function onlyKeys(record: Record<string, string>, allowed: readonly string[]): boolean {
+  const keys = Object.keys(record);
+  return keys.length > 0 && keys.every((key) => allowed.includes(key));
+}
+
+/**
+ * The two parts of an AI account's capture, or an error the sign-in shows.
+ * The flow's broker part must exist exactly when the material rotates: a
+ * rotating login without one would leave its refresh token nowhere the
+ * broker can reach (and a task holding it would refresh it itself), and a
+ * static key needs none.
+ */
+export function buildEngineCapture(
+  flow: ParsedCaptureFlow,
+  material: EngineCaptureMaterial,
+): BuiltCapture | { error: string } {
+  const { location } = flow;
+  if (location.class !== "engine") {
+    return { error: "This capture is not an AI account." };
+  }
+  const kind = location.engineKind!;
+  if (material.authKind === "env") {
+    if (!onlyKeys(material.env, ENGINE_ENV_CREDENTIAL_KEYS[kind] ?? [])) {
+      return { error: "This key is not one the engine reads." };
+    }
+    if (flow.brokerParameter !== null) {
+      return { error: "A pasted key does not rotate; it has no broker part." };
+    }
+    return {
+      lease: serializeLeasedValue({
+        v: 1,
+        part: "lease",
+        location,
+        class: "engine",
+        authKind: "env",
+        env: { ...material.env },
+      }),
+      broker: null,
+      expiresAt: null,
+    };
+  }
+  if (!onlyKeys(material.files, ENGINE_CREDENTIAL_FILES[kind] ?? [])) {
+    return { error: "The sign-in produced files the engine does not use." };
+  }
+  const lane = laneFor(
+    { kind, authKind: "config-dir", id: location.credentialId!, scope: location.scope },
+    material.files,
+  );
+  if (lane === null) {
+    if (flow.brokerParameter !== null) {
+      return { error: "This credential does not rotate; it has no broker part." };
+    }
+    return {
+      lease: serializeLeasedValue({
+        v: 1,
+        part: "lease",
+        location,
+        class: "engine",
+        authKind: "config-dir",
+        files: { ...material.files },
+        expiresAt: null,
+      }),
+      broker: null,
+      expiresAt: null,
+    };
+  }
+  if (flow.brokerParameter === null) {
+    return { error: "This sign-in rotates, and the cloud gave it nowhere to keep its refresh token." };
+  }
+  const expiresAt = lane.expiresAt(material.files);
+  const broker: BrokerEngineValue = {
+    v: 1,
+    part: "broker",
+    location,
+    class: "engine",
+    lane: lane.id,
+    files: { ...material.files },
+    refresh: { ...emptyRefreshMeta(lane.id), expiresAt },
+  };
+  return {
+    lease: serializeLeasedValue({
+      v: 1,
+      part: "lease",
+      location,
+      class: "engine",
+      authKind: "config-dir",
+      files: lane.brokeredCopy(material.files),
+      expiresAt,
+    }),
+    broker: JSON.stringify(broker),
+    expiresAt,
+  };
+}
+
+/** The tags every part carries: the identity a retry is checked against,
+ *  and the workspace and person the role policy compares. */
+export function captureTags(
+  flow: ParsedCaptureFlow,
+  part: "lease" | "broker",
+): Record<string, string> {
+  return {
+    ...(flow.orgId !== null ? { org: flow.orgId } : {}),
+    ...(flow.userId !== null ? { user: flow.userId } : {}),
+    uai_credential: flow.credentialId,
+    uai_revision: flow.revision,
+    uai_part: part,
+  };
+}
+
+/**
+ * Create both parts, broker-only first: a crash after it leaves a revision
+ * the cloud never promotes, which the sweep removes; a lease-readable part
+ * never exists without the refresh token it was brokered from. A retry after
+ * a lost answer finds its own create by its tags and carries on.
+ */
+export async function writeCapture(
+  store: CredentialStore,
+  flow: ParsedCaptureFlow,
+  built: BuiltCapture,
+  options: { signal?: AbortSignal } = {},
+): Promise<CaptureResultWire> {
+  if (!store.putImmutable) {
+    throw new Error("This credential store cannot create immutable parameters.");
+  }
+  // A caller's deadline covers the writes too: past it nothing more is sent,
+  // and a part already sent is the cloud's to sweep with the revision.
+  const { signal } = options;
+  if (built.broker !== null) {
+    if (flow.brokerParameter === null) throw new Error("no broker part to write");
+    if (signal?.aborted) throw new ImmutableParameterAbortedError();
+    await store.putImmutable(flow.brokerParameter, built.broker, captureTags(flow, "broker"), { signal });
+  }
+  if (signal?.aborted) throw new ImmutableParameterAbortedError();
+  await store.putImmutable(
+    flow.leaseParameter,
+    built.lease,
+    { ...built.leaseTags, ...captureTags(flow, "lease") },
+    { signal },
+  );
+  return {
+    credentialId: flow.credentialId,
+    revision: flow.revision,
+    // Created, never overwritten by the box: version 1. Only the broker
+    // writes later versions.
+    leaseVersion: 1,
+    expiresAt: built.expiresAt,
+  };
+}
+
+export interface CaptureOutcome {
+  ok: boolean;
+  message: string;
+  /** Present exactly when `ok`. */
+  capture?: CaptureResultWire;
+}
+
+/**
+ * The sign-in box's sink for an AI account's capture: check the flow, build
+ * both parts, create them. Every failure is a message the sign-in shows, and
+ * none of them carries material.
+ */
+export async function captureEngineAccount(
+  store: CredentialStore | null,
+  wire: CaptureFlowWire,
+  engine: string,
+  material: EngineCaptureMaterial,
+  engineLabel: string,
+): Promise<CaptureOutcome> {
+  const flow = parseCaptureFlow(wire);
+  if (!flow || flow.location.class !== "engine" || flow.location.engineKind !== engine) {
+    return { ok: false, message: "The sign-in's destination is invalid; nothing was kept." };
+  }
+  if (!store) {
+    return { ok: false, message: "This runner has no credential store to hold the account." };
+  }
+  const built = buildEngineCapture(flow, material);
+  if ("error" in built) return { ok: false, message: built.error };
+  try {
+    const capture = await writeCapture(store, flow, built);
+    return { ok: true, message: `${engineLabel} signed in.`, capture };
+  } catch (err) {
+    // A category, never the error's words: a store failure can echo input.
+    console.warn(`[capture-flow] ${engine} ${flow.credentialId}/${flow.revision}: write failed (${storeFailureKind(err)})`);
+    return {
+      ok: false,
+      message: "The credential store refused the write; nothing was kept on this runner.",
+    };
+  }
+}
+
+
+/**
+ * A stored broker-only part, exactly, for the revision at `expected`; null
+ * for anything else. Only the broker reads it (token-broker-revision.ts).
+ */
+export function parseBrokerEngineValue(
+  raw: string,
+  expected: CredentialLocation,
+): BrokerEngineValue | null {
+  if (typeof raw !== "string" || new TextEncoder().encode(raw).length > MAX_CREDENTIAL_VALUE_BYTES) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const o = parsed as Record<string, unknown>;
+  const location = o.location as Record<string, unknown> | null;
+  if (
+    o.v !== 1 ||
+    o.part !== "broker" ||
+    o.class !== "engine" ||
+    expected.class !== "engine" ||
+    typeof o.lane !== "string" ||
+    !location ||
+    typeof location !== "object" ||
+    location.class !== expected.class ||
+    location.scope !== expected.scope ||
+    location.ownerId !== expected.ownerId ||
+    location.engineKind !== expected.engineKind ||
+    location.credentialId !== expected.credentialId ||
+    location.revision !== expected.revision
+  ) {
+    return null;
+  }
+  const allowed = ENGINE_CREDENTIAL_FILES[expected.engineKind ?? ""] ?? [];
+  const files = o.files as Record<string, unknown> | null;
+  if (
+    !files ||
+    typeof files !== "object" ||
+    Array.isArray(files) ||
+    Object.keys(files).length === 0 ||
+    !Object.entries(files).every(([name, text]) => allowed.includes(name) && typeof text === "string")
+  ) {
+    return null;
+  }
+  const refresh = refreshMetaFrom(o.refresh);
+  if (!refresh || refresh.lane !== o.lane) return null;
+  return {
+    v: 1,
+    part: "broker",
+    location: expected,
+    class: "engine",
+    lane: o.lane,
+    files: files as CredentialFiles,
+    refresh,
+  };
+}