@godspeedai/cognate-runtime-bun 0.0.0-stage → 0.1.1

package/src/runtime.ts

@@ -0,0 +1,235 @@
+// Composition root: store, kernel, continuations, artifacts, projections, cognition, and the background loop.
+import { ArtifactService } from "@godspeedai/cognate-artifacts";
+import { ContinuationService } from "@godspeedai/cognate-continuations";
+import { type DurableStore, OutboxDispatcher } from "@godspeedai/cognate-events";
+import { createCordisKernel } from "@godspeedai/cognate-kernel-cordis";
+import type { Principal } from "@godspeedai/cognate-kernel-api";
+import { ProjectionRunner } from "@godspeedai/cognate-projections";
+import { openSqliteStore } from "@godspeedai/cognate-store-sqlite";
+import { COGNITION_PROJECTION, cognitionProjection, recallFor } from "./cognition.ts";
+import type { Core } from "./core.ts";
+import { executeOnce } from "./executor.ts";
+import { foldRun, isTerminal, RESUME_HANDLER, RUN_EXECUTE_TOPIC, RUNS, runStream } from "./fold.ts";
+import type { Runtime, RuntimeOptions } from "./index.ts";
+import { inspectCorrelation } from "./inspect.ts";
+import { Governor } from "./governed-operation.ts";
+import { Invoker } from "./invoker.ts";
+import { createService } from "./service.ts";
+import { RemoteOfferRegistry } from "./remote-offers.ts";
+
+const DELIVERY = { baseMs: 50, maxMs: 5_000, maxAttempts: 10 };
+const TOPICS = [RUN_EXECUTE_TOPIC, "continuation.resume"];
+
+export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
+  const ownsStore = typeof options.store === "string";
+  const store: DurableStore = typeof options.store === "string" ? openSqliteStore({ path: options.store }) : options.store.store;
+  const system: Principal = options.system ?? { id: "system", kind: "system" };
+  const governor = new Governor(options.actions, options.policy, options.governance ?? { mode: "off" });
+  const invoker = new Invoker(governor);
+  // The kernel is single-tenant by contract; the invoker supplies each call's tenant to the policy.
+  const kernel = await createCordisKernel({ tenant: "runtime", principal: system, policy: invoker.policy });
+  await invoker.attach(kernel, options.components ?? []);
+
+  // Authorization happens in the service against `actions`; the continuation layer trusts its caller.
+  const continuations = new ContinuationService(store, { policy: { authorize: () => ({ allow: true, reason: "authorized by runtime service" }) }, delivery: DELIVERY });
+
+  let closed = false;
+  const chains = new Map<string, Promise<void>>();
+  const pending = new Set<string>();
+  const execute = (runId: string): Promise<void> => {
+    const next = (chains.get(runId) ?? Promise.resolve()).then(async () => {
+      for (let attempt = 0; attempt < 5 && !closed; attempt++) if ((await executeOnce(core, runId)) === "done") return;
+    });
+    const tracked = next.finally(() => {
+      if (chains.get(runId) === tracked) chains.delete(runId);
+    });
+    chains.set(runId, tracked);
+    return tracked;
+  };
+
+  const core: Core = {
+    store,
+    kernel,
+    invoker,
+    continuations,
+    artifacts: new ArtifactService(store),
+    governor,
+    agents: new Map(options.agents.map((a) => [a.id, a])),
+    scopeId: kernel.root.id,
+    recall: recallFor(store, options.cognition),
+    outboxFor: options.outboxFor ?? (() => []),
+    controllers: new Map(),
+    remoteOffers: new RemoteOfferRegistry(),
+    execute,
+    kick: () => kick(),
+  };
+
+  const unregister = continuations.registerHandler({
+    ...RESUME_HANDLER,
+    supports: (stored) => stored === RESUME_HANDLER.version,
+    handle: (record) => execute(record.runId),
+  });
+
+  const runDispatcher = new OutboxDispatcher(store, {
+    topic: RUN_EXECUTE_TOPIC,
+    backoff: DELIVERY,
+    deliver: async (item) => {
+      await execute((item.payload as { runId: string }).runId);
+      return { executed: true };
+    },
+  });
+
+  async function tick(): Promise<void> {
+    for (const record of await continuations.expireDue()) pending.add(record.runId);
+    await continuations.dispatchResumes();
+    await runDispatcher.drain();
+    for (const runId of [...pending]) {
+      pending.delete(runId);
+      await execute(runId);
+    }
+  }
+
+  let ticking: Promise<void> | null = null;
+  let again = false;
+  function kick(): void {
+    if (closed) return;
+    if (ticking) {
+      again = true;
+      return;
+    }
+    ticking = (async () => {
+      do {
+        again = false;
+        await tick().catch(() => {});
+      } while (again && !closed);
+    })().finally(() => {
+      ticking = null;
+    });
+  }
+
+  // Projections: user projections, plus the cognitive indexer when cognition is configured.
+  const runners: ProjectionRunner[] = [];
+  for (const { projection } of options.projections ?? []) runners.push(new ProjectionRunner(store, projection));
+  let cognitionRunner: ProjectionRunner | undefined;
+  if (options.cognition) {
+    cognitionRunner = new ProjectionRunner(store, cognitionProjection(options.cognition));
+    runners.push(cognitionRunner);
+    if (!options.cognition.persistent) {
+      // The index lost its data with the process; never let the checkpoint claim entries it no longer holds.
+      await options.cognition.index.clear();
+      await cognitionRunner.rebuild();
+    }
+  }
+  for (const runner of runners) {
+    if ((await runner.catchUp()).status === "rebuild_required") await runner.rebuild();
+    runner.start();
+  }
+
+  // Recovery: re-enter runs that were running at shutdown or whose wait closed without a delivery.
+  for (const { id } of await store.listRecords(RUNS)) {
+    const view = foldRun(id, await store.readStream(runStream(id)));
+    if (!view || isTerminal(view)) continue;
+    if (view.status === "running") pending.add(id);
+    for (const continuationId of view.waitingOn) {
+      const record = await continuations.get(continuationId);
+      if (record && !["OPEN", "BLOCKED", "RESUMED"].includes(record.status)) pending.add(id);
+    }
+  }
+
+  const timer = setInterval(kick, options.tickMs ?? 10);
+  kick();
+
+  const names = [...(options.projections ?? []).map((p) => p.projection.name), ...(cognitionRunner ? [COGNITION_PROJECTION.name] : [])];
+
+  async function pollApprovals(): Promise<number> {
+    const authority = options.governance?.authority;
+    if (!authority?.approvalState) return 0;
+    const SYSTEM_ACTOR = system;
+    let acted = 0;
+    for (const record of await continuations.list({ status: "OPEN" })) {
+      if (record.type !== "governance-approval") continue;
+      const approvalId = (record.condition as { approvalId?: unknown } | null)?.approvalId;
+      if (typeof approvalId !== "string") continue;
+      const state = await authority.approvalState(approvalId);
+      if (state === "approved") {
+        // Idempotent per approval: a second pass (or a second runtime) cannot resume it twice.
+        const outcome = await continuations.resume(record.id, { actor: SYSTEM_ACTOR, idempotencyKey: `governance-resume:${approvalId}`, input: { approvalId, state } });
+        if (outcome.kind === "transitioned") acted++;
+      } else if (state === "rejected" || state === "expired" || state === "used") {
+        const outcome = await continuations.cancel(record.id, { actor: SYSTEM_ACTOR, idempotencyKey: `governance-close:${approvalId}`, reason: `approval ${approvalId} is ${state}` });
+        if (outcome.kind === "transitioned") {
+          acted++;
+          void execute(record.runId).catch(() => {});
+        }
+      }
+    }
+    if (acted) kick();
+    return acted;
+  }
+
+  let approvalTimer: ReturnType<typeof setInterval> | undefined;
+  if ((options.governance?.approvalPollMs ?? 0) > 0 && options.governance?.authority?.approvalState) {
+    approvalTimer = setInterval(() => void pollApprovals().catch(() => {}), options.governance.approvalPollMs);
+  }
+
+  async function quiescent(): Promise<boolean> {
+    if (ticking || pending.size > 0 || chains.size > 0) return false;
+    const now = Date.now();
+    for (const topic of TOPICS) {
+      const items = await store.listOutbox({ topic, status: "pending" });
+      // Items waiting out a retry backoff do not count as queued work.
+      if (items.some((item) => item.availableAt <= now || item.lastError === null)) return false;
+    }
+    for (const name of names) {
+      const checkpoint = await store.getProjection(name);
+      if (checkpoint?.status === "error") continue;
+      const behind = await store.readAll({ afterPosition: checkpoint?.position ?? 0, limit: 1 });
+      if (behind.length > 0) return false;
+    }
+    return true;
+  }
+
+  return {
+    service: createService(core, new Set((options.projections ?? []).filter((p) => p.public).map((p) => p.projection.name))),
+    kernel,
+    store,
+
+    inspect: (correlationId) => inspectCorrelation(store, continuations, correlationId),
+
+    async rebuildCognition() {
+      if (!options.cognition || !cognitionRunner) return;
+      await options.cognition.index.clear();
+      await cognitionRunner.rebuild();
+    },
+
+    async erase(eventId, reason, actor) {
+      await store.erasePayload(eventId, reason, actor.id);
+    },
+
+    pollApprovals,
+
+    async idle(timeoutMs = 10_000) {
+      const deadline = Date.now() + timeoutMs;
+      for (;;) {
+        // Two consecutive quiet observations, so work kicked off between checks is not missed.
+        if ((await quiescent()) && (await Bun.sleep(1), await quiescent())) return;
+        if (Date.now() > deadline) throw new Error(`runtime-bun: idle() timed out after ${timeoutMs}ms`);
+        kick();
+        await Bun.sleep(2);
+      }
+    },
+
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(timer);
+      if (approvalTimer) clearInterval(approvalTimer);
+      await ticking;
+      await Promise.allSettled([...chains.values()]);
+      for (const runner of runners) await runner.stop();
+      unregister();
+      await kernel.shutdown("runtime closed");
+      if (ownsStore) await store.close();
+    },
+  };
+}

package/src/sea-forge-authority.ts

@@ -0,0 +1,401 @@
+// SeaForgeAuthority: the Cognate half of the CEP authority loop (migration Stage 6).
+//
+// Builds a CEP `authority_request` for one GovernedOperation, sends it to SEA-Forge over its Unix-socket
+// NDJSON protocol (`authority_request` verb), and accepts only a response that is demonstrably the decision
+// for *this* request in *this* world. Anything else is `unknown`, which the Governor refuses.
+import { createHash, randomUUID } from "node:crypto";
+import type { ApprovalReference, ApprovalState, AuthorityReference, GovernanceAuthority, GovernanceConstraint, GovernanceDecision, GovernedOperation } from "./governed-operation.ts";
+
+export interface SeaForgeAuthorityOptions {
+  /** Path of the SEA-Forge cell's `server.sock`. */
+  readonly socketPath: string;
+  /** The identity Cognate claims; the server verifies it against the socket peer's uid. */
+  readonly actor?: { readonly actor_id: string; readonly role: string };
+  readonly timeoutMs?: number;
+  /** Largest response line accepted. */
+  readonly maxResponseBytes?: number;
+}
+
+const REQUEST_PROFILE = "godspeed.authority_request";
+const DECISION_PROFILE = "godspeed.authority_decision";
+const PROFILE_VERSION = "1.0.0";
+const DECISIONS: ReadonlySet<string> = new Set(["allow", "deny", "escalate", "unknown", "constrained_allow", "boundary", "degraded"]);
+const CONSTRAINED: ReadonlySet<string> = new Set(["constrained_allow", "boundary", "degraded"]);
+
+type Obj = Record<string, unknown>;
+const isObj = (value: unknown): value is Obj => typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value: unknown): string | undefined => (typeof value === "string" && value.length > 0 ? value : undefined);
+const strings = (value: unknown): string[] | undefined => (Array.isArray(value) && value.every((v) => typeof v === "string" && v.length > 0) ? (value as string[]) : undefined);
+
+function describe(operation: GovernedOperation): { kind: "action" | "capability"; name: string; resource: string; subject: string; correlation: string } {
+  if (operation.kind === "action") {
+    return { kind: "action", name: operation.action, resource: operation.resource, subject: `actor:${operation.caller.tenant}/${operation.caller.actor.id}`, correlation: "" };
+  }
+  const { request } = operation;
+  return { kind: "capability", name: "invoke", resource: request.capability.id, subject: `actor:${request.tenant}/${request.actor.id}`, correlation: request.correlationId };
+}
+
+/** The CEP `authority_request` envelope for one operation (profile godspeed.authority_request). */
+export function buildAuthorityRequest(operation: GovernedOperation, worldRef: string, now: Date = new Date(), approval?: ApprovalReference, carry?: CarriedWork): { envelope: Obj; operationId: string } {
+  return buildEnvelope(describe(operation), worldRef, now, approval, carry);
+}
+
+/**
+ * Work decided in an earlier world that this request carries forward. SEA-Forge refuses a lineage reaching across
+ * worlds unless it cites the allowed transition that moved it (`ledgerEntry` from `listTransitions()`); work already
+ * decided stays pinned to its world and is never re-pinned.
+ */
+export interface CarriedWork {
+  /** The request envelope ids of the earlier work. */
+  readonly lineage: readonly string[];
+  /** `RecordedTransition.ledgerEntry` of the move from that work's world to this request's world. */
+  readonly transitionLedgerEntry: string;
+}
+
+function buildEnvelope(d: ReturnType<typeof describe>, worldRef: string, now: Date, approval?: ApprovalReference, carry?: CarriedWork): { envelope: Obj; operationId: string } {
+  const operationId = `op-${randomUUID()}`;
+  const at = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const provenanceId = `prov-${operationId}`;
+  const envelope: Obj = {
+    envelope_id: `env-authority_request-${operationId}`,
+    cep_version: "1.0.0",
+    envelope_version: "1.0",
+    envelope_kind: "authority_request",
+    created_at: at,
+    created_by: "cognate",
+    scope: { evaluation_context: "cognate-authority_request", world_ref: worldRef },
+    boundary_record: {
+      scope: "authority request for one Cognate operation",
+      included_sections: ["authority", "references", "states", "transformations"],
+      excluded_sections: [],
+      known_omissions: ["operation payload is not carried"],
+      unknowns: [],
+      redactions: [],
+      compression_notes: [],
+      out_of_scope_entities: [],
+      classification: "internal",
+      limitations: [],
+    },
+    completeness_status: "partial",
+    omission_status: "marked",
+    provenance_refs: [provenanceId],
+    validation_status: "valid",
+    // A revalidation links back to the request that escalated; the approval itself is bound server-side.
+    lineage_refs: [...(approval ? [`env-authority_request-${approval.approvalId.replace(/^apr-/, "")}`] : []), ...(carry ? carry.lineage : [])],
+    provenance: [{ provenance_id: provenanceId, source_system_refs: ["cognate"], producer_refs: ["cognate"], production_method: "governed_operation", created_at: at }],
+    authority: [{ authority_id: `auth-${operationId}`, subject_actor_ref: d.subject }],
+    transformations: [{ transformation_id: `tr-${operationId}`, transformation_type: d.kind === "capability" ? "capability_invocation" : "action_invocation" }],
+    references: [{ ref_id: `ref-${operationId}`, ref_type: "artifact_id", target_uri_or_id: d.resource, availability_status: "available", integrity_status: "verifiable" }],
+    states: [{ state_id: `st-${operationId}`, state_type: "declared_state", subject_ref: `operation:${operationId}` }],
+    extensions: {
+      "cep.profile": { profile_id: REQUEST_PROFILE, profile_version: PROFILE_VERSION },
+      [REQUEST_PROFILE]: { operation_id: operationId, correlation_id: d.correlation || operationId, operation_kind: d.kind, operation_name: d.name, resource_id: d.resource, ...(approval ? { approval_id: approval.approvalId } : {}), ...(carry ? { transition_ref: carry.transitionLedgerEntry } : {}) },
+    },
+  };
+  return { envelope, operationId };
+}
+
+/**
+ * A request to move work from one immutable semantic world to another (migration Stage 10).
+ *
+ * Cognate never chooses a world: both refs are given by whoever calls, and an allow only means SEA-Forge
+ * recorded the move. Cognate's pinned world changes by reconfiguration after the move appears in
+ * `SeaForgeAuthority.listTransitions()`, never as a side effect of asking.
+ */
+export interface WorldTransitionRequest {
+  /** World the work is pinned to today (a `world:<name>@sha256:<digest>`; an alias is not accepted). */
+  readonly sourceWorldRef: string;
+  readonly targetWorldRef: string;
+  readonly kind: "semantic_change" | "source_edit_only" | "compiler_upgrade" | "migration";
+  readonly reason: string;
+  /** The sender's claim. SEA-Forge cannot verify it unless the semantic closures are equal, and records `unknown` without one. */
+  readonly compatibility?: "compatible" | "backward_compatible" | "breaking" | "unknown";
+  readonly caller: { readonly tenant: string; readonly actor: { readonly id: string } };
+  readonly semanticDiffRef?: string;
+  readonly migrationRef?: string;
+  readonly evidenceRefs?: readonly string[];
+}
+
+/** The `authority_request` for one world transition. The approval is bound to the TARGET, via `resource_id`. */
+export function buildTransitionRequest(request: WorldTransitionRequest, now: Date = new Date(), approval?: ApprovalReference): { envelope: Obj; operationId: string } {
+  const built = buildEnvelope({ kind: "action", name: "transition", resource: request.targetWorldRef, subject: `actor:${request.caller.tenant}/${request.caller.actor.id}`, correlation: "" }, request.sourceWorldRef, now, approval);
+  const extensions = built.envelope.extensions as Obj;
+  const base = extensions[REQUEST_PROFILE] as Obj;
+  extensions[REQUEST_PROFILE] = { ...base, operation_kind: "world_transition", operation_name: "transition", resource_id: request.targetWorldRef };
+  extensions["godspeed.world_transition"] = {
+    target_world_ref: request.targetWorldRef,
+    transition_kind: request.kind,
+    reason: request.reason,
+    ...(request.compatibility ? { compatibility: request.compatibility } : {}),
+    ...(request.semanticDiffRef ? { semantic_diff_ref: request.semanticDiffRef } : {}),
+    ...(request.migrationRef ? { migration_ref: request.migrationRef } : {}),
+    ...(request.evidenceRefs?.length ? { evidence_refs: [...request.evidenceRefs] } : {}),
+  };
+  built.envelope.transformations = [{ transformation_id: `tr-${built.operationId}`, transformation_type: "world_transition" }];
+  built.envelope.references = [{ ref_id: `ref-${built.operationId}`, ref_type: "world_ref", target_uri_or_id: request.targetWorldRef, availability_status: "available", integrity_status: "verifiable" }];
+  return built;
+}
+
+/** One move SEA-Forge allowed and recorded, as read back from its ledger. */
+export interface RecordedTransition {
+  readonly operationId: string;
+  readonly decisionId: string;
+  /** The ledger entry of the allow; what a request cites (`CarriedWork`) to carry earlier work across the move. */
+  readonly ledgerEntry: string;
+  readonly approvalId?: string;
+  readonly sourceWorldRef: string;
+  readonly targetWorldRef: string;
+  readonly kind: string;
+  readonly compatibility: string;
+  readonly semanticClosureEqual: boolean;
+}
+
+const unknown = (reason: string): GovernanceDecision => ({ disposition: "unknown", reason });
+
+/**
+ * Accept a response only if it is a well-formed authority_decision for exactly this request and world.
+ * Never throws; every defect is an `unknown` disposition.
+ */
+export function interpretDecision(response: unknown, sent: { envelope: Obj; operationId: string }, worldRef: string, approval?: ApprovalReference): GovernanceDecision {
+  if (!isObj(response)) return unknown("authority response is not an object");
+  if (response.ok !== true) return unknown(`authority refused: ${str(response.error_class) ?? "error"}: ${str(response.error) ?? "no detail"}`);
+  const envelope = response.envelope;
+  if (!isObj(envelope)) return unknown("authority response carries no envelope");
+  if (envelope.envelope_kind !== "authority_decision") return unknown("response envelope is not an authority_decision");
+  const extensions = isObj(envelope.extensions) ? envelope.extensions : {};
+  const profile = isObj(extensions["cep.profile"]) ? extensions["cep.profile"] : {};
+  if (profile.profile_id !== DECISION_PROFILE || profile.profile_version !== PROFILE_VERSION) return unknown("response declares the wrong profile");
+  const scope = isObj(envelope.scope) ? envelope.scope : {};
+  if (scope.world_ref !== worldRef) return unknown("decision is for a different world than the one requested");
+  const ext = extensions[DECISION_PROFILE];
+  if (!isObj(ext)) return unknown("decision extension missing");
+  if (ext.request_ref !== sent.envelope.envelope_id || ext.operation_id !== sent.operationId) return unknown("decision is not for this request");
+  if (!Array.isArray(envelope.lineage_refs) || !envelope.lineage_refs.includes(sent.envelope.envelope_id)) return unknown("decision lineage does not include this request");
+  const decision = str(ext.decision);
+  if (!decision || !DECISIONS.has(decision)) return unknown("decision is not a recognized disposition");
+
+  // The approval a decision names must be the one we relied on; an escalation names the one to wait for.
+  const namedApproval = str(ext.approval_id);
+  if (approval && namedApproval !== undefined && namedApproval !== approval.approvalId) return unknown("decision names a different approval than the one relied on");
+  if (approval && decision === "allow" && ext.approval_used === true && namedApproval !== approval.approvalId) return unknown("approved allow does not name the approval relied on");
+
+  const decisionRef = str(ext.ledger_entry) ?? str(ext.decision_id);
+  const decisionEnvelopeId = str(envelope.envelope_id);
+  if (decision === "allow" && !decisionEnvelopeId) return unknown("allow decision carries no envelope id");
+  const authority: AuthorityReference | undefined = decisionEnvelopeId
+    ? { operationId: sent.operationId, requestEnvelopeId: String(sent.envelope.envelope_id), decisionEnvelopeId, worldRef, ...(decisionRef ? { decisionRef } : {}) }
+    : undefined;
+  const base = { reason: `sea-forge decided ${decision}${str(ext.decision_id) ? ` (${str(ext.decision_id)})` : ""}`, ...(decisionRef ? { decisionRef } : {}), ...(authority ? { authority } : {}) };
+  if (decision === "escalate" && namedApproval) {
+    const expires = str(ext.approval_expires_at) ? Date.parse(str(ext.approval_expires_at)!) : Number.NaN;
+    return { disposition: "escalate", ...base, escalation: { approvalId: namedApproval, ...(Number.isFinite(expires) ? { expiresAt: expires } : {}) } };
+  }
+  if (!CONSTRAINED.has(decision)) return { disposition: decision as GovernanceDecision["disposition"], ...base };
+
+  const policyBasis = strings(ext.policy_basis);
+  const rawConstraints = Array.isArray(envelope.constraints) ? envelope.constraints : [];
+  const constraints: GovernanceConstraint[] = [];
+  for (const item of rawConstraints) {
+    if (!isObj(item) || !str(item.constraint_type) || !str(item.description)) return unknown("constraint record is malformed");
+    constraints.push({ type: str(item.constraint_type)!, value: str(item.description)! });
+  }
+  if (!policyBasis?.length || constraints.length === 0) return unknown(`${decision} without constraints and policy basis`);
+  const controls = strings(ext.compensating_controls);
+  if (decision === "degraded" && !controls?.length) return unknown("degraded without compensating controls");
+  return { disposition: decision as GovernanceDecision["disposition"], ...base, policyBasis, constraints, ...(controls ? { compensatingControls: controls } : {}) };
+}
+
+/** One NDJSON request/response exchange over a Unix socket. Rejects on timeout, close, or oversize. */
+export function exchange(socketPath: string, request: unknown, timeoutMs: number, maxBytes: number): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let buffered = "";
+    let settled = false;
+    const finish = (error: Error | null, value?: unknown) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        socket?.end();
+      } catch {}
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const timer = setTimeout(() => finish(new Error(`no response within ${timeoutMs} ms`)), timeoutMs);
+    let socket: Awaited<ReturnType<typeof Bun.connect>> | undefined;
+    Bun.connect({
+      unix: socketPath,
+      socket: {
+        open(s) {
+          s.write(`${JSON.stringify(request)}\n`);
+        },
+        data(_s, chunk) {
+          buffered += chunk.toString("utf8");
+          if (buffered.length > maxBytes) return finish(new Error("response exceeds size limit"));
+          const newline = buffered.indexOf("\n");
+          if (newline < 0) return;
+          try {
+            finish(null, JSON.parse(buffered.slice(0, newline)));
+          } catch {
+            finish(new Error("response is not valid JSON"));
+          }
+        },
+        close() {
+          finish(new Error("connection closed before a response"));
+        },
+        error(_s, error) {
+          finish(error);
+        },
+      },
+    }).then(
+      (s) => {
+        socket = s;
+        if (settled) s.end();
+      },
+      (error: unknown) => finish(error instanceof Error ? error : new Error(String(error))),
+    );
+  });
+}
+
+export type EvidenceReceipt =
+  | { readonly ok: true; readonly operationId: string; readonly envelopeId: string; readonly items: number; readonly ledgerEntry: string }
+  | { readonly ok: false; readonly errorClass: string; readonly error: string };
+
+/** SEA-Forge's governed acceptance of an operation. Never derived from execution or from RealityTrace's own judgment. */
+export type SettlementReceipt =
+  | { readonly ok: true; readonly status: "settled" | "unsettled" | "rejected"; readonly final: boolean; readonly replayed: boolean; readonly envelope: Obj; readonly ledgerEntry: string }
+  | { readonly ok: false; readonly errorClass: string; readonly error: string };
+
+/** Accept a settlement response only if it is demonstrably the settlement of this operation in this world. */
+export function interpretSettlement(response: unknown, operationId: string, worldRef: string): SettlementReceipt {
+  const refuse = (error: string): SettlementReceipt => ({ ok: false, errorClass: "invalid_settlement", error });
+  if (!isObj(response)) return { ok: false, errorClass: "malformed_response", error: "response is not an object" };
+  if (response.ok !== true) return { ok: false, errorClass: str(response.error_class) ?? "error", error: str(response.error) ?? "no detail" };
+  const envelope = response.envelope;
+  if (!isObj(envelope) || envelope.envelope_kind !== "settlement_packet") return refuse("response carries no settlement_packet");
+  const extensions = isObj(envelope.extensions) ? envelope.extensions : {};
+  const profile = isObj(extensions["cep.profile"]) ? extensions["cep.profile"] : {};
+  if (profile.profile_id !== "godspeed.settlement_packet" || profile.profile_version !== PROFILE_VERSION) return refuse("response declares the wrong profile");
+  const scope = isObj(envelope.scope) ? envelope.scope : {};
+  if (scope.world_ref !== worldRef) return refuse("settlement is for a different world");
+  const ext = extensions["godspeed.settlement_packet"];
+  if (!isObj(ext) || ext.operation_id !== operationId) return refuse("settlement is for a different operation");
+  const status = response.status;
+  if (status !== "settled" && status !== "unsettled" && status !== "rejected") return refuse("settlement status is not recognized");
+  // The packet and the summary must agree: a summary cannot be upgraded past what the packet says.
+  if (ext.overall_status !== status) return refuse("settlement summary disagrees with its packet");
+  return { ok: true, status, final: response.final === true, replayed: response.replayed === true, envelope, ledgerEntry: String(response.ledger_entry) };
+}
+
+export class SeaForgeAuthority implements GovernanceAuthority {
+  private readonly actor: { actor_id: string; role: string };
+  private readonly timeoutMs: number;
+  private readonly maxBytes: number;
+
+  constructor(private readonly options: SeaForgeAuthorityOptions) {
+    this.actor = { ...(options.actor ?? { actor_id: "cognate-service", role: "service" }) };
+    this.timeoutMs = options.timeoutMs ?? 5_000;
+    this.maxBytes = options.maxResponseBytes ?? 256 * 1024;
+  }
+
+  async decide(operation: GovernedOperation, worldRef: string, approval?: ApprovalReference, carry?: CarriedWork): Promise<GovernanceDecision> {
+    const sent = buildAuthorityRequest(operation, worldRef, new Date(), approval, carry);
+    let response: unknown;
+    try {
+      response = await exchange(this.options.socketPath, { verb: "authority_request", envelope: sent.envelope, request_id: sent.operationId, actor: this.actor }, this.timeoutMs, this.maxBytes);
+    } catch (error) {
+      return unknown(`sea-forge unreachable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return interpretDecision(response, sent, worldRef, approval);
+  }
+
+  /**
+   * Ask SEA-Forge to move work from one world to another. The answer is the usual governed disposition: a move
+   * across a semantic change comes back `escalate` whatever policy says, and only an approved retry is allowed.
+   * Nothing changes in Cognate on an allow; read the move back with `listTransitions`.
+   */
+  async requestWorldTransition(request: WorldTransitionRequest, approval?: ApprovalReference): Promise<GovernanceDecision> {
+    const sent = buildTransitionRequest(request, new Date(), approval);
+    let response: unknown;
+    try {
+      response = await exchange(this.options.socketPath, { verb: "authority_request", envelope: sent.envelope, request_id: sent.operationId, actor: this.actor }, this.timeoutMs, this.maxBytes);
+    } catch (error) {
+      return unknown(`sea-forge unreachable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return interpretDecision(response, sent, request.sourceWorldRef, approval);
+  }
+
+  /** Every move SEA-Forge allowed, oldest first. Malformed rows are dropped, never guessed at; failure is an empty list. */
+  async listTransitions(): Promise<RecordedTransition[]> {
+    let response: unknown;
+    try {
+      response = await exchange(this.options.socketPath, { verb: "authority_transitions" }, this.timeoutMs, this.maxBytes);
+    } catch {
+      return [];
+    }
+    const rows = isObj(response) && response.ok === true && Array.isArray(response.transitions) ? response.transitions : [];
+    const out: RecordedTransition[] = [];
+    for (const row of rows) {
+      if (!isObj(row) || !isObj(row.record)) continue;
+      const rec = row.record;
+      const operationId = str(row.operation_id);
+      const decisionId = str(row.decision_id);
+      const ledgerEntry = str(row.ledger_entry);
+      const source = str(rec.source_world_ref);
+      const target = str(rec.target_world_ref);
+      const kind = str(rec.transition_kind);
+      const compatibility = str(rec.compatibility);
+      if (!operationId || !decisionId || !ledgerEntry || !source || !target || !kind || !compatibility || typeof rec.semantic_closure_equal !== "boolean" || source === target) continue;
+      out.push({ operationId, decisionId, ledgerEntry, ...(str(row.approval_id) ? { approvalId: str(row.approval_id)! } : {}), sourceWorldRef: source, targetWorldRef: target, kind, compatibility, semanticClosureEqual: rec.semantic_closure_equal });
+    }
+    return out;
+  }
+
+  /**
+   * Submit a GodSpeed `evidence_packet` (built from RealityTrace's recorded evidence) for an operation SEA-Forge
+   * allowed. Recording evidence settles nothing.
+   */
+  async submitEvidence(packet: Obj): Promise<EvidenceReceipt> {
+    // SEA-Forge binds a request id to its first payload. Deriving the id from the payload hash as well means a
+    // replay of the same packet dedupes, while a different (e.g. tampered) packet under the same envelope id
+    // can neither reuse nor poison the id of the genuine one.
+    const requestId = `evidence:${String(packet.envelope_id)}:${createHash("sha256").update(JSON.stringify(packet)).digest("hex").slice(0, 16)}`;
+    let response: unknown;
+    try {
+      response = await exchange(this.options.socketPath, { verb: "authority_evidence", envelope: packet, request_id: requestId, actor: this.actor }, this.timeoutMs, this.maxBytes);
+    } catch (error) {
+      return { ok: false, errorClass: "unreachable", error: error instanceof Error ? error.message : String(error) };
+    }
+    if (!isObj(response)) return { ok: false, errorClass: "malformed_response", error: "response is not an object" };
+    if (response.ok !== true) return { ok: false, errorClass: str(response.error_class) ?? "error", error: str(response.error) ?? "no detail" };
+    return { ok: true, operationId: String(response.operation_id), envelopeId: String(response.envelope_id), items: Number(response.items), ledgerEntry: String(response.ledger_entry) };
+  }
+
+  /**
+   * Ask SEA-Forge to settle an operation from the evidence it holds. The answer is accepted only if it is a
+   * settlement_packet for this operation and world; anything else is refused. `unsettled` is a normal answer.
+   */
+  async settle(operationId: string, worldRef: string): Promise<SettlementReceipt> {
+    // One request id per (operation, call): settlement replays are SEA-Forge's to recognise, not ours to cache.
+    const requestId = `settle:${operationId}:${randomUUID()}`;
+    let response: unknown;
+    try {
+      response = await exchange(this.options.socketPath, { verb: "authority_settle", operation_id: operationId, request_id: requestId, actor: this.actor }, this.timeoutMs, this.maxBytes);
+    } catch (error) {
+      return { ok: false, errorClass: "unreachable", error: error instanceof Error ? error.message : String(error) };
+    }
+    return interpretSettlement(response, operationId, worldRef);
+  }
+
+  /** Where an escalation stands. Only used to decide when to try again; an `approved` here never allows anything. */
+  async approvalState(approvalId: string): Promise<ApprovalState> {
+    try {
+      const response = await exchange(this.options.socketPath, { verb: "authority_approvals" }, this.timeoutMs, this.maxBytes);
+      const approvals = isObj(response) && Array.isArray(response.approvals) ? response.approvals : [];
+      const found = approvals.find((a) => isObj(a) && a.approval_id === approvalId);
+      const state = isObj(found) ? str(found.state) : undefined;
+      return state === "pending" || state === "approved" || state === "rejected" || state === "expired" || state === "used" ? state : "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+}