@openwop/openwop 1.9.0 → 2.0.0

package/src/types.ts

@@ -11,6 +11,8 @@
  * rather than relying on the SDK to refuse unknown values.
  */
 
+import type { CapabilityFamilyKey, ErrorCode } from './generated.js';
+
 /** Run statuses per `RunSnapshot.status` in OpenAPI. */
 export type RunStatus =
   | 'pending'
@@ -27,176 +29,6 @@ export type RunStatus =
   | 'cancelling'
   | 'cancelled';
 
-export interface Capabilities {
-  protocolVersion: string;
-  supportedEnvelopes: readonly string[];
-  schemaVersions: Record<string, number>;
-  limits: {
-    clarificationRounds: number;
-    schemaRounds: number;
-    envelopesPerTurn: number;
-    maxNodeExecutions?: number;
-    /** RFC 0058. Engine-side wall-clock ceiling per run (ms); upper bound for `RunConfigurable.runTimeoutMs`. */
-    maxRunDurationMs?: number;
-    /** RFC 0058. Engine-side agent-loop iteration ceiling; upper bound for `RunConfigurable.maxLoopIterations`. */
-    maxLoopIterations?: number;
-    /** RFC 0094 §H. Maximum REST request body size (bytes) the host
-     *  accepts. Hosts that advertise it MUST enforce it. */
-    maxRequestBodyBytes?: number;
-  };
-  /** RFC 0094 §H. gRPC transport advertisement per `grpc-transport.md`
-   *  §"Capability advertisement". Absent ⇒ the host exposes no gRPC
-   *  transport. A host that exposes the gRPC surface advertises this
-   *  block AND includes `'grpc'` in `supportedTransports`. REST + SSE
-   *  remain exposed regardless. */
-  grpc?: {
-    /** Toggle — `true` when the gRPC surface is live. */
-    supported: boolean;
-    /** Full URI: `grpc://` (cleartext, intra-trusted-network only) OR
-     *  `grpcs://` (TLS). Hosts SHOULD require TLS in production. */
-    endpoint?: string;
-    /** Canonical service name. v1 hosts MUST use `openwop.v1.Engine`. */
-    service: 'openwop.v1.Engine';
-    /** TLS posture. Production hosts MUST set `'required'`. */
-    tls: 'required' | 'optional' | 'disabled';
-  };
-  /** RFC 0101. Multi-party group-conversation advertisement. Absent ⇒ the
-   *  host does not support N agents co-participating in one shared
-   *  transcript (the single user + single driving agent shape of RFC 0005
-   *  remains). When `supported: true`, the host honors the additive
-   *  `participants: AgentRef[]` roster on `conversation.opened` and the
-   *  conditionally-required per-turn `speakerId` on `role: 'agent'`
-   *  conversation turns — advertising `supported: true` without enforcing
-   *  both is a dishonest claim (`OPENWOP_REQUIRE_BEHAVIOR=true` fails it). */
-  multiPartyConversation?: {
-    /** Toggle — `true` when the host supports multi-party conversations. */
-    supported: boolean;
-    /** Upper bound on `participants[]` size the host accepts. Absent ⇒
-     *  host-defined / unbounded. */
-    maxParticipants?: number;
-  };
-  /** RFC 0100. Host exposes itself as an A2A (Agent2Agent) agent. `supported`
-   *  alone ⇒ the synchronous `message/send` → poll `tasks/get` round-trip
-   *  (`a2a-integration.md`). The optional flags gate the RFC 0100 async/durable
-   *  additions. Absent ⇒ no A2A advertisement. */
-  a2a?: {
-    /** Host exposes itself as an A2A agent. */
-    supported: boolean;
-    /** A2A 0.3 well-known agent card URL (`/.well-known/agent-card.json`). */
-    agentCardUrl: string;
-    /** `message/stream` + `tasks/resubscribe` (RFC 0100 §3 resubscribe re-attach). */
-    streaming?: boolean;
-    /** A2A push-notification config (RFC 0100 §4); a caller-supplied
-     *  `pushConfig.url` is SSRF-validated (`a2a-push-egress-ssrf`). */
-    pushNotifications?: boolean;
-    /** RFC 0100 §2. Host persists the projected `A2ATaskState` per backing run;
-     *  `tasks/get` returns live state after disconnect. Absent/false ⇒
-     *  synchronous round-trip only. */
-    durableTasks?: boolean;
-  };
-  /** RFC 0109. Host stamps the optional non-secret `agent.model`
-   *  (`{ provider, model }`) on `role:'agent'` conversation turns, recording
-   *  which model produced the turn (read verbatim on `:fork`). Absent ⇒ no
-   *  provenance; the host omits `agent.model`. */
-  conversationTurnModelProvenance?: {
-    /** Toggle — `true` when the host stamps `agent.model`. */
-    supported: boolean;
-  };
-  /** RFC 0110. Host emits the ephemeral `channel.presence` RunEvent (online +
-   *  per-member typing) for `type:'channel'` conversations. Presence is live
-   *  state — the host never persists it to the replayable event log and it
-   *  never affects replay / `:fork`. Membership-gated (default-deny, CTI-1).
-   *  Absent ⇒ no presence. */
-  channelPresence?: {
-    /** Toggle — `true` when the host emits `channel.presence`. */
-    supported: boolean;
-  };
-  /** Capability advertisement for the host AI-proxy (`aiProviders` in
-   *  `capabilities.md`). Absent ⇒ the host advertises no AI-proxy surface.
-   *  Carries BYOK policy plus the RFC 0105/0106/0108 self-hosted / speech /
-   *  real-time-voice flags. The wire object MAY carry additional fields
-   *  (`input`, `authModes`, `maxInlineMediaBytes`) not modeled here. */
-  aiProviders?: AIProvidersCapability;
-  /** RFC 0104. Portable HITL approver-routing advertisement. When
-   *  `approverRouting.supported`, the host honors the OPTIONAL, ADVISORY
-   *  `approverGroupRefs` / `approverRoleRefs` / `audience` fields on the
-   *  `kind:'approval'` interrupt payload (the SDK carries the interrupt
-   *  payload opaquely as `data`, so those advisory fields ride that opaque
-   *  object), resolves the advertised `refKinds` against its own RBAC, and
-   *  ENFORCES eligibility at resolve time. Absent ⇒ the host ignores them. */
-  interrupt?: {
-    approverRouting?: {
-      /** Host honors the RFC 0104 approver-routing fields. */
-      supported: boolean;
-      /** Ref kinds the host actually resolves: `'group'` ⇒ honors
-       *  `approverGroupRefs`, `'role'` ⇒ honors `approverRoleRefs`. Absent ⇒
-       *  advisory-only passthrough (the host resolves neither). */
-      refKinds?: readonly ('group' | 'role')[];
-      /** Host honors the `audience` notification-targeting override.
-       *  Absent/`false` ⇒ the host notifies the resolved eligible union. */
-      audience?: boolean;
-    };
-  };
-  /** RFC 0007 + RFC 0118. Top-level `core.dispatch` capability descriptors
-   *  (`capabilities.md` §`dispatch`). This is the discovery surface for
-   *  parallel sub-workflow fan-out/join. NOTE: distinct from the legacy
-   *  boolean {@link AgentsCapability.dispatch} — `dispatch.supported` here
-   *  carries the SAME "host implements the `core.dispatch` Core typeId"
-   *  meaning, exposed top-level per `capabilities.md` (the corpus advertises
-   *  it both nested under `agents` and at the doc root; absent ⇒ the host
-   *  advertises no top-level dispatch descriptors). Read-only. */
-  dispatch?: DispatchCapability;
-  /** RFC 0117 (amended by RFC 0119). Host loads SIGNED, SANDBOXED front-end
-   *  plugin packs (`kind:"frontend-plugin"`) in an origin/execution-isolated
-   *  sandbox and talks to them over the closed `ui-plugin/1` host-RPC boundary
-   *  (`capabilities.md` §`uiPlugins`). This is the DISCOVERY surface only — the
-   *  `ui-plugin/1` RPC envelope + the `frontend-plugin` manifest are a
-   *  renderer/registry concern the SDK does not model (as with the RFC 0102
-   *  A2UI `surface` and RFC 0071 pack manifests). Absent ⇒ the host loads no
-   *  plugin packs (graceful degradation to RFC 0071 host rendering). Read-only. */
-  uiPlugins?: UiPluginsCapability;
-  /** RFC 0113. Agent-memory capability descriptors. `injectionBudget` advertises
-   *  that the host honors `MemoryListOptions.tokenBudget` (a token-bounded
-   *  prefix of the ranked, SR-1-redacted, single-tenant entry list). Absent ⇒
-   *  a supplied `tokenBudget` is ignored (today's `limit`/`tag` behavior).
-   *  Read-only; the wire `memory` block MAY carry other descriptors not modeled
-   *  here (e.g. `search`). */
-  memory?: {
-    injectionBudget?: {
-      /** Host honors `MemoryListOptions.tokenBudget` (RFC 0113). */
-      supported: boolean;
-      /** Unit `tokenBudget` is denominated in. `chars` counts UTF-8/Unicode
-       *  characters of the entry `content` (tokenizer-free). */
-      tokenCounter?: 'o200k_base' | 'cl100k_base' | 'chars' | 'host-defined';
-    };
-  };
-  /** RFC 0115. Conditional-GET + Content-Encoding negotiation on run reads
-   *  (`GET /v1/runs/{runId}`). Absent ⇒ the host returns today's `200` +
-   *  identity body. Distinct from the file-egress `fileHandling.transport`
-   *  (ftp/sftp/ssh) sub-capability — this advertises HTTP-layer poll economy
-   *  on the run-read REST surface. Read-only. */
-  restTransport?: {
-    /** Host emits a strong, event-log-sequence-derived `ETag` on
-     *  `GET /v1/runs/{runId}` and honors `If-None-Match` with a `304 Not
-     *  Modified` (empty body) when the validator matches the current state. */
-    conditionalRunGet?: boolean;
-    /** Content-Encoding values the host will negotiate on run reads. `gzip`
-     *  is the baseline; `br`/`zstd` are optional — the host advertises only
-     *  the subset it can serve. For each advertised value the decoded body is
-     *  byte-identical to the identity body. */
-    contentEncodings?: readonly ('gzip' | 'br' | 'zstd')[];
-  };
-  extensions?: Record<string, unknown>;
-  // Network-handshake superset (all `(future)` fields per capabilities.md)
-  implementation?: { name?: string; version?: string; vendor?: string };
-  engineVersion?: number;
-  eventLogSchemaVersion?: number;
-  supportedTransports?: readonly ('rest' | 'mcp' | 'a2a' | 'grpc')[];
-  configurable?: Record<string, unknown>;
-  observability?: Record<string, unknown>;
-  minClientVersion?: string;
-}
-
 /**
  * The `kind` discriminator on a `cap.breached` event payload
  * (`run-event-payloads.schema.json#capBreached`). The four engine kinds, the
@@ -221,7 +53,7 @@ export type CapBreachedKind =
  * does not advertise `capabilities.compensation` omits the field; an
  * advertising host carries it on every snapshot, `none` when idle. The
  * value is the deterministic fold of the `compensation.*` events defined in
- * `spec/v1/compensation.md §"Run rollup: compensationStatus"`.
+ * `spec/v2/core/compensation.md §"Run rollup: compensationStatus"`.
  */
 export type CompensationStatus =
   | 'none'
@@ -232,10 +64,22 @@ export type CompensationStatus =
   | 'failed'
   | 'manual';
 
+/** `RunSnapshot.owner` — closed; `subject` REQUIRED (identity.md). */
+export interface RunOwner {
+  tenant: string;
+  workspace?: string;
+  subject: string;
+}
+
+/** `schemas/v2/run-snapshot.schema.json` — the fold of the event log through the run projection (runs.md §Snapshot). */
 export interface RunSnapshot {
   runId: string;
   workflowId: string;
   status: RunStatus;
+  owner: RunOwner;
+  /** The era key, integer ≥ 2; a v2 host stamps `3` on every run it creates. */
+  eventLogSchemaVersion: number;
+  engineVersion?: number;
   /** RFC 0151 §D. Present iff the host advertises `capabilities.compensation`.
    *  See {@link CompensationStatus}. */
   compensationStatus?: CompensationStatus;
@@ -245,7 +89,25 @@ export interface RunSnapshot {
   nodeStates?: Record<string, unknown>;
   variables?: Record<string, unknown>;
   channels?: Record<string, unknown>;
-  error?: { code?: string; message?: string };
+  /** `{ code, message, details? }` on terminal `failed`. */
+  error?: { code: string; message: string; details?: Record<string, unknown> };
+  /** The persisted `RunOptions` (runs.md §Run options). */
+  configurable?: RunConfigurable;
+  tags?: readonly string[];
+  metadata?: Record<string, unknown>;
+  agent?: AgentRef;
+  /** MUST NOT change for the run's lifetime. */
+  runOrchestrator?: AgentRef;
+  metrics?: {
+    openwopCost?: {
+      usd?: number;
+      tokens?: { input?: number; output?: number };
+      model?: string;
+      provider?: string;
+      duration_ms?: number;
+    };
+    [key: string]: unknown;
+  };
   /** Linkage back to the parent run when this run was spawned via
    *  `core.subWorkflow`. Per `interrupt-profiles.md §openwop-interrupt-
    *  cascade-cancel`: child runs preserve `parentRunId` + `parentNodeId`
@@ -254,7 +116,7 @@ export interface RunSnapshot {
   parentNodeId?: string;
   /** Surfaced for `waiting-*` runs per `interrupt.md §"Signed-token
    *  callback"`. Carries the open interrupt's metadata so clients can
-   *  resolve via `POST /v1/interrupts/{token}` without consulting a
+   *  resolve via `POST /interrupts/{token}` without consulting a
    *  separate endpoint. Hosts MAY omit `data` to keep payloads small;
    *  the token + callbackUrl are the load-bearing fields. */
   interrupt?: {
@@ -267,32 +129,48 @@ export interface RunSnapshot {
 }
 
 /**
- * Per-run parameter overlay carried in `RunOptions.configurable`. Reserved
- * keys are typed; unknown keys are passed through verbatim. See
- * `run-options.md`.
+ * `schemas/v2/configurable.schema.json` — closed, nested and versioned (RFC
+ * 0171 §D.1; runs.md §Run options). `version` is REQUIRED and is `1`. An
+ * unknown root key, an unknown key inside a section, or a dotted key is
+ * rejected with `400 validation_error`; vendor keys live under
+ * `extensions.<org>`.
  */
 export interface RunConfigurable {
-  /** Override the per-run node-execution ceiling. Clamped server-side. */
-  recursionLimit?: number;
-  /** RFC 0058. Wall-clock run deadline (ms from `run.started`); clamped to
-   *  `Capabilities.limits.maxRunDurationMs`. Breach → `cap.breached
-   *  { kind: 'run-duration' }` + `run_timeout`. */
-  runTimeoutMs?: number;
-  /** RFC 0058. Agent-loop iteration ceiling (one per orchestrator turn);
-   *  clamped to `Capabilities.limits.maxLoopIterations`. Breach →
-   *  `cap.breached { kind: 'loop-iterations' }` + `loop_limit_exceeded`.
-   *  Ignored unless the host advertises `capabilities.agents.loop.supported`. */
-  maxLoopIterations?: number;
-  /** Override AI model for nodes that consume `ctx.config.configurable.model`. */
-  model?: string;
-  /** Override AI temperature (server SHOULD enforce 0..2). */
-  temperature?: number;
-  /** Override AI max-tokens cap. */
-  maxTokens?: number;
-  /** Per-prompt-ID variant override map. */
-  promptOverrides?: Record<string, string>;
-  /** Implementation-specific extensions; passed through verbatim. */
-  [key: string]: unknown;
+  version: 1;
+  run?: {
+    /** Clamped to `limits.maxNodeExecutions`. */
+    recursionLimit?: number;
+    /** Resolves to `min(runTimeoutMs, limits.maxRunDurationMs)`; breach → `run_timeout`. */
+    runTimeoutMs?: number;
+    /** Resolves against `limits.maxLoopIterations`; breach → `loop_limit_exceeded`. */
+    maxLoopIterations?: number;
+    /** The `low-confidence` interrupt threshold. */
+    escalationThreshold?: number;
+  };
+  ai?: {
+    /** MUST be in `aiProviders.supported`, else `400 validation_error`. */
+    provider?: string;
+    model?: string;
+    /** 0..2 */
+    temperature?: number;
+    maxTokens?: number;
+    /** References a provider in `aiProviders.byok`; never carries key material. */
+    credentialRef?: string;
+    promptOverrides?: Record<string, string>;
+    /** Test-keys-only; `403 mock_provider_forbidden` on a production credential. */
+    mockProvider?: string;
+    reasoningVerbosity?: 'none' | 'summary' | 'full';
+    /** The `envelope.refusal` ceiling (events.md E5). */
+    maxRefusals?: number;
+  };
+  distillation?: {
+    /** Resolves to `min(tokenBudget, memory.distillation.maxTokenBudget)`. */
+    tokenBudget?: number;
+  };
+  /** `schemas/v2/budget-policy.schema.json`. */
+  budget?: Record<string, unknown>;
+  /** A vendor key lives under its registered org and nowhere else. */
+  extensions?: Record<string, Record<string, unknown>>;
 }
 
 export interface CreateRunRequest {
@@ -305,6 +183,9 @@ export interface CreateRunRequest {
   inputs?: Record<string, unknown>;
   tenantId?: string;
   scopeId?: string;
+  /** `schemas/v2/residency.schema.json`; an unadvertised `region` → `422 residency_unavailable`. */
+  residency?: { region?: string; [key: string]: unknown };
+  /** The signed-token callback (interrupt.md). */
   callbackUrl?: string;
   configurable?: RunConfigurable;
   tags?: readonly string[];
@@ -333,35 +214,6 @@ export interface CancelRunResponse {
   status: 'cancelled' | 'cancelling';
 }
 
-/**
- * Portable JSON diagnostic export for a single run per
- * `spec/v1/debug-bundle.md` + `schemas/debug-bundle.schema.json`.
- *
- * Hosts MAY omit non-required fields. Consumers MUST treat masked /
- * omitted / hashed values as the spec-canonical content per the host's
- * advertised `redactionMode` — they are NOT placeholders for missing
- * data.
- */
-export interface DebugBundle {
-  bundleVersion: string;
-  generatedAt: string;
-  host: { name?: string; version?: string; vendor?: string };
-  run: Record<string, unknown>;
-  events: ReadonlyArray<Record<string, unknown>>;
-  redactionApplied: boolean;
-  /** Reflects the host's `capabilities.compliance.defaultMode`. */
-  redactionMode: 'mask' | 'omit' | 'hash' | 'passthrough';
-  /** True when the bundle hit the host's size cap; pair with `truncatedReason`. */
-  truncated?: boolean;
-  truncatedReason?: string;
-  [key: string]: unknown;
-}
-
-export interface DebugBundleOptions {
-  /** Optional host-extension query parameter to lower the size cap for testing. Spec-canonical hosts SHOULD prefer `host.<vendor>.<query>` namespacing; this is the SQLite-reference convention. */
-  maxEvents?: number;
-}
-
 export interface RegisterWebhookRequest {
   /** Receiver URL the host will POST signed deliveries to. */
   url: string;
@@ -407,7 +259,7 @@ export interface ResumeRunResponse {
   resumedAt?: string;
 }
 
-// rest-endpoints.md §"POST /v1/runs:bulk-cancel" (closes R1).
+// rest-endpoints.md §"POST /runs:bulk-cancel" (closes R1).
 export interface BulkCancelRunsRequest {
   runIds: readonly string[];
   reason?: string;
@@ -491,28 +343,8 @@ export interface CreateAnnotationRequest {
   note?: string;
 }
 
-/** RFC 0059 versioned, tenant·workspace-scoped ground-truth file
- *  (`workspace-file.schema.json`). The `list` endpoint returns this shape
- *  minus `content` (metadata only). */
-export interface WorkspaceFile {
-  path: string;
-  content: string;
-  contentType?: string;
-  version: number;
-  etag?: string;
-  updatedAt: string;
-}
-
-/** RFC 0059 request body for `putWorkspaceFile` (`workspace-file-create.schema.json`).
- *  `path` is URL-bound; the host assigns `version`/`etag`/`updatedAt`.
- *  Optimistic concurrency is expressed via the `If-Match` header, not the body. */
-export interface PutWorkspaceFileRequest {
-  content: string;
-  contentType?: string;
-}
-
 /**
- * Response from `GET /v1/runs/{runId}/ancestry` — RFC 0040 §C cross-host
+ * Response from `GET /runs/{runId}/ancestry` — RFC 0040 §C cross-host
  * composition parent. `parent: null` for top-level runs (not dispatched
  * from any other run); otherwise `parent.wellKnownUrl` is set when the
  * parent is on a different host so callers can walk the chain.
@@ -532,7 +364,7 @@ export interface RunAncestryResponse {
   };
 }
 
-/** RFC 0054 — response from `GET /v1/runs/{runId}:diff?against={otherRunId}`.
+/** RFC 0054 — response from `GET /runs/{runId}:diff?against={otherRunId}`.
  *  Mirror of `run-diff-response.schema.json`. Deterministic, replay-aware
  *  structured diff of two runs' event sequences + terminal states. */
 export interface RunDiffEventDiff {
@@ -596,9 +428,16 @@ export interface ResolveInterruptByTokenResponse {
   [key: string]: unknown;
 }
 
+/** `GET /runs/{runId}/events/poll` response (events.md §Poll) — closed. */
 export interface PollEventsResponse {
+  runId: string;
   events: readonly RunEventDoc[];
-  isComplete: boolean;
+  /** The highest sequence in the log at the time of the response; `-1` when the log is empty. */
+  lastSequence: number;
+  /** The snapshot status. */
+  status: RunStatus;
+  /** Whether the run is terminal. */
+  isTerminal: boolean;
 }
 
 /** Mirror of `run-event.schema.json` — top-level shape only. */
@@ -609,109 +448,184 @@ export interface RunEventDoc {
   type: string; // RunEventType — string-typed for forward compat
   payload: unknown;
   timestamp: string;
+  /** The one ordering field: integer ≥ 0, first event `0`, strictly increasing per run. */
   sequence: number;
-  schemaVersion?: number;
-  engineVersion?: string;
+  /** Per-event schema version, integer ≥ 1 (RFC 0172 §B axis 5). */
+  schemaVersion: number;
+  /** Integer ≥ 0 everywhere (RFC 0172 §B axis 3). */
+  engineVersion?: number;
   causationId?: string;
 }
 
+/**
+ * A vendor error code: `<org>.<name>` with the org registered in
+ * `spec/v2/declaration.json`; `openwop.` is reserved (errors.md). The template
+ * literal keeps `ErrorEnvelope.error` open to registered vendor codes while
+ * every protocol code is a member of the generated {@link ErrorCode} union.
+ */
+export type VendorErrorCode = `${string}.${string}`;
+
+/** `{ error, message, details? }` and nothing else (errors.md §The envelope). */
 export interface ErrorEnvelope {
-  error: string;
+  error: ErrorCode | VendorErrorCode;
   message: string;
   details?: Record<string, unknown>;
 }
 
 export type StreamMode = 'values' | 'updates' | 'messages' | 'debug';
 
-// ─── BYOK / AI providers (Phase H.1 + H.1″) ─────────────────────────────
+// ─── Discovery: the closed v2 root (capabilities.md; RFC 0169, 0172, 0176) ──
 
-/**
- * AI policy mode advertised by the host per `capabilities.md`
- * §`aiProviders.policies`. Hosts MAY advertise a subset; clients MUST
- * tolerate any subset.
- *
- *   - `disabled`   — provider MUST NOT be used at all
- *   - `optional`   — no restriction (default)
- *   - `required`   — provider call MUST carry a `credentialRef`
- *   - `restricted` — model MUST match the policy's `allowedModels`
- */
-export type AIPolicyMode = 'disabled' | 'optional' | 'required' | 'restricted';
+/** Maturity of a capability record. */
+export type CapabilityStatus = 'stable' | 'experimental' | 'deprecated';
+
+/** The five wire-legal witness classes (RFC 0168 §B); `unwitnessable` never appears on the wire. */
+export type WitnessClass =
+  | 'witnessable-unaided'
+  | 'witnessable-gated'
+  | 'seam-gated'
+  | 'claims-check'
+  | 'negative-existence';
 
 /**
- * Closed-set deny reason returned in `provider_policy_denied.details.reason`
- * per spec §"Wire-format error".
+ * One capability record (RFC 0169 §A). `status`, `since` and `witness` are
+ * REQUIRED; `until` is REQUIRED when `status` is `experimental` or
+ * `deprecated` and MUST NOT be present when `stable`. `supported` does not
+ * exist — presence of the record is the claim. The remaining members are the
+ * family's facets (`spec/v2/facets/<key>.schema.json` where hand-decided).
  */
-export type AIPolicyDenyReason =
-  | 'provider_disabled'
-  | 'byok_required'
-  | 'byok_required_but_unresolved'
-  | 'model_not_allowed';
+export interface CapabilityRecord {
+  status: CapabilityStatus;
+  /** `<major>.<minor>` */
+  since: string;
+  /** `<major>.<minor>` or `YYYY-MM-DD` */
+  until?: string;
+  witness: WitnessClass;
+  [facet: string]: unknown;
+}
+
+/** A version-axis grammar: `<major>.<minor>` with no leading zero (RFC 0149 §C). */
+export type ProtocolVersion = `${number}.${number}`;
 
 /**
- * Capability advertisement payload mirroring spec §`aiProviders` +
- * §`aiProviders.policies`. Optional sub-fields are absent on hosts
- * that don't enforce per-provider policies.
+ * The closed v2 discovery root (`schemas/v2/capabilities.schema.json`,
+ * `additionalProperties: false`). Every key is one of the generated
+ * {@link CapabilityMetadataKey}s, a family key ({@link CapabilityFamilyKey})
+ * carrying a {@link CapabilityRecord}, or `extensions`. `protocolVersions`
+ * and `preferredVersion` are REQUIRED (versioning.md §1.1).
  */
-export interface AIProvidersCapability {
-  /** Provider ids the host's AI-proxy can route to. Optional per
-   *  `capabilities.schema.json` (the `aiProviders` block has no required
-   *  fields); a host advertising the block normally lists them. */
-  supported?: readonly string[];
-  /** Subset of `supported` for which BYOK is permitted. */
-  byok?: readonly string[];
-  /** Optional 4-mode policy enforcement advertisement. */
-  policies?: {
-    modes: readonly AIPolicyMode[];
-    scopes?: readonly string[];
-    errorCode?: string;
-  };
-  /** RFC 0108. Subset of `supported` whose entries are operator-/tenant-
-   *  configured OpenAI-compatible endpoints (Ollama / vLLM / LM Studio / any
-   *  `/v1/chat/completions`-compatible server), as opposed to a host-managed
-   *  connection to a known public vendor. Each entry also appears in
-   *  `supported` and MAY also appear in `byok`. The id is an OPAQUE label that
-   *  MUST NOT encode the endpoint's network location (RFC 0108 §A.3), and a
-   *  client MUST NOT infer model capabilities from it (§B) — the authoritative
-   *  sources are `modelCapabilities.advertised[]` and `aiProviders.input`. */
-  selfHosted?: readonly string[];
-  /** RFC 0105. Present (value MUST be `'supported'`) ⇒ the host exposes speech
-   *  synthesis via the host-side `ctx.callSpeechSynthesizer`. Absent ⇒ no TTS
-   *  (a call is rejected with `speech_synthesis_unsupported`). */
-  speechSynthesis?: 'supported';
-  /** RFC 0106. Optional real-time voice profile. Absent ⇒ no live voice. The
-   *  sub-flags gate streaming STT / chunked TTS and turn-taking; the host
-   *  enforces that `turnDetection`/`bargeIn` require `transcription`. */
-  realtimeVoice?: {
-    /** Present (`'streaming'`) ⇒ host exposes streaming `ctx.callTranscriber`. */
-    transcription?: 'streaming';
-    /** Present (`'streaming'`) ⇒ `ctx.callSpeechSynthesizer` honors `stream:true`.
-     *  Requires `aiProviders.speechSynthesis: 'supported'`. */
-    synthesis?: 'streaming';
-    /** Endpointing sophistication; requires `transcription`. */
-    turnDetection?: 'vad' | 'semantic';
-    /** Present (`'supported'`) ⇒ host emits `voice.barge_in`/`voice.cancelled`
-     *  on overlapping speech; requires `transcription`. */
-    bargeIn?: 'supported';
-  };
-  /** RFC 0116. Provider-scoped advert that the host honors the AI-envelope
-   *  `generate` request's optional `cachePrefixId` (a tenant-namespaced,
-   *  secret-free label) as a routing hint into the routed provider's
-   *  server-side context cache. Absent ⇒ the host ignores `cachePrefixId`
-   *  (no error). The cache MUST be keyed by `(resolved tenant, cachePrefixId)`
-   *  (SECURITY invariant `prompt-prefix-cache-cross-tenant-isolation`) and a
-   *  hit/miss MUST NOT change the recorded envelope or
-   *  `provider.usage.inputTokens`/`outputTokens` (replay-invariant). NOT a
-   *  universal claim — `providers` scopes it per routed provider. */
-  promptPrefixCache?: {
-    /** Whether the host honors `cachePrefixId`. */
-    supported: boolean;
-    /** Subset of `supported` for which `cachePrefixId` is honored (prefix
-     *  caching is provider-specific, e.g. Anthropic ephemeral). A request
-     *  whose routed provider is not listed has `cachePrefixId` ignored. */
-    providers?: readonly string[];
+export type Capabilities = {
+  /** Every `<major>.<minor>` this host serves. */
+  protocolVersions: readonly ProtocolVersion[];
+  /** The header-less default; MUST be a member of `protocolVersions[]`. */
+  preferredVersion: ProtocolVersion;
+  /** Kept as `preferredVersion`'s twin for v1 readers through the overlap. */
+  protocolVersion?: ProtocolVersion;
+  /** RFC 0172 row C5.8 — a host MAY refuse a client below it with `426 client_version_unsupported`. */
+  minClientVersion?: string;
+  /** Integer everywhere (RFC 0172 §B axis 3). */
+  engineVersion?: number;
+  /** The era key; a v2 host writes `3`. */
+  eventLogSchemaVersion?: number;
+  implementation?: { name?: string; version?: string; vendor?: string };
+  /** `extensions.<org>.<name>` — vendor and host extension records; the org's own shape. */
+  extensions?: Record<`${string}.${string}`, Record<string, unknown>>;
+  configurable?: Record<string, unknown>;
+  observability?: Record<string, unknown>;
+  runtimeCapabilities?: Record<string, unknown>;
+  testing?: Record<string, unknown>;
+  conformance?: Record<string, unknown>;
+  fixtures?: Record<string, unknown>;
+  compliance?: Record<string, unknown>;
+  discovery?: Record<string, unknown>;
+} & {
+  readonly [K in CapabilityFamilyKey]?: CapabilityRecord;
+};
+
+// ─── RFC 0173 — compensation, effect ledger, effect seams ─────────────────
+
+/** `GET /runs/{runId}/compensation` (`schemas/v2/compensation-projection.schema.json`). */
+export interface CompensationProjection {
+  runId: string;
+  status: 'none' | 'pending' | 'running' | 'completed' | 'partial' | 'failed' | 'manual-intervention';
+  plan: readonly {
+    nodeId: string;
+    order: number;
+    /** `schemas/v2/compensation-policy.schema.json` */
+    policy?: Record<string, unknown>;
+    irreversibleEffect?: boolean;
+  }[];
+  attempts: readonly {
+    nodeId: string;
+    attempt: number;
+    outcome: 'succeeded' | 'failed' | 'skipped' | 'manual';
+    at: string;
+    reason?: string;
+  }[];
+}
+
+/** `GET /runs/{runId}/effects` (`schemas/v2/effect-ledger-projection.schema.json`). */
+export interface EffectLedgerProjection {
+  runId: string;
+  effects: readonly {
+    effectId: string;
+    nodeId: string;
+    attempt: number;
+    invocationId?: string;
+    keying: 'business-identity' | 'activity-recipe';
+    /** Redaction-safe provider-side identity; never credential material. */
+    providerKey?: string;
+    state: 'claimed' | 'completed' | 'released' | 'escaped';
+    at: string;
+  }[];
+}
+
+/** `GET /host/effect-seams` (`schemas/v2/effect-seam-manifest.schema.json`). */
+export interface EffectSeamManifest {
+  manifestVersion: '1';
+  host: {
+    name: string;
+    build: { kind: 'image-digest' | 'commit' | 'artifact-sha256'; id: string };
   };
+  seams: readonly {
+    /** The outbound effect path, host-named (e.g. `http.fetch`). */
+    seam: string;
+    kind: 'http' | 'queue' | 'storage' | 'provider-sdk' | 'webhook-fanout';
+    guarded: true;
+    guardedBy: string;
+    branchReFires?: boolean;
+    note?: string;
+  }[];
+}
+
+// ─── Host events channel (`/host/events`; events.md §Host events) ─────────
+
+/** `heartbeat.evaluated` (`schemas/v2/heartbeat-evaluated.schema.json`). */
+export interface HeartbeatEvaluatedPayload {
+  heartbeatId: string;
+  status: 'ok' | 'timeout' | 'error';
+  changed: boolean;
+  [key: string]: unknown;
+}
+
+/** `heartbeat.stateChanged` (`schemas/v2/heartbeat-state-changed.schema.json`). */
+export interface HeartbeatStateChangedPayload {
+  heartbeatId: string;
+  from: Record<string, unknown>;
+  to: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** One frame of the `hostEvents` channel — content-free of run data. */
+export interface HostEventDoc {
+  type: string;
+  payload: unknown;
+  timestamp?: string;
+  [key: string]: unknown;
 }
 
+// ─── AI run overlay ─────────────────────────────────────────────────────
+
 /**
  * Opaque host-issued reference to a stored secret. Sent via
  * `RunOptions.configurable.ai.credentialRef`; the host resolves
@@ -734,20 +648,6 @@ export interface AIRunOverlay {
 
 // ─── MCP client (Phase H.2) ─────────────────────────────────────────────
 
-/**
- * Capability advertisement for hosts that operate an MCP client.
- * Mirrors `examples/hosts/postgres/src/mcp-client.ts` reference shape.
- * `trustBoundary: "untrusted"` is REQUIRED per
- * threat-model-prompt-injection.md §"UNTRUSTED marker": tool output is
- * adversarial-tolerant and downstream LLM nodes treat it as user data.
- */
-export interface McpClientCapability {
-  supported: true;
-  transports: readonly string[];
-  defaultTimeoutMs?: number;
-  trustBoundary: 'untrusted';
-}
-
 /** Wire shape of the `core.mcp.toolCall` node config. */
 export interface McpToolCallNodeConfig {
   serverId: string;
@@ -769,16 +669,6 @@ export interface McpInvokedSummary {
 
 // ─── HTTP client (Phase H.3) ────────────────────────────────────────────
 
-/** Capability advertisement for hosts that implement `core.http.request`. */
-export interface HttpClientCapability {
-  supported: true;
-  methods: readonly ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD')[];
-  defaultTimeoutMs?: number;
-  maxResponseBodyBytes: number;
-  ssrfGuard: boolean;
-  redirectPolicy?: 'follow' | 'reject';
-}
-
 /** Wire shape of the `core.http.request` node config. */
 export interface HttpRequestNodeConfig {
   url: string;
@@ -822,13 +712,6 @@ export interface MemoryListOptions {
   query?: string;
 }
 
-/** Capability advertisement shape per capabilities.md §`memory`. */
-export interface MemoryCapability {
-  supported: true;
-  maxEntrySizeBytes: number;
-  ttlSupported: boolean;
-}
-
 // ─── Reasoning + agent events (Phase I.2) ───────────────────────────────
 
 /** Mirror of `schemas/agent-ref.schema.json`. */
@@ -842,109 +725,6 @@ export interface AgentRef {
 /** Reasoning verbosity per capabilities.md §`agents.reasoning`. */
 export type ReasoningVerbosity = 'off' | 'summary' | 'full';
 
-/** Capability advertisement shape per capabilities.md §`agents` (Phase 1-6). */
-export interface AgentsCapability {
-  supported: true;
-  profile?: string;
-  modelClasses?: readonly ('reasoning' | 'tool-using' | 'chat')[];
-  orchestratorPattern?: string;
-  memoryBackends?: readonly string[];
-  orchestrator?: boolean;
-  /** Phase 6. Host implements the `core.dispatch` Core typeId. The RFC 0118
-   *  fan-out/join descriptors live on the top-level {@link Capabilities.dispatch}
-   *  object (`capabilities.md` §`dispatch`), NOT here. */
-  dispatch?: boolean;
-  reasoning?: {
-    verbosity: ReasoningVerbosity;
-    tokenLimit?: number;
-    /** RFC 0024. When `true`, host MAY emit `agent.reasoning.delta`
-     *  events incrementally while a reasoning block is still open,
-     *  in addition to the final `agent.reasoned`. Consumers that
-     *  only read `agent.reasoned` remain correct (the closing event
-     *  is authoritative). */
-    streaming?: boolean;
-  };
-}
-
-/**
- * RFC 0007 + RFC 0118 — the top-level `core.dispatch` capability descriptors
- * (`capabilities.md` §`dispatch`), exposed as {@link Capabilities.dispatch}.
- * The discovery surface for parallel sub-workflow fan-out and join: an author
- * reads `joinModes` / `onChildFailureModes` / `fanOutPolicies` to detect partial
- * support before pinning a `core.dispatch` node's `fanOutPolicy` / `joinPolicy`.
- * All fields OPTIONAL + read-only; absent descriptors carry the documented
- * conservative defaults (a host that omits `joinModes` implements no parallel
- * join; one that omits `onChildFailureModes` accepts only `'collect'`). The SDK
- * does NOT model the authoring-side `DispatchConfig` (`fanOutPolicy` /
- * `joinPolicy` / `maxConcurrency`) — that is a workflow-node-definition shape,
- * out of this client SDK's read-only scope.
- */
-export interface DispatchCapability {
-  /** Host implements the `core.dispatch` Core typeId (the top-level mirror of
-   *  the legacy {@link AgentsCapability.dispatch} boolean). */
-  supported?: boolean;
-  /** RFC 0007 + RFC 0118. Host honors `nextWorkerIds.length > 1`; since RFC 0118
-   *  ALSO the gate for accepting `fanOutPolicy: 'parallel'` at registration. A
-   *  host advertising `false` rejects a node pinning `'parallel'`. */
-  fanOutSupported?: boolean;
-  /** RFC 0118. The `fanOutPolicy` values the host accepts. Absent ⇒ treat as
-   *  `['sequential', 'reject']` (parallel unsupported). */
-  fanOutPolicies?: readonly ('sequential' | 'reject' | 'parallel')[];
-  /** RFC 0118. The `joinPolicy.mode` values the host implements for
-   *  `fanOutPolicy: 'parallel'`. Absent ⇒ the host implements no parallel join. */
-  joinModes?: readonly ('wait-all' | 'quorum' | 'first' | 'race')[];
-  /** RFC 0118. The `joinPolicy.onChildFailure` error-aggregation values the host
-   *  accepts (orthogonal to {@link joinModes}). Absent ⇒ `['collect']` only — a
-   *  host that omits this MUST reject a node pinning `'fail-fast'` / `'absorb'`. */
-  onChildFailureModes?: readonly ('collect' | 'fail-fast' | 'absorb')[];
-  /** RFC 0118. The host's hard concurrency/breadth ceiling for a parallel
-   *  fan-out. Effective concurrency is `min(config.maxConcurrency ?? ∞,
-   *  maxFanOut ?? ∞)`. Absent ⇒ unbounded (treat as "unknown, may be capped"). */
-  maxFanOut?: number;
-}
-
-/**
- * RFC 0117 (`Active`; amended by RFC 0119) — the `uiPlugins` capability
- * advertisement (`capabilities.md` §`uiPlugins`), exposed as
- * {@link Capabilities.uiPlugins}. The host loads `kind:"frontend-plugin"` packs
- * in an origin/execution-isolated sandbox (mechanism per {@link isolation}) and
- * serves the closed `ui-plugin/1` host-RPC boundary. All fields but `supported`
- * are OPTIONAL + read-only; a client reads them to decide whether (and which
- * surfaces / RPC methods) a plugin can target before install. The SDK models
- * only this discovery block — NOT the `ui-plugin/1` RPC envelope or the
- * `frontend-plugin` manifest (a renderer/registry concern, out of client scope).
- */
-export interface UiPluginsCapability {
-  /** Host loads `kind:"frontend-plugin"` packs in an isolated sandbox and
-   *  serves the `ui-plugin/1` host-RPC boundary. `false`/absent ⇒ the host
-   *  rejects such packs at registration and renders no plugin surface. */
-  supported: boolean;
-  /** RFC 0117 (amended by RFC 0119). The categorical isolation MECHANISM the
-   *  host enforces for plugin bytes. The five named values plus a vendor
-   *  `x-host-<host>-<key>` form (per `host-extensions.md`) — the open string
-   *  admits the vendor form without discarding autocomplete for the known set.
-   *  ALL values denote the SAME mandatory isolation property (no host execution
-   *  context / DOM / origin-storage / credential access, deny-egress, RPC-only);
-   *  the field names the mechanism, never relaxes the property. Absent ⇒
-   *  `'cross-origin-iframe'` (the default). */
-  isolation?:
-    | 'cross-origin-iframe'
-    | 'wasm'
-    | 'process'
-    | 'container'
-    | 'vm'
-    | (string & {});
-  /** RFC 0117. Plugin surfaces this host renders. A pack surface not in this
-   *  set is installable-but-inert (graceful degradation). */
-  surfaces?: readonly ('artifact-viewer' | 'route' | 'settings-panel')[];
-  /** RFC 0117. The `ui-plugin/1` host-RPC methods this host honors. A plugin
-   *  call to a method not in this set is rejected with `method_not_allowed`
-   *  (SECURITY invariant `frontend-plugin-rpc-allowlist`). */
-  hostApi?: readonly ('artifact.read' | 'artifact.write' | 'host.toast' | 'host.navigate')[];
-  /** RFC 0117. Per-plugin entry-bundle byte ceiling the host will load. */
-  maxEntryBytes?: number;
-}
-
 // ─── agent.* event payloads (RFC 0002 §B + RFC 0024) ────────────────────
 //
 // Mirror of `schemas/run-event-payloads.schema.json#$defs.agent*`. Field
@@ -1148,7 +928,7 @@ export interface VoiceCancelledPayload {
 /** `channel.presence` (RFC 0110). EPHEMERAL online + typing presence for a
  *  `type:'channel'` conversation. Observable on the LIVE run-event stream
  *  only — the host MUST NOT persist it to the replayable event log, so it is
- *  ABSENT on replay / `POST /v1/runs/{runId}:fork`. Membership-gated: every
+ *  ABSENT on replay / `POST /runs/{runId}:fork`. Membership-gated: every
  *  ref is a current participant (opaque RFC 0041 subject refs, non-PII). */
 export interface ChannelPresencePayload {
   conversationId: string;
@@ -1208,7 +988,7 @@ export interface DispatchJoinPayload {
  *  in-window orchestrator-loop transcript turns with a host-produced summary to
  *  honor `multiAgent.executionModel.contextBudget.transcriptTokenBudget`.
  *  CONTENT-FREE: the summary text never rides the wire — `summaryRef` is an
- *  artifactId resolved via `GET /v1/runs/{runId}/artifacts/{artifactId}`. The
+ *  artifactId resolved via `GET /runs/{runId}/artifacts/{artifactId}`. The
  *  summary is nondeterministic host output governed like an RFC 0041 envelope:
  *  on `:fork mode:replay` the host MUST reuse this recorded `summaryRef` and
  *  MUST NOT re-summarize. `replacedTurns` lists the event ids the summary stands
@@ -1237,36 +1017,8 @@ export interface TypedRunEvent<T> extends RunEventDoc {
   payload: T;
 }
 
-// ─── Auth profile claims (Phase I.5 + I.6) ──────────────────────────────
-
-/** Profile identifiers per auth-profiles.md. */
-export type AuthProfileClaim =
-  | 'openwop-audit-log-integrity'
-  | 'openwop-auth-api-key-rotation'
-  | 'openwop-auth-oauth2-client-credentials'
-  | 'openwop-auth-oidc-user-bearer'
-  | 'openwop-auth-mtls'
-  | 'openwop-discovery-auth-scoped'
-  | 'openwop-interrupt-quorum'
-  | 'openwop-interrupt-auth-required'
-  | 'openwop-interrupt-external-event'
-  | 'openwop-interrupt-cascade-cancel'
-  | 'openwop-production';
-
-/** Rotation advertisement shape per auth-profiles.md §"openwop-auth-api-key-rotation". */
-export interface AuthRotationCapability {
-  supported: true;
-  minGraceSeconds: number;
-}
-
-/** Auth-scoped discovery advertisement per RFC 0011 §A. */
-export interface DiscoveryAuthScopedCapability {
-  supported: true;
-  mode: 'same-endpoint';
-}
-
 // ---------------------------------------------------------------------------
-// AI Envelope (DRAFT v1.x — `spec/v1/ai-envelope.md`)
+// AI Envelope (`spec/v2/core/events.md` §AI envelopes)
 //
 // Inbound LLM-emission envelope. Distinct from `RunEventDoc` (outbound event
 // log) and `ErrorEnvelope` (host HTTP error response). Top-level shape is
@@ -1297,7 +1049,7 @@ export interface PartialInfo {
   total: number;
 }
 
-/** Canonical inbound LLM-emission wire shape per `spec/v1/ai-envelope.md`. */
+/** Canonical inbound LLM-emission wire shape per `spec/v2/core/ai-envelope.md`. */
 export interface AIEnvelope<TPayload = unknown> {
   /** Discriminator for payload shape, kind routing, and Envelope Contract gate. */
   type: string;
@@ -1346,11 +1098,6 @@ export interface ValidationDetail {
 /** Optional capability advertisement. Default when absent: 'warn'. */
 export type EnvelopeStrictness = 'warn' | 'strict';
 
-/** Optional capability advertisement per `ai-envelope.md` §"Capability handshake integration". */
-export interface EnvelopeContractsCapability {
-  advertised: boolean;
-}
-
 // Universal-kind payloads. Per-kind schemas at `schemas/envelopes/<kind>.schema.json`.
 
 /** Payload of the universal `clarification.request` envelope kind. */
@@ -1439,7 +1186,7 @@ export interface A2uiSurfacePatchOp {
 /**
  * RFC 0114 — a HOST-SIDE TRANSPORT frame carrying an RFC 6902 delta over a
  * recorded `ui.a2ui-surface` envelope ({@link A2UISurfacePayload}). Delivered
- * ONLY over the run event stream (`GET /v1/runs/{runId}/events`) to a subscriber
+ * ONLY over the run event stream (`GET /runs/{runId}/events`) to a subscriber
  * that negotiated `?a2uiDelta=1`; every other consumer (the event-log read,
  * replay, `:fork`, any non-negotiating subscriber) receives the materialized
  * FULL surface. This is NOT a recorded-envelope shape — the recorded
@@ -1462,7 +1209,7 @@ export interface A2uiSurfaceDeltaFrame {
   patch: A2uiSurfacePatchOp[];
 }
 
-// ── RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md) ──
+// ── RFC 0027 + RFC 0028 — Prompt library (spec/v2/core/prompts.md) ──
 
 /**
  * Role a PromptTemplate plays when composed into an LLM call. Shared enum
@@ -1488,7 +1235,7 @@ export interface PromptVariable {
 
 /**
  * Named, versioned, variable-bound prompt body. Per
- * `schemas/prompt-template.schema.json` + spec/v1/prompts.md §PromptTemplate.
+ * `schemas/prompt-template.schema.json` + spec/v2/core/prompts.md §PromptTemplate.
  *
  * `meta.packName` + `meta.packVersion` are required when `meta.source: "pack"`
  * (RFC 0028 §C); a JSON-Schema `if/then` conditional enforces this at the
@@ -1633,8 +1380,8 @@ function extractTraceId(traceparent: string): string | undefined {
 }
 
 /**
- * One installed manifest agent, as projected by `GET /v1/agents` /
- * `GET /v1/agents/{agentId}` (RFC 0072 §A). Read-only — never carries the
+ * One installed manifest agent, as projected by `GET /agents` /
+ * `GET /agents/{agentId}` (RFC 0072 §A). Read-only — never carries the
  * system-prompt body, resolved handoff schemas, or credential material (SR-1).
  */
 export interface AgentInventoryEntry {
@@ -1653,7 +1400,7 @@ export interface AgentInventoryEntry {
   degraded?: string[];
 }
 
-/** Response body for `GET /v1/agents` (RFC 0072 §A). */
+/** Response body for `GET /agents` (RFC 0072 §A). */
 export interface AgentInventoryResponse {
   agents: AgentInventoryEntry[];
   total: number;
@@ -1674,7 +1421,7 @@ export interface AgentRosterEntry {
   description?: string;
 }
 
-/** Response for `GET /v1/agents/roster` (RFC 0086 §B). */
+/** Response for `GET /agents/roster` (RFC 0086 §B). */
 export interface AgentRosterResponse {
   roster: AgentRosterEntry[];
   total: number;
@@ -1704,7 +1451,7 @@ export interface AgentOrgChart {
   members: OrgChartMember[];
 }
 
-/** Response for `GET /v1/agents/org-chart/{departmentId}` (RFC 0087 §D) — the
+/** Response for `GET /agents/org-chart/{departmentId}` (RFC 0087 §D) — the
  *  department subtree + the responsibility roll-up (union of member portfolios). */
 export interface OrgChartResponsibilityView {
   department: OrgChartDepartment;
@@ -1716,94 +1463,12 @@ export interface OrgChartResponsibilityView {
  * Backs the workflow-engine sample app's Agents tab. Pack-installed
  * agents come through `AgentInventoryEntry` above (RFC 0072 §A
  * normative inventory). The types below mirror the sample-host
- * `POST /v1/host/sample/agents` create surface — they're scoped to
+ * `POST /host/sample/agents` create surface — they're scoped to
  * the sample-extension and may evolve independently of the
  * normative agent surface. Future RFC promotion would migrate these
  * to the normative wire shape.
  */
 
-/** Body for `POST /v1/host/sample/agents`. The server synthesises
- *  the agentId as `user.<tenantId>.<persona-slug>`. */
-export interface CreateUserAgentRequest {
-  /** Short name; becomes the `@`-mention slug and chat panel label.
-   *  Required, ≤64 chars. */
-  persona: string;
-  /** Longer display name; defaults to the persona when omitted. */
-  label?: string;
-  description?: string;
-  /** One of: `chat`, `reasoning`, `coding`, `extraction`. */
-  modelClass: string;
-  /** Inline system prompt body; ≤16 000 chars. The sample-host stores
-   *  it directly (no pack-file ref). */
-  systemPrompt: string;
-  /** Capability ids the agent is allowed to call; ≤32 entries. */
-  toolAllowlist?: string[];
-  memoryShape?: {
-    scratchpad?: boolean;
-    conversation?: boolean;
-    longTerm?: boolean;
-  };
-  /** 0.0-1.0; decisions below this are surfaced as low-confidence. */
-  confidenceThreshold?: number;
-}
-
-/** Response body for `POST /v1/host/sample/agents` — shaped to
- *  match `AgentInventoryEntry` minus normative-only fields, so a
- *  follow-up `GET /v1/agents` returns a row of the same shape. */
-export interface UserAgentRecord {
-  agentId: string;
-  persona: string;
-  label: string;
-  description?: string;
-  modelClass: string;
-  packName: string;
-  packVersion: string;
-  toolAllowlist: string[];
-  memoryShape: {
-    scratchpad: boolean;
-    conversation: boolean;
-    longTerm: boolean;
-  };
-  confidenceThreshold?: number;
-  hasHandoffSchemas: false;
-}
-
-/** One installable agent-pack summary from the sample host's local
- *  registry mirror (`GET /v1/host/sample/registry/agent-packs`). */
-export interface AgentPackSummary {
-  /** Pack name, e.g. `core.openwop.agents.code-reviewer`. */
-  name: string;
-  version: string;
-  description?: string;
-  /** Personas declared by the pack's `agents[]` (per RFC 0003). */
-  personas: string[];
-  /** True when at least one of the pack's agents is registered in
-   *  this host's in-process AgentRegistry. */
-  installed: boolean;
-}
-
-export interface AgentPackRegistryResponse {
-  packs: AgentPackSummary[];
-  total: number;
-}
-
-export interface InstallAgentPackRequest {
-  /** Must start with `core.openwop.agents.` — the sample's install
-   *  route filters to that namespace. */
-  name: string;
-  /** Defaults to `1.0.0` when omitted. */
-  version?: string;
-}
-
-export interface InstallAgentPackResponse {
-  name: string;
-  version: string;
-  /** True when the pack was newly installed; false when it was
-   *  already present in the registry. */
-  installed: boolean;
-  alreadyInstalled: boolean;
-}
-
 // ── RFC 0081 — Agent evaluation (eval-summary.schema.json) ─────────────
 
 /** Abstract model class (RFC 0002 / RFC 0003 manifest vocabulary). */
@@ -1871,7 +1536,7 @@ export type DeploymentState =
 
 /**
  * RFC 0078 §B — a portable tool descriptor as projected onto the host's
- * `GET /v1/tools` catalog. Source-agnostic (node-pack / workflow / mcp /
+ * `GET /tools` catalog. Source-agnostic (node-pack / workflow / mcp /
  * connector / host-extension); `safetyTier`, `egress`, and `approval` let a
  * caller reason about a tool's blast radius before invoking it.
  */
@@ -1893,8 +1558,8 @@ export interface ToolDescriptor {
 
 /**
  * RFC 0112 — a compact, model-facing projection of `ToolDescriptor`, returned by
- * `GET /v1/tools?view=compact` (envelope `{ tools: CompactToolDescriptor[] }`) +
- * `GET /v1/tools/{toolId}?view=compact` when the host advertises
+ * `GET /tools?view=compact` (envelope `{ tools: CompactToolDescriptor[] }`) +
+ * `GET /tools/{toolId}?view=compact` when the host advertises
  * `capabilities.toolCatalog.compactView`. The heavy descriptor fields
  * (`outputSchema`/`auth`/`egress`/`approval`/`replayPolicy`/`costHint`/`latencyHint`)
  * are dropped, and any `inputSchema` is bounded to the compact structural subset
@@ -1941,7 +1606,7 @@ export interface AgentDeploymentTransition {
   reason?: string;
 }
 
-// ── RFC 0103 Localized content surface (spec/v1/localized-content.md) ──
+// ── RFC 0103 Localized content surface (spec/v2/core/localized-content.md) ──
 // Mirror schemas/localized-content-*.schema.json. Host-defined structured
 // content (`data`, `localizations`, `seo`) is kept open per the schemas
 // (additionalProperties: true) — it is the host's content model, not a
@@ -1977,7 +1642,7 @@ export interface LocalizedContentSection {
   order: number;
 }
 
-/** Public delivery response for `GET /v1/content/pages/{slug}` — the negotiated
+/** Public delivery response for `GET /content/pages/{slug}` — the negotiated
  *  locale's resolved page + sections (the RFC 0103 `resolveSection` merge is
  *  applied host-side: exact → language-family → base). */
 export interface LocalizedContentPageResponse {
@@ -1998,7 +1663,7 @@ export interface LocalizedContentLanguageSettings {
   autoTranslateOnPublish: boolean;
 }
 
-/** Request body for `PUT /v1/content/pages/{pageId}/sections/{sectionId}`. */
+/** Request body for `PUT /content/pages/{pageId}/sections/{sectionId}`. */
 export interface PutContentSectionRequest {
   /** Target locale; the baseLocale upserts `data`, else `localizations[locale]`. */
   locale: string;
@@ -2006,9 +1671,9 @@ export interface PutContentSectionRequest {
   data: Record<string, unknown>;
 }
 
-// ── RFC 0099 Trigger subscription registration (spec/v1/trigger-bridge.md §F) ──
+// ── RFC 0099 Trigger subscription registration (spec/v2/core/trigger-bridge.md §F) ──
 
-/** Registration body for `POST /v1/trigger-subscriptions`
+/** Registration body for `POST /trigger-subscriptions`
  *  (`schemas/trigger-subscription-registration.schema.json`). */
 export interface TriggerSubscriptionRegistration {
   /** External event source descriptor (host-defined: webhook / email / form …). */
@@ -2025,7 +1690,7 @@ export interface TriggerSubscriptionRegistration {
  *  registration fields the host echoes back. */
 export type TriggerSubscription = Record<string, unknown>;
 
-/** `201` response for `POST /v1/trigger-subscriptions`. `binding` carries the
+/** `201` response for `POST /trigger-subscriptions`. `binding` carries the
  *  source-specific wiring the caller needs (e.g. `{ ingestUrl,
  *  secretFingerprint }` for webhook); the secret is returned ONCE at creation
  *  (SR-1) — persist it, it is not retrievable again. */