@almadar/shell-runtime 0.0.0-stage → 1.0.0

package/dist/chunk-7WB6VWRK.js

@@ -0,0 +1,798 @@
+import { isProgramEffect } from './chunk-WGCWJOT2.js';
+import { systemRandom, base64Standard } from './chunk-ZUSM4VW4.js';
+import { OnDeviceModelFailure, promptOnDevice, embedOnDevice } from './chunk-FWA5K7Q2.js';
+import { untilAborted } from './chunk-MZKIL5IN.js';
+import { isJsonObject, WriteDeclinedError, QueryDeclinedError, TabHostFailure, RowSetRefSchema, toPayloadValue, credentialStatusConnected } from '@almadar/core';
+
+function callerViewer(caller) {
+  return caller === void 0 ? void 0 : { id: caller.principal, ...caller.role !== void 0 ? { role: caller.role } : {} };
+}
+function issuePayload(issue) {
+  const payload = { code: issue.code, message: issue.message };
+  if (issue.path !== void 0) payload.path = issue.path;
+  if (issue.line !== void 0) payload.line = issue.line;
+  if (issue.column !== void 0) payload.column = issue.column;
+  return payload;
+}
+var HostAskError = class extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+  }
+  kind;
+};
+function programDocumentJson(document) {
+  return typeof document === "string" ? document : toPayloadValue(document);
+}
+function kernelEventRequestParser(kernel) {
+  return (payload, options) => {
+    try {
+      return { ok: kernel.parseEventRequest(JSON.stringify(payload), JSON.stringify(options)) };
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+}
+async function settle(work) {
+  try {
+    return { ok: await work() };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function serviceParams(args) {
+  if (args === null) return void 0;
+  if (!isJsonObject(args)) throw new Error("call-service: the arguments are not an object");
+  return args;
+}
+function failureMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function callService(ports, request, scope) {
+  const { service, method, args, key, caller, site } = request;
+  const identity = caller !== void 0 ? { principal: caller.principal, ...caller.role !== void 0 ? { role: caller.role } : {} } : {};
+  const orbital = site?.orbital ?? scope.orbital;
+  const onMessage = site?.emit.onMessage;
+  const message = (payload) => {
+    if (site === void 0 || onMessage === void 0) return;
+    ports.deliverLive({ orbital, trait: site.trait, event: onMessage }, payload, scope.originClientId);
+  };
+  const call = async (signal, outsideRequest) => {
+    const host = site !== void 0 ? ports.servicePorts({ orbital, trait: site.trait }, callerViewer(caller), message, outsideRequest === true ? void 0 : scope.assertReentry) : void 0;
+    const context = caller !== void 0 || signal !== void 0 || host !== void 0 || outsideRequest !== void 0 ? { ...identity, ...host !== void 0 ? { host } : {}, ...signal !== void 0 ? { signal } : {}, ...outsideRequest !== void 0 ? { outsideRequest } : {} } : void 0;
+    const result = await ports.callService(service, method, serviceParams(args), context);
+    return result;
+  };
+  const deferred = site?.followOn === true ? ports.deferCallOutcome() : void 0;
+  if (site !== void 0 && deferred !== void 0) {
+    startDeferredCall(deferred, site, key, call, { ports, orbital, scope });
+    return { kind: "serviceDeferred" };
+  }
+  const run = async () => {
+    if (key === void 0) return { kind: "service", result: { ok: await call() } };
+    const outcome = await ports.inFlightCalls.run(key, (signal) => untilAborted(signal, call(signal)));
+    return outcome.cancelled ? { kind: "serviceCancelled" } : { kind: "service", result: { ok: outcome.value } };
+  };
+  try {
+    return await run();
+  } catch (error) {
+    return { kind: "service", result: { error: failureMessage(error) } };
+  }
+}
+function startDeferredCall(defer, site, key, call, context) {
+  const { ports, orbital, scope } = context;
+  const deliver = (event, payload) => defer({
+    orbital,
+    traitName: site.trait,
+    event,
+    payload,
+    entityId: scope.entityId,
+    originClientId: scope.originClientId,
+    locale: scope.locale
+  });
+  const outcome = key === void 0 ? call(void 0, true).then((value) => ({ cancelled: false, value })) : ports.inFlightCalls.run(key, (signal) => untilAborted(signal, call(signal, true)));
+  void outcome.then(
+    (settled) => {
+      if (settled.cancelled) {
+        if (site.emit.cancelled !== void 0 && key !== void 0) deliver(site.emit.cancelled, { key });
+      } else if (site.emit.success !== void 0) {
+        deliver(site.emit.success, keyed(settled.value === null ? void 0 : toEventPayload(settled.value), key));
+      }
+    },
+    (error) => {
+      if (site.emit.failure !== void 0) deliver(site.emit.failure, keyed({ error: failureMessage(error) }, key));
+    }
+  );
+}
+function keyed(payload, key) {
+  return payload !== void 0 && key !== void 0 ? { ...payload, key } : payload;
+}
+function toEventPayload(value) {
+  return isJsonObject(value) ? value : void 0;
+}
+async function substrate(ports, request, scope) {
+  const { key, site } = request;
+  const sink = ports.deferCallOutcome();
+  const complete = ports.substrateCompletion;
+  if (key === void 0 || site === void 0 || sink === void 0 || complete === void 0) return substrateInPlace(ports, request, scope);
+  const source = site.emit.onMessage !== void 0 ? ports.substrateStream?.(request.op, request.args, scope) : void 0;
+  if (ports.inFlightCalls.inFlight(key)) return { kind: "substrate", result: { error: { message: source !== void 0 ? `key ${key} already has a stream open` : `key ${key} already has a completion pending`, errors: [] } } };
+  const deliver = (fired) => {
+    if (fired !== null) sink({ orbital: site.orbital ?? scope.orbital, traitName: site.trait, event: fired.event, payload: isJsonObject(fired.payload) ? fired.payload : void 0, entityId: site.entityId, originClientId: scope.originClientId, locale: scope.locale });
+  };
+  const failed = (error) => deliver(complete(site, key, request.op, request.args, { error: { message: failureMessage(error), errors: [] } }));
+  if (source !== void 0 && ports.substrateMessage !== void 0) {
+    const message = ports.substrateMessage;
+    void ports.inFlightCalls.run(key, (signal) => new Promise((resolve) => {
+      let unsubscribe;
+      let ended = false;
+      const end = () => {
+        ended = true;
+        unsubscribe?.();
+        signal.removeEventListener("abort", end);
+        resolve();
+      };
+      signal.addEventListener("abort", end, { once: true });
+      unsubscribe = source.subscribe((value) => {
+        if (signal.aborted) return;
+        const fired = message(site, key, value);
+        deliver(fired);
+      }, end);
+      if (ended) unsubscribe();
+    })).catch(failed);
+    return { kind: "serviceDeferred" };
+  }
+  const pending = ports.inFlightCalls.run(key, (signal) => untilAborted(signal, substrateInPlace(ports, request, { ...scope, assertReentry: void 0 })));
+  void pending.then((outcome) => {
+    if (outcome.cancelled || outcome.value.kind !== "substrate") return;
+    deliver(complete(site, key, request.op, request.args, outcome.value.result));
+  }, failed);
+  return { kind: "serviceDeferred" };
+}
+function optionalKey(op, args) {
+  if (args.length === 0) return { key: void 0 };
+  const [key] = args;
+  if (args.length === 1 && typeof key === "string" && key !== "") return { key };
+  return { error: `${op}: the key must be one non-empty text` };
+}
+async function performHostAsk(actions, op, args) {
+  const fail = (message) => ({ error: message });
+  if (op === "auth/sign-out") {
+    if (args.length !== 0) return fail("auth/sign-out takes no arguments");
+    if (actions?.signOut === void 0) return fail("no host sign-out is configured for auth/sign-out");
+    try {
+      await actions.signOut();
+      return { ok: null };
+    } catch (error) {
+      return fail(error instanceof Error ? error.message : String(error));
+    }
+  }
+  const audio = actions?.audio;
+  if (audio === void 0) return fail(`no host audio is configured for ${op}`);
+  let ask;
+  if (op === "audio/stop-music") {
+    if (args.length !== 0) return fail("audio/stop-music takes no arguments");
+    ask = { op };
+  } else {
+    const parsed = optionalKey(op, args);
+    if ("error" in parsed) return fail(parsed.error);
+    if (op === "audio/play-sound") {
+      if (parsed.key === void 0) return fail("audio/play-sound: the key must be one non-empty text");
+      ask = { op, key: parsed.key };
+    } else if (op === "audio/stop-sound" || op === "audio/change-music") {
+      ask = { op, key: parsed.key };
+    } else {
+      return fail(`no host action is configured for ${op}`);
+    }
+  }
+  try {
+    audio(ask);
+    return { ok: null };
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+}
+var SIGN_IN_FIELDS = {
+  google: ["method"],
+  email: ["method", "email", "password"],
+  emailLink: ["method", "email", "continueUrl", "link"],
+  customToken: ["method", "token"]
+};
+function parseSignInRequest(args) {
+  const [request] = args;
+  if (args.length !== 1 || !isJsonObject(request)) return { error: "auth/sign-in takes one request object" };
+  const method = request.method;
+  const allowed = typeof method === "string" ? SIGN_IN_FIELDS[method] : void 0;
+  if (typeof method !== "string" || allowed === void 0) return { error: "auth/sign-in: method must be google, email, emailLink or customToken" };
+  const text = (field) => {
+    const value = request[field];
+    return typeof value === "string" && value !== "" ? value : void 0;
+  };
+  for (const field of Object.keys(request)) {
+    if (!allowed.includes(field)) return { error: `auth/sign-in: ${field} is not a field of the ${method} method` };
+  }
+  if (method === "google") return { request: { method } };
+  if (method === "email") {
+    const email2 = text("email");
+    const password = text("password");
+    return email2 !== void 0 && password !== void 0 ? { request: { method, email: email2, password } } : { error: "auth/sign-in: email takes an email and a password" };
+  }
+  if (method === "customToken") {
+    const token = text("token");
+    return token !== void 0 ? { request: { method, token } } : { error: "auth/sign-in: customToken takes a token" };
+  }
+  const email = text("email");
+  const continueUrl = text("continueUrl");
+  const link = text("link");
+  if (email === void 0 || continueUrl === void 0 === (link === void 0)) {
+    return { error: "auth/sign-in: emailLink takes an email and exactly one of continueUrl (send the link) or link (complete the sign-in)" };
+  }
+  return continueUrl !== void 0 ? { request: { method: "emailLink", email, continueUrl } } : { request: { method: "emailLink", email, link } };
+}
+function parseConsentRequest(args) {
+  const [request] = args;
+  if (args.length !== 1 || !isJsonObject(request)) return { error: "auth/consent takes one request object" };
+  for (const field of Object.keys(request)) {
+    if (field !== "authorizeUrl") return { error: `auth/consent: ${field} is not a field of the request` };
+  }
+  const authorizeUrl = request.authorizeUrl;
+  return typeof authorizeUrl === "string" && authorizeUrl !== "" ? { request: { authorizeUrl } } : { error: "auth/consent: authorizeUrl must be one non-empty text" };
+}
+function consentFromRedirect(redirectUrl) {
+  let params;
+  try {
+    params = new URL(redirectUrl).searchParams;
+  } catch {
+    throw new HostAskError("invalid", "the consent redirect is not a URL");
+  }
+  const code = params.get("code");
+  const state = params.get("state");
+  if (code === null || code === "" || state === null || state === "") throw new HostAskError("denied", "the consent redirect carried no code and state");
+  return { code, state };
+}
+async function performConsent(actions, args) {
+  const parsed = parseConsentRequest(args);
+  if ("error" in parsed) return { error: parsed.error, kind: "invalid" };
+  if (actions?.consent === void 0) return { error: "no host consent is configured for auth/consent", kind: "unavailable" };
+  try {
+    const { code, state } = await actions.consent(parsed.request);
+    return { ok: { code, state } };
+  } catch (error) {
+    if (error instanceof HostAskError) return { error: error.message, kind: error.kind };
+    return { error: error instanceof Error ? error.message : String(error), kind: "unavailable" };
+  }
+}
+async function performHostAnswer(actions, op, args) {
+  if (op === "auth/consent") return performConsent(actions, args);
+  if (op !== "auth/sign-in") {
+    const outcome = await performHostAsk(actions, op, args);
+    return "error" in outcome ? { error: outcome.error, kind: "unavailable" } : { ok: {} };
+  }
+  const parsed = parseSignInRequest(args);
+  if ("error" in parsed) return { error: parsed.error, kind: "invalid" };
+  if (actions?.signIn === void 0) return { error: "no host sign-in is configured for auth/sign-in", kind: "unavailable" };
+  try {
+    const answer = await actions.signIn(parsed.request);
+    const fields = {};
+    if ("sent" in answer) fields.sent = true;
+    else {
+      fields.uid = answer.uid;
+      if (answer.email !== void 0) fields.email = answer.email;
+      if (answer.displayName !== void 0) fields.displayName = answer.displayName;
+    }
+    return { ok: fields };
+  } catch (error) {
+    if (error instanceof HostAskError) return { error: error.message, kind: error.kind };
+    return { error: error instanceof Error ? error.message : String(error), kind: "unavailable" };
+  }
+}
+function hostAskReturn(completion, outcome) {
+  const keyed2 = completion.key !== void 0 ? { key: completion.key } : {};
+  const event = "ok" in outcome ? completion.success : completion.failure;
+  if (event === void 0) return void 0;
+  const payload = "ok" in outcome ? { ...outcome.ok, ...keyed2 } : { error: outcome.error, kind: outcome.kind, ...keyed2 };
+  return { trait: completion.trait, ...completion.entityId !== void 0 ? { entityId: completion.entityId } : {}, event, payload };
+}
+async function hostAction(ports, request) {
+  const outcome = await performHostAsk(ports.hostActions, request.op, request.args);
+  return "error" in outcome ? { kind: "substrate", result: { error: { message: outcome.error, errors: [] } } } : { kind: "substrate", result: { ok: null } };
+}
+async function substrateInPlace(ports, request, scope) {
+  if (request.op === "auth/sign-in" || request.op === "auth/consent") return { kind: "substrate", result: { error: { message: `${request.op} runs on the client host: a server-role kernel cannot ask it`, errors: [] } } };
+  if (request.op.startsWith("audio/") || request.op === "auth/sign-out") return hostAction(ports, request);
+  if (request.op === "program/live") return { kind: "substrate", result: { error: { message: "program/live streams to its onMessage route: give it a key and an onMessage route", errors: [] } } };
+  const handler = ports.programEffect();
+  const failure = (message, errors = []) => {
+    const detail = { message, errors };
+    return { kind: "substrate", result: { error: detail } };
+  };
+  if (request.op === "program/dispatch" || request.op === "program/inputs" || request.op === "program/resolve-rows") {
+    const lent = ports.servicePorts({ orbital: scope.orbital, trait: "" }, void 0, () => {
+    }, scope.assertReentry);
+    try {
+      const delivered = await deliverAgentAsk(request.op, request.args, lent, ports, scope.originClientId);
+      if (delivered.ok) return { kind: "substrate", result: { ok: delivered.result } };
+      return failure(delivered.error, delivered.errors ?? []);
+    } catch (error) {
+      return failure(error instanceof Error ? error.message : String(error));
+    }
+  }
+  if (handler === void 0) return failure(`no program host configured for ${request.op}`);
+  if (!isProgramEffect(request.op)) return failure(`no program host configured for ${request.op}`);
+  try {
+    const outcome = await handler(request.op, request.args, void 0);
+    if (outcome.ok) return { kind: "substrate", result: { ok: programDocumentJson(outcome.result) } };
+    return failure(outcome.error, (outcome.errors ?? []).map((issue) => issuePayload(issue)));
+  } catch (error) {
+    return failure(error instanceof Error ? error.message : String(error));
+  }
+}
+async function deliverAgentAsk(op, args, host, ports, clientId) {
+  const [first, second, third] = args;
+  if (op === "program/resolve-rows") {
+    if (args.length !== 2 || first === void 0 || second === void 0) return { ok: false, error: "program/resolve-rows: the host is asked for a row-set reference and the viewer slot, which is null: a program names no viewer" };
+    const reference = RowSetRefSchema.safeParse(first);
+    if (!reference.success) {
+      const error = `program/resolve-rows: not a row-set reference: ${reference.error.message}`;
+      return { ok: false, error, errors: [{ code: "INVALID_REQUEST", message: error, status: 400 }] };
+    }
+    if (second !== null) return { ok: false, error: "program/resolve-rows: rows resolve for the requesting session's identity (EXEC-IDENTITY-1); a program names no viewer, so the viewer argument is null" };
+    if (host.resolveRows === void 0) return { ok: false, error: "program/resolve-rows: this host resolves no row sets" };
+    const page = await host.resolveRows(reference.data, clientId);
+    return { ok: true, result: toPayloadValue(page) };
+  }
+  if (op === "program/inputs") {
+    const steps = args.length === 1 && isJsonObject(first) ? first["trace"] : void 0;
+    if (typeof steps !== "number") return { ok: false, error: "program/inputs: the host is asked for { trace } only" };
+    if (host.trace === void 0) return { ok: false, error: "program/inputs: this host keeps no dispatch trace" };
+    return { ok: true, result: host.trace(steps) };
+  }
+  if (args.length === 1 && isJsonObject(first)) {
+    const { inbound, body, headers } = first;
+    if (typeof inbound !== "string" || typeof body !== "string" || !isJsonObject(headers)) return { ok: false, error: "program/dispatch: the host is asked for { inbound, body, headers }" };
+    if (host.deliverInbound === void 0) return { ok: false, error: "program/dispatch: this host does not deliver inbound requests" };
+    const named = {};
+    for (const [key, value] of Object.entries(headers)) if (typeof value === "string") named[key] = value;
+    const answer = await host.deliverInbound(inbound, { headers: named, rawBody: body });
+    return { ok: true, result: { status: answer.status, body: answer.body } };
+  }
+  if (typeof first !== "string" || second === void 0 || !isJsonObject(second)) return { ok: false, error: "program/dispatch: the host is asked for a qualified address and a payload record" };
+  const payload = second;
+  if (isJsonObject(third)) {
+    if (host.dispatchRequest === void 0) return { ok: false, error: "program/dispatch: this host does not serve event requests" };
+    const stream = third["stream"] === true;
+    if (stream && host.supportsDispatchStream !== true) return { ok: false, error: "program/dispatch: this host does not answer stream items" };
+    const parse = ports.parseEventRequest;
+    if (parse === void 0) return { ok: false, error: "program/dispatch: this host has no kernel to parse an event request" };
+    const parsed = parse(payload, third);
+    if ("error" in parsed) return { ok: false, error: parsed.error, errors: [{ code: "INVALID_REQUEST", message: parsed.error, status: 400 }] };
+    const orbital = typeof third["orbital"] === "string" ? third["orbital"] : "";
+    const answered = await host.dispatchRequest(orbital, parsed.ok, third["input"] === true, stream);
+    if (!answered.ok) return { ok: false, error: answered.error, errors: [{ code: answered.code, message: answered.error, status: answered.status }] };
+    if (!stream) return { ok: true, result: answered.response };
+    if (answered.streamItems === void 0) return { ok: false, error: "program/dispatch: this host does not answer stream items" };
+    return { ok: true, result: { ...answered.response, items: answered.streamItems } };
+  }
+  const event = first.lastIndexOf(".");
+  const trait = first.lastIndexOf(".", event - 1);
+  if (event < 0 || trait < 0) return { ok: false, error: `program/dispatch: '${first}' is not a qualified address` };
+  const response = await host.dispatchInput(first.slice(0, trait), { targetTrait: first.slice(trait + 1, event), event: first.slice(event + 1), payload });
+  return { ok: true, result: response };
+}
+var CREDENTIAL_CONNECT_UNAVAILABLE = "this host holds no credential store that can connect";
+var SECRET_PORTS_UNAVAILABLE = "SECRET_PORTS_UNAVAILABLE: this host was given no secret ports";
+async function onDeviceModel(ports, request, scope) {
+  const { key } = request;
+  const ask = async (signal) => request.kind === "prompt" ? { kind: "prompt", result: { ok: await promptOnDevice(ports.onDevice, request.text, request.schema, key ?? null, signal) } } : { kind: "embed", result: { ok: await embedOnDevice(ports.onDevice, request.texts, key ?? null, signal) } };
+  const run = async () => {
+    if (key === void 0) return ask();
+    const outcome = await ports.inFlightCalls.run(key, (signal) => untilAborted(signal, ask(signal)));
+    return outcome.cancelled ? { kind: "serviceCancelled" } : outcome.value;
+  };
+  try {
+    return await run();
+  } catch (error) {
+    const failure = error instanceof OnDeviceModelFailure ? { kind: error.kind, message: error.message } : { kind: "failed", message: failureMessage(error) };
+    return request.kind === "prompt" ? { kind: "prompt", result: { error: failure } } : { kind: "embed", result: { error: failure } };
+  }
+}
+var NO_TAB_HOST = "browser/tab: no host answers browser tabs";
+async function tab(ports, request, scope) {
+  const { ask, key } = request;
+  const port = ports.tabs;
+  if (port === void 0) return { kind: "tab", result: { error: { kind: "unavailable", message: NO_TAB_HOST } } };
+  const deliver = (payload) => {
+    if (ask.kind !== "watch") return;
+    const target = ask.deliver;
+    const lent = ports.servicePorts({ orbital: target.orbital, trait: target.trait }, void 0, () => {
+    });
+    void lent.dispatchInput(target.orbital, { targetTrait: target.trait, event: target.event, payload });
+  };
+  const perform = async (signal) => {
+    try {
+      return { kind: "tab", result: { ok: await port.perform(ask, { ...signal !== void 0 ? { signal } : {}, deliver }) } };
+    } catch (error) {
+      if (error instanceof TabHostFailure) return { kind: "tab", result: { error: { kind: error.kind, message: error.message } } };
+      return { kind: "tab", result: { error: { kind: "failed", message: failureMessage(error) } } };
+    }
+  };
+  const run = async () => {
+    if (key === void 0) return perform();
+    const outcome = await ports.inFlightCalls.run(key, (signal) => untilAborted(signal, perform(signal)));
+    return outcome.cancelled ? { kind: "serviceCancelled" } : outcome.value;
+  };
+  return run();
+}
+async function pageFacts(ports, request) {
+  return { kind: "pageFacts", result: await settle(async () => ports.pageFacts?.(request.fields) ?? { available: false, hostname: "", referrer: "", screenWidth: null, href: "" }) };
+}
+function finishTls(ports, os, key, raw) {
+  return new Promise((resolve) => completeTls(ports, os, key, raw, resolve));
+}
+function completeTls(ports, os, key, raw, finish) {
+  const tls = ports.osTls;
+  if (tls === void 0) {
+    finish(raw);
+    return;
+  }
+  const step = (outcome, parked) => {
+    const next = tls.complete(key, outcome);
+    if (next === null) {
+      finish(parked ? { error: { kind: "tls", message: "the TLS operation vanished" } } : outcome);
+      return;
+    }
+    if ("done" in next) {
+      finish(next.done);
+      return;
+    }
+    void os.answer(next.ask.op, next.ask.args).then((answered) => step(answered, true));
+  };
+  step(raw, false);
+}
+var CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+var SEGMENT_ENCODERS = {
+  base64: (value) => base64Standard(new TextEncoder().encode(value)),
+  uri: (value) => encodeURIComponent(value),
+  form: (value) => encodeURIComponent(value).replace(/[!'()~]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%20/g, "+")
+};
+async function withCredentialSegments(ports, op, args, principal) {
+  const segments = args[1];
+  if (op !== "os/send" || !Array.isArray(segments)) return { args };
+  const parts = [];
+  for (const [at, segment] of segments.entries()) {
+    const invalid = (what) => ({ error: { kind: "invalid", message: `${op}: segment ${at + 1} ${what}` } });
+    if (!isJsonObject(segment)) return invalid("is not a { bytes, credential } object");
+    const text = segment["bytes"];
+    const name = segment["credential"];
+    if (typeof text !== "string" || typeof name !== "string") return invalid("needs a bytes text and a credential name");
+    if (!CANONICAL_BASE64.test(text)) return invalid("bytes are not standard base64");
+    parts.push(Uint8Array.from(atob(text), (c) => c.charCodeAt(0)));
+    const requested = segment["encode"];
+    const encoder = requested === void 0 ? void 0 : typeof requested === "string" && Object.hasOwn(SEGMENT_ENCODERS, requested) ? SEGMENT_ENCODERS[requested] : null;
+    if (encoder === null) return invalid(`encode must be one of ${Object.keys(SEGMENT_ENCODERS).join(", ")}`);
+    const requestedScope = segment["scope"];
+    if (requestedScope !== void 0 && requestedScope !== "app" && requestedScope !== "user") return invalid("scope must be one of app, user");
+    if (name === "") continue;
+    if (requestedScope === "user" && principal === void 0) return { error: { kind: "denied", message: `${op}: segment ${at + 1} needs a signed-in viewer` } };
+    const store = ports.secretPorts?.secrets;
+    if (store === void 0) return { error: { kind: "denied", message: `${op}: no credential source is configured` } };
+    let held;
+    try {
+      held = await store.get(name, requestedScope === "user" ? principal : void 0);
+    } catch (error) {
+      return { error: { kind: "io", message: `${op}: credential ${name}: ${error instanceof Error ? error.message : String(error)}` } };
+    }
+    if (held === void 0 || held === null) return { error: { kind: "denied", message: `${op}: credential ${name} is not held` } };
+    parts.push(new TextEncoder().encode(encoder === void 0 ? held : encoder(held)));
+  }
+  const bytes = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    bytes.set(part, offset);
+    offset += part.length;
+  }
+  return { args: [args[0] ?? null, base64Standard(bytes), ...args.slice(2)] };
+}
+async function osAnswer(ports, request, scope) {
+  const { os } = ports;
+  if (os === void 0) return { kind: "os", result: { error: { kind: "denied", message: `${request.op}: no os host configured` } } };
+  const { op, key, site, orbital: asking } = request;
+  const completions = ports.osCompletions;
+  const sink = ports.deferCallOutcome();
+  const message = ports.substrateMessage;
+  const streaming = key !== void 0 && site !== void 0 && completions !== void 0 && sink !== void 0 && message !== void 0 && os.stream !== void 0 && completions.streams(op);
+  const deferring = !streaming && key !== void 0 && site !== void 0 && completions !== void 0 && sink !== void 0 && os.defer !== void 0 && completions.defers(op);
+  const lease = (streaming || deferring) && key !== void 0 ? ports.inFlightCalls.reserve(key) : void 0;
+  if ((streaming || deferring) && lease === void 0) {
+    return { kind: "os", result: { error: { kind: "invalid", message: `${op}: key ${key} already has ${streaming ? "a stream open" : "a completion pending"}` } } };
+  }
+  const segmented = await withCredentialSegments(ports, op, request.args, request.principal);
+  if ("error" in segmented) {
+    lease?.release();
+    return { kind: "os", result: segmented };
+  }
+  if (lease?.signal.aborted === true) {
+    lease.release();
+    return { kind: "serviceCancelled" };
+  }
+  const { args } = segmented;
+  if (lease !== void 0 && streaming && key !== void 0 && site !== void 0 && completions !== void 0 && sink !== void 0 && message !== void 0 && os.stream !== void 0) {
+    const orbital = site.orbital ?? scope.orbital;
+    const stop = () => {
+      os.cancel?.(key);
+      lease.release();
+    };
+    lease.signal.addEventListener("abort", stop, { once: true });
+    const deliver = (fired) => {
+      if (fired === null || lease.signal.aborted) return false;
+      sink({ orbital, traitName: site.trait, event: fired.event, payload: isJsonObject(fired.payload) ? fired.payload : void 0, entityId: site.entityId, originClientId: scope.originClientId, locale: scope.locale });
+      return true;
+    };
+    const started = await os.stream(op, args, key, (value) => deliver(message(site, key, value)), (error) => {
+      lease.release();
+      lease.signal.removeEventListener("abort", stop);
+      deliver(completions.event(site, key, { error }));
+    }, asking);
+    if ("error" in started) {
+      lease.release();
+      lease.signal.removeEventListener("abort", stop);
+    }
+    return { kind: "os", result: started };
+  }
+  if (lease !== void 0 && deferring && key !== void 0 && site !== void 0 && completions !== void 0 && sink !== void 0 && os.defer !== void 0) {
+    const orbital = site.orbital ?? scope.orbital;
+    const cancel = () => {
+      os.cancel?.(key);
+      lease.release();
+    };
+    lease.signal.addEventListener("abort", cancel, { once: true });
+    const finish = (outcome) => {
+      lease.release();
+      lease.signal.removeEventListener("abort", cancel);
+      if (lease.signal.aborted) return;
+      const fired = completions.event(site, key, outcome);
+      if (fired === null) return;
+      sink({
+        orbital,
+        traitName: site.trait,
+        event: fired.event,
+        payload: isJsonObject(fired.payload) ? fired.payload : void 0,
+        entityId: site.entityId,
+        originClientId: scope.originClientId,
+        locale: scope.locale
+      });
+    };
+    const started = os.defer(op, args, key, (raw) => {
+      completeTls(ports, os, key, raw, finish);
+    }, asking);
+    if ("error" in started) {
+      lease.release();
+      lease.signal.removeEventListener("abort", cancel);
+    }
+    return "error" in started ? { kind: "os", result: started } : { kind: "serviceDeferred" };
+  }
+  return { kind: "os", result: await os.answer(op, args, asking) };
+}
+async function secret(ports, request) {
+  const store = ports.secretPorts?.secrets;
+  if (store === void 0) return { kind: "secret", result: { error: SECRET_PORTS_UNAVAILABLE } };
+  return { kind: "secret", result: await settle(async () => await store.get(request.name, request.principal) ?? null) };
+}
+async function secretSet(ports, request) {
+  const store = ports.secretPorts?.secrets;
+  if (store === void 0) return { kind: "secretSet", result: { error: SECRET_PORTS_UNAVAILABLE } };
+  return { kind: "secretSet", result: await settle(async () => {
+    await store.set(request.name, request.value, request.ttlMs, request.principal);
+    return null;
+  }) };
+}
+async function secretRotate(ports, request) {
+  const store = ports.secretPorts?.secrets;
+  if (store === void 0) return { kind: "secretRotate", result: { error: SECRET_PORTS_UNAVAILABLE } };
+  const rotate = store.rotate;
+  if (rotate === void 0) return { kind: "secretRotate", result: { error: "this host keeps no rotatable credentials" } };
+  return { kind: "secretRotate", result: await settle(async () => {
+    await rotate.call(store, request.name, request.value, request.principal);
+    return null;
+  }) };
+}
+function random(ports, request) {
+  const source = ports.secretPorts?.random ?? systemRandom;
+  try {
+    return { kind: "random", result: { ok: base64Standard(source(request.bytes)) } };
+  } catch (error) {
+    return { kind: "random", result: { error: failureMessage(error) } };
+  }
+}
+async function credentialStatus(ports, request) {
+  const store = ports.secretPorts?.secrets;
+  if (store === void 0) return { kind: "credentialStatus", result: { error: SECRET_PORTS_UNAVAILABLE } };
+  return { kind: "credentialStatus", result: await settle(async () => {
+    const connected = credentialStatusConnected(await store.get(request.name, request.principal), request.principal);
+    const label = connected ? await store.label?.(request.name, request.principal) : void 0;
+    return { connected, ...label !== void 0 ? { label } : {} };
+  }) };
+}
+async function credentialForget(ports, request) {
+  const store = ports.secretPorts?.secrets;
+  if (store === void 0) return { kind: "credentialForget", result: { error: SECRET_PORTS_UNAVAILABLE } };
+  return { kind: "credentialForget", result: await settle(async () => {
+    await store.forget(request.name, request.principal);
+    return null;
+  }) };
+}
+async function credentialConnect(ports, request) {
+  const connect = ports.secretPorts?.connect;
+  if (connect === void 0) return { kind: "credentialConnect", result: { error: { kind: "unavailable", message: CREDENTIAL_CONNECT_UNAVAILABLE } } };
+  try {
+    return { kind: "credentialConnect", result: await connect(request.grant) };
+  } catch (error) {
+    return { kind: "credentialConnect", result: { error: { kind: "unavailable", message: failureMessage(error) } } };
+  }
+}
+async function credentialEnvTails(ports, request) {
+  const env = ports.secretPorts?.env;
+  if (env === void 0) return { kind: "credentialEnvTails", result: { ok: { kind: "unsupported" } } };
+  return { kind: "credentialEnvTails", result: await settle(async () => ({ kind: "held", tails: env(request.names) })) };
+}
+async function credentialAdmin(ports, work) {
+  const port = ports.secretPorts?.credentials;
+  if (port === void 0) return { error: SECRET_PORTS_UNAVAILABLE };
+  return settle(() => work(port));
+}
+function rowData(value) {
+  if (!isJsonObject(value)) throw new Error("persist: the row is not an object");
+  return value;
+}
+async function queryRows(persistence, request) {
+  const { entityType, query, project } = request;
+  try {
+    if (project === "ids") {
+      if (!persistence.queryIds) return { kind: "queryUnsupported", reason: "no-ids-capability" };
+      return { kind: "idPage", result: { ok: await persistence.queryIds(entityType, query) } };
+    }
+    if (!persistence.queryPage) return { kind: "queryUnsupported", reason: "no-query-capability" };
+    return { kind: "page", result: { ok: await persistence.queryPage(entityType, query) } };
+  } catch (error) {
+    if (error instanceof QueryDeclinedError) return { kind: "queryUnsupported", reason: error.reason };
+    return { kind: project === "ids" ? "idPage" : "page", result: { error: failureMessage(error) } };
+  }
+}
+async function commitRows(persistence, request) {
+  if (!persistence.commitRows) return { kind: "committed", result: { error: "this store does not commit rows" } };
+  try {
+    return { kind: "committed", result: { ok: await persistence.commitRows(request.rows) } };
+  } catch (error) {
+    return { kind: "committed", result: { error: failureMessage(error) } };
+  }
+}
+async function writeRows(persistence, request) {
+  const { batch } = request;
+  try {
+    if (!persistence.writeBatch) return { kind: "writeUnsupported", reason: "no-write-capability" };
+    return { kind: "wrote", result: { ok: await persistence.writeBatch(batch) } };
+  } catch (error) {
+    if (error instanceof WriteDeclinedError) return { kind: "writeUnsupported", reason: error.reason };
+    return { kind: "wrote", result: { error: failureMessage(error) } };
+  }
+}
+function declareCapabilities(persistence, declare, entityTypes) {
+  for (const entityType of entityTypes) {
+    const query = persistence.queryPage ? persistence.queryCapabilities?.(entityType) : void 0;
+    const write = persistence.writeWhere || persistence.writeBatch || persistence.commitRows ? persistence.writeCapabilities?.(entityType) : void 0;
+    if (query === void 0 && write === void 0) continue;
+    declare(entityType, JSON.stringify(query ?? null), JSON.stringify(write ?? null));
+  }
+}
+async function answerRequest(ports, request, scope) {
+  const { persistence } = ports;
+  switch (request.kind) {
+    case "readRow":
+      return {
+        kind: "row",
+        result: await settle(async () => {
+          const row = await persistence.getById(request.entityType, request.id);
+          return row;
+        })
+      };
+    case "listRows":
+      return {
+        kind: "rows",
+        result: await settle(async () => await persistence.list(request.entityType))
+      };
+    case "queryRows":
+      return queryRows(persistence, request);
+    case "writeRows":
+      return writeRows(persistence, request);
+    case "commitRows":
+      return commitRows(persistence, request);
+    case "createRow":
+      return {
+        kind: "row",
+        result: await settle(async () => {
+          const data = rowData(request.data);
+          const { id } = await persistence.create(request.entityType, data);
+          return await persistence.getById(request.entityType, id) ?? { ...data, id };
+        })
+      };
+    case "writeRow":
+      return {
+        kind: "row",
+        result: await settle(async () => {
+          const data = rowData(request.data);
+          const existing = await persistence.getById(request.entityType, request.id);
+          if (existing === null) await persistence.create(request.entityType, { ...data, id: request.id });
+          else await persistence.update(request.entityType, request.id, { ...data, id: request.id });
+          return await persistence.getById(request.entityType, request.id) ?? { ...existing, ...data, id: request.id };
+        })
+      };
+    case "deleteRow":
+      return {
+        kind: "deleted",
+        result: await settle(async () => {
+          await persistence.delete(request.entityType, request.id);
+          return null;
+        })
+      };
+    case "callService":
+      return callService(ports, request, scope);
+    case "cancelCall":
+      ports.inFlightCalls.cancel(request.key);
+      ports.os?.cancel?.(request.key);
+      return { kind: "cancelled", result: { ok: null } };
+    case "substrate":
+      return substrate(ports, request, scope);
+    case "pageFacts":
+      return pageFacts(ports, request);
+    case "prompt":
+    case "embed":
+      return onDeviceModel(ports, request);
+    case "tab":
+      return tab(ports, request);
+    case "secret":
+      return secret(ports, request);
+    case "secretSet":
+      return secretSet(ports, request);
+    case "secretRotate":
+      return secretRotate(ports, request);
+    case "random":
+      return random(ports, request);
+    case "os":
+      return osAnswer(ports, request, scope);
+    case "clock":
+      return { kind: "clock", result: { ok: (ports.now ?? Date.now)() } };
+    case "sealed":
+      return { kind: "sealed", result: { error: `${request.op}: a sealed operator is answered by the kernel, never by a host` } };
+    case "deliver":
+      return { kind: "deliver", result: { error: { kind: "down", id: request.envelope.id } } };
+    case "guest":
+      return { kind: "substrate", result: { error: { message: "program/dispatch: this host starts no guest kernels", errors: [{ kind: "unsupported", message: "program/dispatch: this host starts no guest kernels" }] } } };
+    case "credentialStatus":
+      return credentialStatus(ports, request);
+    case "credentialForget":
+      return credentialForget(ports, request);
+    case "credentialConnect":
+      return credentialConnect(ports, request);
+    case "credentialStoreList":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.list()) };
+    case "credentialEnvTails":
+      return credentialEnvTails(ports, request);
+    case "credentialStoreRead":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.read(request.name)) };
+    case "credentialStoreWrite":
+      return { kind: request.kind, result: await credentialAdmin(ports, async (port) => {
+        await port.write(request.service, request.name, request.value);
+        return null;
+      }) };
+    case "credentialStoreRemove":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.remove(request.name)) };
+    case "credentialStoreRotate":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.rotate()) };
+    case "credentialModeRead":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.mode()) };
+    case "credentialModeWrite":
+      return { kind: request.kind, result: await credentialAdmin(ports, (port) => port.setMode(request.mode)) };
+  }
+}
+
+export { HostAskError, answerRequest, completeTls, consentFromRedirect, declareCapabilities, finishTls, hostAskReturn, kernelEventRequestParser, parseConsentRequest, parseSignInRequest, performHostAnswer, performHostAsk, writeRows };