@godspeedai/cognate-protocol-connect 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @godspeedai/cognate-protocol-connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Maps `RuntimeService` (runtime-api) to the generated Connect service `cognate.v1.RuntimeService` (`@godspeedai/cognate-proto`), independent of the HTTP server.
+
+- `registerRuntimeService(router, service, { authenticate, maxJsonDepth })` — server routes. The caller comes from request headers via `authenticate`, never from message bodies (§32). `google.protobuf.Value` inputs are depth-checked.
+- `createRemoteRuntimeService(transport, tokenFor)` — a `RuntimeService` over any Connect transport; ServiceError codes round-trip exactly.
+- `errorCodes` — ServiceError ↔ Connect code table.
+
+Proof: `test/service.test.ts` runs the same service conformance kit as the in-process runtime, over JSON and binary encodings (CG-WIR-003, §40.G).
+
+Mode matrix (DEBT-004): unary and server streaming only; client/bidi streaming are not offered.

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@godspeedai/cognate-protocol-connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Maps RuntimeService to the generated Connect service (server routes and a remote client). Transport-agnostic.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/protocol-connect"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "2.15.0",
+    "@godspeedai/cognate-events": "^0.1.1",
+    "@godspeedai/cognate-kernel-api": "^0.1.1",
+    "@godspeedai/cognate-proto": "^0.1.1",
+    "@godspeedai/cognate-runtime-api": "^0.1.1",
+    "@connectrpc/connect": "2.2.0"
+  },
+  "devDependencies": {
+    "@godspeedai/cognate-protocol-connect-bun": "workspace:*",
+    "@godspeedai/cognate-runtime-bun": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,715 @@
+// Maps the transport-independent RuntimeService (spec §22, ADR-0011) onto the generated Connect
+// service. Caller identity always comes from the transport's authenticator (spec §32), never from
+// message bodies. The same ServiceError code round-trips through the wire in both directions.
+import { fromJson, toJson } from "@bufbuild/protobuf";
+import { type Value, ValueSchema } from "@bufbuild/protobuf/wkt";
+import type { ConnectRouter, HandlerContext, Transport } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import {
+  type Continuation,
+  ContinuationAction as PbContinuationAction,
+  ContinuationStatus as PbContinuationStatus,
+  type Event as PbEvent,
+  type JsonPatchOp as PbJsonPatchOp,
+  ResolveOutcome as PbResolveOutcome,
+  type Run,
+  type RemoteCapabilityOffer as PbRemoteCapabilityOffer,
+  RunStatus as PbRunStatus,
+  RuntimeService as RuntimeServiceDesc,
+  type SemanticRef as PbSemanticRef,
+  type StateUpdate as PbStateUpdate,
+} from "@godspeedai/cognate-proto";
+import type { Json, StoredEvent } from "@godspeedai/cognate-events";
+import type { SemanticRef } from "@godspeedai/cognate-kernel-api";
+import type { Caller, ContinuationView, JsonPatchOp, RemoteCapabilityOffer, RunView, RuntimeService, ServiceErrorCode, StateUpdate } from "@godspeedai/cognate-runtime-api";
+import { ServiceError } from "@godspeedai/cognate-runtime-api";
+
+export interface HandlerOptions {
+  /** Establish the caller from request headers (e.g. `authorization: Bearer …`); undefined → unauthenticated. */
+  readonly authenticate: (headers: Headers) => Caller | undefined | Promise<Caller | undefined>;
+  /** Maximum nesting depth of JSON values (google.protobuf.Value) accepted from clients. */
+  readonly maxJsonDepth: number;
+}
+
+/** The ServiceError ↔ Connect code table (exported for tests and other transports). */
+export const errorCodes: Readonly<Record<ServiceErrorCode, number>> = {
+  not_found: Code.NotFound,
+  permission_denied: Code.PermissionDenied,
+  invalid_argument: Code.InvalidArgument,
+  failed_precondition: Code.FailedPrecondition,
+  unavailable: Code.Unavailable,
+  deadline_exceeded: Code.DeadlineExceeded,
+  already_exists: Code.AlreadyExists,
+  unauthenticated: Code.Unauthenticated,
+  resource_exhausted: Code.ResourceExhausted,
+};
+
+const codeToServiceError: ReadonlyMap<number, ServiceErrorCode> = new Map(
+  (Object.entries(errorCodes) as [ServiceErrorCode, number][]).map(([code, connectCode]) => [connectCode, code]),
+);
+
+// ── JSON ↔ google.protobuf.Value ────────────────────────────────────────────────
+
+function jsonToValue(json: Json): Value {
+  return fromJson(ValueSchema, json as never);
+}
+
+function valueToJson(value: Value | undefined): Json {
+  // An absent field, or a Value with no oneof case set (e.g. a bare object literal handed to the
+  // generated client's `create()` for a `google.protobuf.Value` field, which does not coerce plain
+  // JSON the way it does for `Struct`/`ListValue` fields), is treated as JSON null rather than
+  // raising `@bufbuild/protobuf`'s "must have a value" error.
+  if (value === undefined || value.kind.case === undefined) return null;
+  return toJson(ValueSchema, value) as Json;
+}
+
+function semanticRefInit(ref: SemanticRef | undefined) {
+  if (!ref) return undefined;
+  return { namespace: ref.namespace, id: ref.id, kind: ref.kind ?? "", source: { uri: ref.source.uri, digest: ref.source.digest }, projectionVersion: ref.projectionVersion };
+}
+
+function semanticRefFromWire(ref: PbSemanticRef | undefined): SemanticRef | undefined {
+  if (!ref) return undefined;
+  return { namespace: ref.namespace, id: ref.id, kind: ref.kind || undefined, source: { uri: ref.source?.uri ?? "", digest: ref.source?.digest ?? "" }, projectionVersion: ref.projectionVersion };
+}
+
+function jsonDepth(value: unknown): number {
+  if (value === null || typeof value !== "object") return 0;
+  const values = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
+  let max = 0;
+  for (const v of values) max = Math.max(max, jsonDepth(v));
+  return values.length === 0 ? 1 : 1 + max;
+}
+
+/** Decode an incoming Value and enforce the configured depth bound (spec §32). */
+function decodeValue(value: Value | undefined, maxJsonDepth: number): Json {
+  const json = valueToJson(value);
+  if (jsonDepth(json) > maxJsonDepth) {
+    throw new ConnectError(`value exceeds maximum JSON depth of ${maxJsonDepth}`, Code.InvalidArgument);
+  }
+  return json;
+}
+
+// ── uint64 ↔ number ───────────────────────────────────────────────────────────────
+
+const toNumber = (v: bigint | undefined): number | undefined => (v === undefined ? undefined : Number(v));
+const toBigInt = (v: number | null | undefined): bigint | undefined => (v === null || v === undefined ? undefined : BigInt(Math.trunc(v)));
+
+// ── enums ↔ string unions ──────────────────────────────────────────────────────────
+
+const runStatusToProto: Record<RunView["status"], PbRunStatus> = {
+  running: PbRunStatus.RUNNING,
+  waiting: PbRunStatus.WAITING,
+  completed: PbRunStatus.COMPLETED,
+  failed: PbRunStatus.FAILED,
+  cancelled: PbRunStatus.CANCELLED,
+};
+const runStatusFromProto: Record<number, RunView["status"]> = {
+  [PbRunStatus.RUNNING]: "running",
+  [PbRunStatus.WAITING]: "waiting",
+  [PbRunStatus.COMPLETED]: "completed",
+  [PbRunStatus.FAILED]: "failed",
+  [PbRunStatus.CANCELLED]: "cancelled",
+};
+
+const continuationStatusToProto: Record<ContinuationView["status"], PbContinuationStatus> = {
+  OPEN: PbContinuationStatus.OPEN,
+  RESUMED: PbContinuationStatus.RESUMED,
+  CANCELLED: PbContinuationStatus.CANCELLED,
+  EXPIRED: PbContinuationStatus.EXPIRED,
+  FAILED: PbContinuationStatus.FAILED,
+  BLOCKED: PbContinuationStatus.BLOCKED,
+};
+const continuationStatusFromProto: Record<number, ContinuationView["status"]> = {
+  [PbContinuationStatus.OPEN]: "OPEN",
+  [PbContinuationStatus.RESUMED]: "RESUMED",
+  [PbContinuationStatus.CANCELLED]: "CANCELLED",
+  [PbContinuationStatus.EXPIRED]: "EXPIRED",
+  [PbContinuationStatus.FAILED]: "FAILED",
+  [PbContinuationStatus.BLOCKED]: "BLOCKED",
+};
+
+const continuationActionToProto: Record<"resume" | "cancel", PbContinuationAction> = {
+  resume: PbContinuationAction.RESUME,
+  cancel: PbContinuationAction.CANCEL,
+};
+const continuationActionFromProto: Record<number, "resume" | "cancel"> = {
+  [PbContinuationAction.RESUME]: "resume",
+  [PbContinuationAction.CANCEL]: "cancel",
+};
+
+const resolveOutcomeFromProto: Record<number, "transitioned" | "duplicate" | "already_terminal"> = {
+  [PbResolveOutcome.TRANSITIONED]: "transitioned",
+  [PbResolveOutcome.DUPLICATE]: "duplicate",
+  [PbResolveOutcome.ALREADY_TERMINAL]: "already_terminal",
+};
+const resolveOutcomeToProto: Record<"transitioned" | "duplicate" | "already_terminal", PbResolveOutcome> = {
+  transitioned: PbResolveOutcome.TRANSITIONED,
+  duplicate: PbResolveOutcome.DUPLICATE,
+  already_terminal: PbResolveOutcome.ALREADY_TERMINAL,
+};
+
+// ── message ↔ view conversions ────────────────────────────────────────────────────
+
+function runInit(run: RunView) {
+  return {
+    runId: run.runId,
+    agent: run.agent,
+    tenant: run.tenant,
+    status: runStatusToProto[run.status],
+    input: jsonToValue(run.input),
+    output: jsonToValue(run.output),
+    error: run.error ?? undefined,
+    correlationId: run.correlationId,
+    startedBy: run.startedBy,
+    waitingOn: [...run.waitingOn],
+  };
+}
+
+function runFromWire(run: Run): RunView {
+  return {
+    runId: run.runId,
+    agent: run.agent,
+    tenant: run.tenant,
+    status: runStatusFromProto[run.status] ?? "running",
+    input: valueToJson(run.input),
+    output: valueToJson(run.output),
+    error: run.error ?? null,
+    correlationId: run.correlationId,
+    startedBy: run.startedBy,
+    waitingOn: run.waitingOn,
+  };
+}
+
+function continuationInit(c: ContinuationView) {
+  return {
+    id: c.id,
+    runId: c.runId,
+    type: c.type,
+    status: continuationStatusToProto[c.status],
+    condition: jsonToValue(c.condition),
+    payload: jsonToValue(c.payload),
+    version: BigInt(c.version),
+    expiresAt: c.expiresAt === null ? undefined : BigInt(c.expiresAt),
+  };
+}
+
+function continuationFromWire(c: Continuation): ContinuationView {
+  return {
+    id: c.id,
+    runId: c.runId,
+    type: c.type,
+    status: continuationStatusFromProto[c.status] ?? "OPEN",
+    condition: valueToJson(c.condition),
+    payload: valueToJson(c.payload),
+    version: Number(c.version),
+    expiresAt: c.expiresAt === undefined ? null : Number(c.expiresAt),
+  };
+}
+
+function eventInit(e: StoredEvent) {
+  return {
+    eventId: e.eventId,
+    streamId: e.streamId,
+    streamSequence: BigInt(e.streamSequence),
+    position: BigInt(e.position),
+    eventType: e.eventType,
+    schemaVersion: e.schemaVersion,
+    occurredAt: e.occurredAt,
+    recordedAt: e.recordedAt,
+    tenant: e.tenant,
+    correlationId: e.correlationId,
+    causationId: e.causationId ?? undefined,
+    runId: e.runId ?? undefined,
+    scopeId: e.scopeId,
+    componentId: e.componentId,
+    fiberId: e.fiberId,
+    semanticRef: semanticRefInit(e.semanticRef),
+    payload: jsonToValue(e.payload),
+    metadata: e.metadata,
+    erasure: e.erasure ? { reason: e.erasure.reason, erasedAt: e.erasure.erasedAt } : undefined,
+  };
+}
+
+function eventFromWire(e: PbEvent): StoredEvent {
+  return {
+    eventId: e.eventId,
+    streamId: e.streamId,
+    streamSequence: Number(e.streamSequence),
+    position: Number(e.position),
+    eventType: e.eventType,
+    schemaVersion: e.schemaVersion,
+    occurredAt: e.occurredAt,
+    recordedAt: e.recordedAt,
+    tenant: e.tenant,
+    correlationId: e.correlationId,
+    causationId: e.causationId ?? null,
+    runId: e.runId ?? null,
+    scopeId: e.scopeId,
+    componentId: e.componentId,
+    fiberId: e.fiberId,
+    semanticRef: semanticRefFromWire(e.semanticRef),
+    payload: valueToJson(e.payload),
+    metadata: e.metadata as { readonly [key: string]: Json } | undefined,
+    erasure: e.erasure ? { reason: e.erasure.reason, erasedAt: e.erasure.erasedAt } : undefined,
+  };
+}
+
+// ── shared state (spec §29.1) ───────────────────────────────────────────────────────
+
+function jsonPatchOpInit(op: JsonPatchOp) {
+  return {
+    op: op.op,
+    path: op.path,
+    from: "from" in op ? op.from : undefined,
+    value: jsonToValue("value" in op ? op.value : null),
+  };
+}
+
+function jsonPatchOpFromWire(op: PbJsonPatchOp): JsonPatchOp {
+  const value = valueToJson(op.value);
+  switch (op.op) {
+    case "add":
+      return { op: "add", path: op.path, value };
+    case "replace":
+      return { op: "replace", path: op.path, value };
+    case "remove":
+      return { op: "remove", path: op.path };
+    case "move":
+      return { op: "move", from: op.from ?? "", path: op.path };
+    case "copy":
+      return { op: "copy", from: op.from ?? "", path: op.path };
+    case "test":
+      return { op: "test", path: op.path, value };
+    default:
+      throw new ConnectError(`unknown JSON Patch op "${op.op}"`, Code.InvalidArgument);
+  }
+}
+
+function stateUpdateFieldInit(update: StateUpdate) {
+  if ("snapshot" in update) return { kind: { case: "snapshot" as const, value: jsonToValue(update.snapshot) } };
+  return { kind: { case: "patch" as const, value: { ops: update.patch.map(jsonPatchOpInit) } } };
+}
+
+function stateUpdateFromWire(update: PbStateUpdate | undefined): StateUpdate {
+  if (update?.kind.case === "patch") return { patch: update.kind.value.ops.map(jsonPatchOpFromWire) };
+  return { snapshot: valueToJson(update?.kind.case === "snapshot" ? update.kind.value : undefined) };
+}
+
+function offerInit(offer: RemoteCapabilityOffer) {
+  return {
+    id: offer.id, leaseId: offer.leaseId, agent: offer.agent, scopeId: offer.scopeId,
+    capability: offer.contract.id, contractVersion: offer.contract.version, attributes: jsonToValue(offer.contract.attributes ?? {}),
+    description: offer.description, inputSchema: jsonToValue(offer.inputSchema), outputSchema: offer.outputSchema === undefined ? undefined : jsonToValue(offer.outputSchema), expiresAt: BigInt(offer.expiresAt),
+  };
+}
+
+function offerFromWire(offer: PbRemoteCapabilityOffer): RemoteCapabilityOffer {
+  const attributes = valueToJson(offer.attributes);
+  return {
+    id: offer.id, leaseId: offer.leaseId, agent: offer.agent, scopeId: offer.scopeId,
+    contract: { id: offer.capability, version: offer.contractVersion, ...(attributes && typeof attributes === "object" && !Array.isArray(attributes) ? { attributes: attributes as Readonly<Record<string, Json>> } : {}) },
+    description: offer.description, inputSchema: valueToJson(offer.inputSchema), ...(offer.outputSchema === undefined ? {} : { outputSchema: valueToJson(offer.outputSchema) }), expiresAt: Number(offer.expiresAt),
+  };
+}
+
+// ── error mapping ─────────────────────────────────────────────────────────────────
+
+function throwConnectError(e: unknown): never {
+  if (e instanceof ServiceError) {
+    throw new ConnectError(e.message, errorCodes[e.code]);
+  }
+  throw e;
+}
+
+function throwServiceError(e: unknown): never {
+  if (e instanceof ConnectError) {
+    const code = codeToServiceError.get(e.code) ?? "unavailable";
+    throw new ServiceError(code, e.rawMessage || e.message);
+  }
+  throw e;
+}
+
+/** Race a unary call against the handler's deadline signal (spec §32); the signal is set up by the transport. */
+function withDeadline<T>(context: HandlerContext, work: Promise<T>): Promise<T> {
+  if (context.signal.aborted) {
+    return Promise.reject(new ConnectError("deadline exceeded", Code.DeadlineExceeded));
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new ConnectError("deadline exceeded", Code.DeadlineExceeded));
+    context.signal.addEventListener("abort", onAbort, { once: true });
+    work.then(
+      (v) => {
+        context.signal.removeEventListener("abort", onAbort);
+        resolve(v);
+      },
+      (e) => {
+        context.signal.removeEventListener("abort", onAbort);
+        reject(e);
+      },
+    );
+  });
+}
+
+async function requireCaller(options: HandlerOptions, context: HandlerContext): Promise<Caller> {
+  const caller = await options.authenticate(context.requestHeader);
+  if (!caller) throw new ConnectError("unauthenticated", Code.Unauthenticated);
+  return caller;
+}
+
+/** Register the RuntimeService routes on a Connect router. ServiceError codes map to Connect codes. */
+export function registerRuntimeService(router: ConnectRouter, service: RuntimeService, options: HandlerOptions): void {
+  const depth = options.maxJsonDepth;
+  router.service(RuntimeServiceDesc, {
+    async startRun(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const run = await withDeadline(
+          context,
+          service.startRun(caller, {
+            agent: req.agent,
+            input: decodeValue(req.input, depth),
+            idempotencyKey: req.idempotencyKey,
+            correlationId: req.correlationId,
+            state: req.state !== undefined ? decodeValue(req.state, depth) : undefined,
+          }),
+        );
+        return runInit(run);
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async getRun(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const run = await withDeadline(context, service.getRun(caller, { runId: req.runId }));
+        return runInit(run);
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async cancelRun(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const run = await withDeadline(context, service.cancelRun(caller, { runId: req.runId, reason: req.reason, idempotencyKey: req.idempotencyKey }));
+        return runInit(run);
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async *streamEvents(req, context) {
+      const caller = await requireCaller(options, context);
+      try {
+        const iterable = service.events(caller, {
+          afterPosition: toNumber(req.afterPosition),
+          runId: req.runId,
+          correlationId: req.correlationId,
+          follow: req.follow,
+          signal: context.signal,
+        });
+        for await (const event of iterable) {
+          if (context.signal.aborted) return;
+          yield eventInit(event);
+        }
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async listContinuations(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const status = req.status === PbContinuationStatus.UNSPECIFIED ? undefined : continuationStatusFromProto[req.status];
+        const continuations = await withDeadline(context, service.listContinuations(caller, { runId: req.runId, status }));
+        return { continuations: continuations.map(continuationInit) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async resolveContinuation(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const result = await withDeadline(
+          context,
+          service.resolveContinuation(caller, {
+            continuationId: req.continuationId,
+            action: continuationActionFromProto[req.action] ?? "resume",
+            input: decodeValue(req.input, depth),
+            reason: req.reason,
+            idempotencyKey: req.idempotencyKey,
+            expectedVersion: toNumber(req.expectedVersion),
+          }),
+        );
+        return { outcome: resolveOutcomeToProto[result.outcome], continuation: continuationInit(result.continuation) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async invoke(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const output = await withDeadline(
+          context,
+          service.invoke(caller, { capability: req.capability, input: decodeValue(req.input, depth), correlationId: req.correlationId, idempotencyKey: req.idempotencyKey, deadline: toNumber(req.deadline) }),
+        );
+        return { output: jsonToValue(output) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async getArtifact(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const artifact = await withDeadline(context, service.getArtifact(caller, { artifactId: req.artifactId, representation: req.representation }));
+        return { id: artifact.id, name: artifact.name, mediaType: artifact.mediaType, contentHash: artifact.contentHash, bytes: artifact.bytes };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async readProjection(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const entries = await withDeadline(context, service.readProjection(caller, { name: req.name }));
+        return { entries: entries.map((entry) => ({ key: entry.key, value: jsonToValue(entry.value) })) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async listRuns(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const runs = await withDeadline(context, service.listRuns(caller, { correlationId: req.correlationId, agent: req.agent }));
+        return { runs: runs.map(runInit) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async updateState(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const result = await withDeadline(
+          context,
+          service.updateState(caller, { runId: req.runId, update: stateUpdateFromWire(req.update), idempotencyKey: req.idempotencyKey, expectedVersion: toNumber(req.expectedVersion) }),
+        );
+        return { state: jsonToValue(result.state), version: BigInt(result.version) };
+      } catch (e) {
+        throwConnectError(e);
+      }
+    },
+    async readSharedState(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const result = await withDeadline(context, service.readSharedState(caller, { threadId: req.threadId }));
+        return { state: jsonToValue(result.state), version: BigInt(result.version) };
+      } catch (e) { throwConnectError(e); }
+    },
+    async updateSharedState(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const result = await withDeadline(context, service.updateSharedState(caller, {
+          threadId: req.threadId,
+          update: stateUpdateFromWire(req.update),
+          idempotencyKey: req.idempotencyKey,
+          expectedVersion: toNumber(req.expectedVersion),
+        }));
+        return { state: jsonToValue(result.state), version: BigInt(result.version) };
+      } catch (e) { throwConnectError(e); }
+    },
+    async publishRemoteOffer(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const attributes = decodeValue(req.attributes, depth);
+        if (attributes === null || typeof attributes !== "object" || Array.isArray(attributes)) throw new ConnectError("offer attributes must be an object", Code.InvalidArgument);
+        const offer = await withDeadline(context, service.publishRemoteOffer(caller, { leaseId: req.leaseId, agent: req.agent, contract: { id: req.capability, version: req.contractVersion, attributes: attributes as Readonly<Record<string, Json>> }, description: req.description, inputSchema: decodeValue(req.inputSchema, depth), ...(req.outputSchema === undefined ? {} : { outputSchema: decodeValue(req.outputSchema, depth) }), ttlMs: Number(req.ttlMs) }));
+        return offerInit(offer);
+      } catch (e) { throwConnectError(e); }
+    },
+    async listRemoteOffers(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        const offers = await withDeadline(context, service.listRemoteOffers(caller, { agent: req.agent }));
+        return { offers: offers.map(offerInit) };
+      } catch (e) { throwConnectError(e); }
+    },
+    async revokeRemoteOffer(req, context) {
+      try {
+        const caller = await requireCaller(options, context);
+        await withDeadline(context, service.revokeRemoteOffer(caller, { offerId: req.offerId }));
+        return {};
+      } catch (e) { throwConnectError(e); }
+    },
+  });
+}
+
+/** A RuntimeService backed by a remote Connect endpoint. `tokenFor` supplies the credential that authenticates a caller. */
+export function createRemoteRuntimeService(transport: Transport, tokenFor: (caller: Caller) => string): RuntimeService {
+  const client = createClient(RuntimeServiceDesc, transport);
+  const headersFor = (caller: Caller) => ({ authorization: `Bearer ${tokenFor(caller)}` });
+
+  return {
+    async startRun(caller, request) {
+      try {
+        const run = await client.startRun(
+          {
+            agent: request.agent,
+            input: jsonToValue(request.input),
+            idempotencyKey: request.idempotencyKey,
+            correlationId: request.correlationId,
+            state: request.state !== undefined ? jsonToValue(request.state) : undefined,
+          },
+          { headers: headersFor(caller) },
+        );
+        return runFromWire(run);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async getRun(caller, request) {
+      try {
+        const run = await client.getRun({ runId: request.runId }, { headers: headersFor(caller) });
+        return runFromWire(run);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async cancelRun(caller, request) {
+      try {
+        const run = await client.cancelRun({ runId: request.runId, reason: request.reason, idempotencyKey: request.idempotencyKey }, { headers: headersFor(caller) });
+        return runFromWire(run);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    events(caller, request) {
+      const headers = headersFor(caller);
+      const signal = request.signal;
+      return (async function* () {
+        try {
+          const stream = client.streamEvents(
+            { afterPosition: toBigInt(request.afterPosition), runId: request.runId, correlationId: request.correlationId, follow: request.follow ?? false },
+            { headers, signal },
+          );
+          for await (const event of stream) {
+            yield eventFromWire(event);
+          }
+        } catch (e) {
+          if (signal?.aborted) return;
+          throwServiceError(e);
+        }
+      })();
+    },
+    async listContinuations(caller, request) {
+      try {
+        const response = await client.listContinuations(
+          { runId: request.runId, status: request.status ? continuationStatusToProto[request.status] : PbContinuationStatus.UNSPECIFIED },
+          { headers: headersFor(caller) },
+        );
+        return response.continuations.map(continuationFromWire);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async resolveContinuation(caller, request) {
+      try {
+        const response = await client.resolveContinuation(
+          {
+            continuationId: request.continuationId,
+            action: continuationActionToProto[request.action],
+            input: jsonToValue(request.input ?? null),
+            reason: request.reason,
+            idempotencyKey: request.idempotencyKey,
+            expectedVersion: toBigInt(request.expectedVersion),
+          },
+          { headers: headersFor(caller) },
+        );
+        return { outcome: resolveOutcomeFromProto[response.outcome] ?? "transitioned", continuation: continuationFromWire(response.continuation!) };
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async invoke(caller, request) {
+      try {
+        const response = await client.invoke(
+          { capability: request.capability, input: jsonToValue(request.input), correlationId: request.correlationId, idempotencyKey: request.idempotencyKey, deadline: toBigInt(request.deadline) },
+          { headers: headersFor(caller) },
+        );
+        return valueToJson(response.output);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async getArtifact(caller, request) {
+      try {
+        const artifact = await client.getArtifact({ artifactId: request.artifactId, representation: request.representation }, { headers: headersFor(caller) });
+        return { id: artifact.id, name: artifact.name, mediaType: artifact.mediaType, contentHash: artifact.contentHash, bytes: artifact.bytes };
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async readProjection(caller, request) {
+      try {
+        const response = await client.readProjection({ name: request.name }, { headers: headersFor(caller) });
+        return response.entries.map((entry) => ({ key: entry.key, value: valueToJson(entry.value) }));
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async listRuns(caller, request) {
+      try {
+        const response = await client.listRuns({ correlationId: request.correlationId, agent: request.agent }, { headers: headersFor(caller) });
+        return response.runs.map(runFromWire);
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async updateState(caller, request) {
+      try {
+        const response = await client.updateState(
+          { runId: request.runId, update: stateUpdateFieldInit(request.update), idempotencyKey: request.idempotencyKey, expectedVersion: toBigInt(request.expectedVersion) },
+          { headers: headersFor(caller) },
+        );
+        return { state: valueToJson(response.state), version: Number(response.version) };
+      } catch (e) {
+        throwServiceError(e);
+      }
+    },
+    async readSharedState(caller, request) {
+      try {
+        const response = await client.readSharedState({ threadId: request.threadId }, { headers: headersFor(caller) });
+        return { state: valueToJson(response.state), version: Number(response.version) };
+      } catch (e) { throwServiceError(e); }
+    },
+    async updateSharedState(caller, request) {
+      try {
+        const response = await client.updateSharedState({
+          threadId: request.threadId,
+          update: stateUpdateFieldInit(request.update),
+          idempotencyKey: request.idempotencyKey,
+          expectedVersion: toBigInt(request.expectedVersion),
+        }, { headers: headersFor(caller) });
+        return { state: valueToJson(response.state), version: Number(response.version) };
+      } catch (e) { throwServiceError(e); }
+    },
+    async observe(_caller, _request) {
+      // Observation ingestion is an in-process, mechanism-layer door in v0 — deliberately not exposed over the
+      // public Connect surface (it is a provider/observer privilege, not a remote-caller capability).
+      throw new ServiceError("failed_precondition", "observation ingestion is an in-process door; not available over the remote Connect surface");
+    },
+    async publishRemoteOffer(caller, request) {
+      try {
+        const offer = await client.publishRemoteOffer({ leaseId: request.leaseId, agent: request.agent, capability: request.contract.id, contractVersion: request.contract.version, attributes: jsonToValue(request.contract.attributes ?? {}), description: request.description, inputSchema: jsonToValue(request.inputSchema), outputSchema: request.outputSchema === undefined ? undefined : jsonToValue(request.outputSchema), ttlMs: BigInt(request.ttlMs) }, { headers: headersFor(caller) });
+        return offerFromWire(offer);
+      } catch (e) { throwServiceError(e); }
+    },
+    async listRemoteOffers(caller, request) {
+      try {
+        const response = await client.listRemoteOffers({ agent: request.agent }, { headers: headersFor(caller) });
+        return response.offers.map(offerFromWire);
+      } catch (e) { throwServiceError(e); }
+    },
+    async revokeRemoteOffer(caller, request) {
+      try {
+        await client.revokeRemoteOffer({ offerId: request.offerId }, { headers: headersFor(caller) });
+      } catch (e) { throwServiceError(e); }
+    },
+  };
+}