@opengeni/config 0.5.1 → 0.6.9

package/src/index.ts

@@ -6,10 +6,24 @@ import {
   ProductAccessMode,
   ReasoningEffort,
   SandboxBackend,
+  SessionMcpApprovalPolicy,
   StaticUsageLimits,
+  TurnExecutionPolicyV1,
   UsageLimitsMode,
+  type TurnExecutionModelSourceV1,
+  type TurnExecutionReasoningSourceV1,
 } from "@opengeni/contracts";
-import { CODEX_MODEL_ID_PREFIX, CODEX_PROVIDER_ID } from "@opengeni/codex/constants";
+import { CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS } from "@opengeni/codex";
+import {
+  CODEX_FALLBACK_MODEL_SLUGS,
+  CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT,
+  CODEX_MODEL_CONTEXT_WINDOW_TOKENS,
+  CODEX_MODEL_EFFECTIVE_CONTEXT_WINDOW_TOKENS,
+  CODEX_MODEL_ID_PREFIX,
+  CODEX_PROVIDER_BASE_URL,
+  CODEX_PROVIDER_ID,
+} from "@opengeni/codex/constants";
+import { createHash } from "node:crypto";
 import { z } from "zod";
 
 const envName = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -90,7 +104,7 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
   "You are an OpenGeni workspace agent.",
   "Follow the user's task and any enabled pack or skill instructions for the current role.",
   "Work inside the sandbox workspace and use filesystem and shell tools when useful.",
-  "Repository resources are mounted under repos/<owner>/<repo>.",
+  "Repository resources are mounted under repos/<host>/<owner>/<repo> unless the session specifies another collision-free mount path.",
   "File resources are mounted under files/<file-id>/ unless the session specifies another mount path.",
   "Attached files are mounted read-only; copy them before modifying.",
   "Bundled skills are under .agents/ and can include infrastructure, marketing, or other role-specific guidance.",
@@ -103,14 +117,59 @@ export const DEFAULT_AGENT_INSTRUCTIONS = [
 
 export const McpServerConnectionRefSchema = z
   .object({
-    connectionId: z.string().uuid().optional(),
+    // Standalone ids are UUIDs; embedded hosts may use any stable opaque id.
+    connectionId: z.string().min(1).optional(),
+    provider: z.string().min(1).max(128).optional(),
     providerDomain: z.string().min(1),
     kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
     scopes: z.array(z.string().min(1)).optional(),
     resource: z.string().min(1).optional(),
+    selectedResources: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(512),
+            kind: z.literal("repository"),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(256)
+      .superRefine((resources, context) => {
+        const seen = new Set<string>();
+        for (const [index, resource] of resources.entries()) {
+          const key = `${resource.kind}\0${resource.id}`;
+          if (seen.has(key)) {
+            context.addIssue({
+              code: "custom",
+              message: "selectedResources must not contain duplicates",
+              path: [index],
+            });
+          }
+          seen.add(key);
+        }
+      })
+      .optional(),
     subjectScope: z.enum(["workspace", "subject"]).optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((reference, context) => {
+    if (!reference.selectedResources) return;
+    if (!reference.connectionId) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires connectionId",
+        path: ["connectionId"],
+      });
+    }
+    if (!reference.provider) {
+      context.addIssue({
+        code: "custom",
+        message: "selectedResources requires provider",
+        path: ["provider"],
+      });
+    }
+  });
 export type McpServerConnectionRef = z.infer<typeof McpServerConnectionRefSchema>;
 
 const SettingsSchema = z.object({
@@ -125,7 +184,7 @@ const SettingsSchema = z.object({
   // topology. Default "" → standalone: no search_path scoping, server default
   // (`public`). When set (e.g. "opengeni"), the db handle + the managed-auth
   // pool send `search_path = "<dbSchema>","opengeni_private","public"` so every
-  // query resolves into the dedicated schema with NO query rewrite (SPIKE-1 F1).
+  // query resolves into the dedicated schema with NO query rewrite (schema-isolation contract F1).
   dbSchema: z.string().default(""),
   // Step I (§7.7). RLS posture. "force" (default) = today's FORCE-RLS via the
   // non-owner `opengeni_app` role. "scoped" = the embedded owner-role path (the
@@ -135,6 +194,12 @@ const SettingsSchema = z.object({
   temporalHost: z.string().default("127.0.0.1:7233"),
   temporalNamespace: z.string().default("default"),
   temporalTaskQueue: z.string().default("opengeni-runs-ts"),
+  temporalTlsEnabled: EnvBoolean.default(false),
+  temporalApiKey: z.string().optional(),
+  temporalTlsServerName: z.string().optional(),
+  temporalTlsRootCaCertificateBase64: z.string().optional(),
+  temporalTlsClientCertificateBase64: z.string().optional(),
+  temporalTlsClientPrivateKeyBase64: z.string().optional(),
   startupDependencyRetryAttempts: z.coerce.number().int().positive().default(30),
   startupDependencyRetryInitialDelayMs: z.coerce.number().int().positive().default(1000),
   startupDependencyRetryMaxDelayMs: z.coerce.number().int().positive().default(5000),
@@ -157,18 +222,28 @@ const SettingsSchema = z.object({
   staticEntitlementsJson: z.string().default("{}"),
   staticUsageLimitsJson: z.string().default("{}"),
   delegationSecret: z.string().optional(),
-  // Sandbox-surfacing scoped stream-token HMAC secret (master-spine §C.3 / I8).
+  // sandbox workspace scoped stream-token HMAC secret (sandbox contract §C.3 / stream-token availability contract).
   // When unset, the API falls back to `delegationSecret` (the same HMAC envelope
   // family, `ogs_` vs `ogd_` prefix). REQUIRED-WHEN-DESKTOP, but the absence of
   // BOTH while sandboxDesktopEnabled=true is a GRACEFUL DEGRADE (DesktopStream
-  // transport:null + a loud boot warning), NOT a hard boot-fail (I8/OD-8).
+  // transport:null + a loud boot warning), NOT a hard boot-fail (stream-token availability contract).
   streamTokenSecret: z.string().optional(),
   // The desktop input plane (raw stream:control writes) is OFF in v1: even a
   // holder of stream:control gets 403 until this flips. Keeps stream:control a
   // declared-but-inert permission so later hardening is a flag flip.
   streamControlEnabled: EnvBoolean.default(false),
+  // Existing-session explicit tool replacement is gated until every API and
+  // worker instance understands durable tools_provided provenance.
+  sessionTurnToolReplacementEnabled: EnvBoolean.default(false),
   toolspaceEnabled: EnvBoolean.default(false),
   toolspaceMaxCallsPerTurn: z.coerce.number().int().positive().default(200),
+  // Optional release-coherent bootstrap hint for custom rigs/connected machines
+  // that do not carry the stock-image ogtool binary. Exact stable versions only:
+  // the agent must never guess a tag or silently install `latest`.
+  ogtoolPackageSpec: z
+    .string()
+    .regex(/^@opengeni\/ogtool@(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u)
+    .optional(),
   environmentsEncryptionKey: z.string().optional(),
   integrationsEnabled: EnvBoolean.default(false),
   integrationsStateSecret: z.string().optional(),
@@ -216,6 +291,10 @@ const SettingsSchema = z.object({
   // Model-catalog auto-compact limit. When present it is clamped to
   // 90% of the raw window, matching Codex core's auto_compact_token_limit().
   contextAutoCompactThresholdTokens: z.coerce.number().int().positive().optional(),
+  // Provider-neutral fallback for canonical model-facing tool-result text.
+  // The current stable Codex catalog policy is 10k tokens; the truncator adds
+  // Codex's 1.2x JSON serialization allowance when applying it.
+  modelToolOutputTruncationTokens: z.coerce.number().int().positive().default(10_000),
   authRequired: EnvBoolean.default(false),
   accessKey: z.string().optional(),
   authAllowHealth: EnvBoolean.default(true),
@@ -249,15 +328,11 @@ const SettingsSchema = z.object({
   // tool that BM25-discloses only the matching connectors. Default OFF — a codex
   // turn is byte-for-byte unchanged until enabled. OPENGENI_CODEX_TOOL_SEARCH_ENABLED
   codexToolSearchEnabled: EnvBoolean.default(false),
-  // OPE-21 atomic, workspace-local credential allocation. Default OFF is a
+  // credential allocator atomic, workspace-local credential allocation. Default OFF is a
   // deliberate rolling-deploy fence: migrate + roll every worker first, then
   // enable. Turning it off restores the legacy sticky selector without a schema
   // rollback; the additive lease table/cursor columns become inert.
   codexCredentialLeasingEnabled: EnvBoolean.default(false),
-  // Multi-account P3 (auto-rotation): an account is "near exhaustion" — ineligible to be
-  // rotated TO — when EITHER usage window (5h/weekly) is at/over this percent. Default 90 to
-  // match the UI danger flip (UsageBar danger at pct >= 90). OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT.
-  codexRotationNearExhaustionPct: z.coerce.number().int().min(1).max(100).default(90),
   openaiReasoningEffort: ReasoningEffort.default("low"),
   openaiAllowedReasoningEfforts: z.string().default("low,medium,high,xhigh"),
   openaiResponsesTransport: z.enum(["http", "websocket"]).default("http"),
@@ -398,7 +473,7 @@ const SettingsSchema = z.object({
   // recordingMaxSeconds is the ffmpeg -t hard ceiling (bounds a multi-day turn).
   recordingEnabled: EnvBoolean.default(true),
   recordingDefaultCodec: z.enum(["h264-mp4", "vp9-webm"]).default("h264-mp4"),
-  // Workbench v2 turn-end workspace capture (dossier §10.1). When on, the turn
+  // Workbench v2 turn-end workspace capture. When on, the turn
   // activity probes the box's changed files off the live box at turn end and
   // persists a capture revision (blobs in @opengeni/storage) so the workbench
   // paints cold/offline sessions with zero machine round-trips. Best-effort and
@@ -458,6 +533,15 @@ const SettingsSchema = z.object({
   // EnvBoolean (NOT z.coerce.boolean(), which would coerce "false" -> true and
   // turn the flag ON the moment anyone set the env var to disable it).
   sandboxOwnershipEnabled: EnvBoolean.default(false),
+  // --- standalone rig-verifier ownership rollout flag, default OFF ---
+  // Rig verification creates a throwaway provider sandbox outside the normal
+  // session-turn path. When enabled, that sandbox must first acquire the same
+  // durable lease lifecycle used by session boxes so the global orphan sweep
+  // recognizes its exact provider instance. Keep this separate from the general
+  // sandboxOwnershipEnabled rollout: every reaper worker must understand verifier
+  // leases before dispatch is enabled. When false the verifier fails closed before
+  // provider create; it never falls back to the legacy unowned path.
+  rigVerificationLeaseOwnershipEnabled: EnvBoolean.default(false),
   // --- lazy sandbox provisioning rollout flag, default OFF ---
   // Only effective when sandboxOwnershipEnabled is ALSO on (lazy provisioning is a
   // property of the owned path — the SDK never creates/resumes an injected session,
@@ -477,7 +561,7 @@ const SettingsSchema = z.object({
   // 404 (invisible — the surface does not exist for this deployment) and the
   // selfhosted backend is inert; boot is unaffected. EnvBoolean (NOT
   // z.coerce.boolean(), which coerces "false" -> true). Flipped per-environment via
-  // the deploy-staging IaC secret/configmap pattern (dossier §17/§25.1).
+  // the deploy-staging IaC secret/configmap pattern.
   sandboxSelfhostedEnabled: EnvBoolean.default(false),
   // Gates the op-stream (streaming exec) transport to Connected Machines. The
   // runner must ALSO advertise Capabilities.op_stream; default off, and legacy
@@ -497,7 +581,7 @@ const SettingsSchema = z.object({
   selfhostedNatsUrl: z.string().optional(),
   selfhostedRelayUrl: z.string().optional(),
   // The HMAC secret the control plane signs the agent's relay PRODUCER token with
-  // (the `ogr_` envelope threaded into EnrollmentCredentials.relayToken; M8b/dossier
+  // (the `ogr_` envelope threaded into EnrollmentCredentials.relayToken; M8b/design
   // §10.5). The relay verifies the producer token with the SAME secret. Optional:
   // when ABSENT the poll returns an empty relayToken (graceful degrade — the stream
   // plane is simply unavailable until configured). Falls back to streamTokenSecret /
@@ -507,7 +591,7 @@ const SettingsSchema = z.object({
   // The minisign PUBLIC key the agent pins for self-update verification (handed to
   // the agent in EnrollmentCredentials; the SECRET key lives only in CI).
   agentUpdatePublicKey: z.string().optional(),
-  // --- NATS auth-callout tenancy boundary (bring-your-own-compute M-AUTH; dossier
+  // --- NATS auth-callout tenancy boundary (bring-your-own-compute M-AUTH; design
   //     §10.1 NATS Accounts per workspace + §17 the isolation smoke) -------------
   // nats-server is configured with AUTH CALLOUT: an external agent connects
   // presenting its `oge_` enrollment bearer as the connect auth-token; the server
@@ -678,14 +762,8 @@ const SettingsSchema = z.object({
         allowedTools: z.array(z.string().min(1)).optional(),
         timeoutMs: z.number().int().positive().optional(),
         cacheToolsList: z.boolean().default(false),
-        /**
-         * Human-approval policy for this server's tools, overlaid per-run from a
-         * session MCP server row (never from OPENGENI_MCP_SERVERS). `true` = all
-         * tools require approval; a string[] = only the listed UNPREFIXED tool
-         * names do; absent = auto-run (the historical default). Enforced in the
-         * runtime by attaching `needsApproval` to the matching MCP tools.
-         */
-        requireApproval: z.union([z.boolean(), z.array(z.string().min(1))]).optional(),
+        /** Runtime approval policy, overlaid from an attempt-frozen session snapshot. */
+        requireApproval: SessionMcpApprovalPolicy.optional(),
         /**
          * Extra request headers sent to this MCP server (credential injection
          * for workspace-enabled capability MCPs). Populated at runtime from
@@ -701,12 +779,34 @@ const SettingsSchema = z.object({
 
 export type Settings = z.infer<typeof SettingsSchema>;
 export type McpServerConfig = Settings["mcpServers"][number];
+export type TemporalTlsConnectionConfig = {
+  serverNameOverride?: string;
+  serverRootCACertificate?: Uint8Array;
+  clientCertPair?: {
+    crt: Uint8Array;
+    key: Uint8Array;
+  };
+};
+export type TemporalConnectionOptions = {
+  address: string;
+  tls?: true | TemporalTlsConnectionConfig;
+  apiKey?: string;
+};
 export type ModelPricing = {
   inputMicrosPerMillionTokens: number;
   cachedInputMicrosPerMillionTokens?: number | undefined;
   outputMicrosPerMillionTokens: number;
   marginBps?: number | undefined;
 };
+export type ModelPricingScheduleV1 = {
+  default: ModelPricing;
+  inputTokenTiers?:
+    | Array<{
+        minimumInputTokens: number;
+        pricing: ModelPricing;
+      }>
+    | undefined;
+};
 export type ModelUsageInput = {
   inputTokens?: number | undefined;
   outputTokens?: number | undefined;
@@ -725,6 +825,164 @@ const ModelPricingSchema = z.object({
   marginBps: z.number().int().min(0).max(100_000).optional(),
 });
 
+const ModelPricingScheduleSchema = z
+  .object({
+    default: ModelPricingSchema,
+    inputTokenTiers: z
+      .array(
+        z.object({
+          minimumInputTokens: z.number().int().nonnegative(),
+          pricing: ModelPricingSchema,
+        }),
+      )
+      .optional(),
+  })
+  .superRefine((schedule, ctx) => {
+    let previous = -1;
+    for (const [index, tier] of (schedule.inputTokenTiers ?? []).entries()) {
+      if (tier.minimumInputTokens <= previous) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["inputTokenTiers", index, "minimumInputTokens"],
+          message: "input-token tier thresholds must be strictly increasing",
+        });
+      }
+      previous = tier.minimumInputTokens;
+    }
+  });
+
+export const CapabilitySupportV1 = z.enum(["supported", "unsupported", "unknown"]);
+export type CapabilitySupportV1 = z.infer<typeof CapabilitySupportV1>;
+
+export const CapabilityStateV1Schema = z
+  .object({
+    upstream: CapabilitySupportV1,
+    runnable: z.boolean(),
+  })
+  .superRefine((state, ctx) => {
+    if (state.upstream === "unsupported" && state.runnable) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["runnable"],
+        message: "an upstream-unsupported capability cannot be runnable",
+      });
+    }
+  });
+export type CapabilityStateV1 = z.infer<typeof CapabilityStateV1Schema>;
+
+const ModelModalityV1 = z.enum(["text", "image", "audio"]);
+const ModelLatencyModeV1 = z.enum(["standard", "priority", "fast"]);
+
+export const ModelCapabilitiesV1Schema = z
+  .object({
+    reasoning: CapabilityStateV1Schema.extend({
+      efforts: z.array(ReasoningEffort),
+      defaultEffort: ReasoningEffort.nullable(),
+      required: z.boolean(),
+    }),
+    functionCalling: CapabilityStateV1Schema,
+    structuredOutput: CapabilityStateV1Schema,
+    hostedTools: z.object({
+      webSearch: CapabilityStateV1Schema,
+      xSearch: CapabilityStateV1Schema,
+      codeExecution: CapabilityStateV1Schema,
+    }),
+    inputModalities: z.array(ModelModalityV1).min(1),
+    outputModalities: z.array(ModelModalityV1).min(1),
+    transports: z.object({
+      sse: CapabilityStateV1Schema,
+      responsesWebSocket: CapabilityStateV1Schema,
+      realtimeAudio: CapabilityStateV1Schema,
+    }),
+    latencyModes: z
+      .array(
+        z.object({
+          id: ModelLatencyModeV1,
+          upstream: CapabilitySupportV1,
+          runnable: z.boolean(),
+          billingMultiplierBps: z.number().int().positive().optional(),
+        }),
+      )
+      .min(1),
+  })
+  .superRefine((capabilities, ctx) => {
+    const efforts = new Set(capabilities.reasoning.efforts);
+    if (efforts.size !== capabilities.reasoning.efforts.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["reasoning", "efforts"],
+        message: "reasoning efforts must be unique",
+      });
+    }
+    if (
+      capabilities.reasoning.defaultEffort !== null &&
+      !efforts.has(capabilities.reasoning.defaultEffort)
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["reasoning", "defaultEffort"],
+        message: "the default reasoning effort must be one of the supported efforts",
+      });
+    }
+    if (capabilities.reasoning.runnable && capabilities.reasoning.efforts.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["reasoning", "efforts"],
+        message: "a runnable reasoning capability must declare at least one effort",
+      });
+    }
+    for (const field of ["inputModalities", "outputModalities"] as const) {
+      if (new Set(capabilities[field]).size !== capabilities[field].length) {
+        ctx.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} must be unique`,
+        });
+      }
+    }
+    const latencyIds = new Set<string>();
+    for (const [index, mode] of capabilities.latencyModes.entries()) {
+      if (latencyIds.has(mode.id)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["latencyModes", index, "id"],
+          message: "latency mode ids must be unique",
+        });
+      }
+      latencyIds.add(mode.id);
+      if (mode.upstream === "unsupported" && mode.runnable) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["latencyModes", index, "runnable"],
+          message: "an upstream-unsupported latency mode cannot be runnable",
+        });
+      }
+    }
+  });
+export type ModelCapabilitiesV1 = z.infer<typeof ModelCapabilitiesV1Schema>;
+
+export type ModelDeploymentV1 = {
+  upstreamModelId: string;
+  wireApi: ModelProviderApi;
+};
+
+export type ModelExecutionLimitsV1 = {
+  contextWindowTokens: number | null;
+  effectiveContextWindowTokens: number | null;
+  autoCompactTokenLimit: number | null;
+  toolOutputTruncationTokens: number | null;
+};
+
+export type CredentialSourceV1 =
+  | { kind: "deployment"; mechanism: "api_key" | "azure_ad_bearer" }
+  | { kind: "connected_subscription"; provider: "codex" }
+  | { kind: "workspace_connection"; mechanism: "api_key" };
+
+export type BillingAttributionV1 = {
+  upstreamPayer: "deployment" | "workspace" | "connected_subscription";
+  metering: "opengeni_credits" | "external";
+};
+
 /**
  * Wire API a provider speaks. The built-in OpenAI/Azure provider always uses
  * "responses" (the OpenAI Responses API). Extra registry providers default to
@@ -744,16 +1002,52 @@ export const RegistryProviderKind = z.enum(["api-key", "codex-subscription"]);
 export type RegistryProviderKind = z.infer<typeof RegistryProviderKind>;
 
 /** A single model exposed by a registry provider. */
-const RegistryModelSchema = z.object({
-  id: z.string().min(1), // model id sent to the provider, e.g. "accounts/fireworks/models/glm-5p2"
-  label: z.string().min(1).optional(), // display name; defaults to id
-  contextWindowTokens: z.number().int().positive().optional(),
-  effectiveContextWindowTokens: z.number().int().positive().optional(),
-  autoCompactTokenLimit: z.number().int().positive().optional(),
-  reasoningEffort: z.boolean().optional(), // model accepts a reasoning-effort control
-  hostedWebSearch: z.boolean().optional(), // provider executes the hosted web_search tool for this model
-  pricing: ModelPricingSchema.optional(),
-});
+const RegistryModelSchema = z
+  .object({
+    id: z.string().min(1), // canonical OpenGeni product id
+    upstreamModelId: z.string().min(1).optional(), // exact provider slug; defaults to id
+    aliases: z.array(z.string().min(1)).optional(), // accepted input only; never sent upstream
+    label: z.string().min(1).optional(), // display name; defaults to id
+    contextWindowTokens: z.number().int().positive().optional(),
+    effectiveContextWindowTokens: z.number().int().positive().optional(),
+    autoCompactTokenLimit: z.number().int().positive().optional(),
+    // Canonical model-facing function/tool-result policy. The runtime applies
+    // the same 1.2x serialization allowance as Codex when materializing output.
+    toolOutputTruncationTokens: z.number().int().positive().optional(),
+    reasoningEffort: z.boolean().optional(), // legacy compatibility input/projection
+    hostedWebSearch: z.boolean().optional(), // legacy compatibility input/projection
+    capabilities: ModelCapabilitiesV1Schema.optional(),
+    pricing: z.union([ModelPricingSchema, ModelPricingScheduleSchema]).optional(),
+    // Reserved normalized contracts are derived by OpenGeni in V1. Generic
+    // registry JSON must not opt itself into workspace BYOK or reattribute cost.
+    credentialSource: z.never().optional(),
+    billing: z.never().optional(),
+  })
+  .superRefine((model, ctx) => {
+    if (
+      model.capabilities &&
+      model.reasoningEffort !== undefined &&
+      model.reasoningEffort !== model.capabilities.reasoning.runnable
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["reasoningEffort"],
+        message: "legacy reasoningEffort must agree with capabilities.reasoning.runnable",
+      });
+    }
+    if (
+      model.capabilities &&
+      model.hostedWebSearch !== undefined &&
+      model.hostedWebSearch !== model.capabilities.hostedTools.webSearch.runnable
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["hostedWebSearch"],
+        message:
+          "legacy hostedWebSearch must agree with capabilities.hostedTools.webSearch.runnable",
+      });
+    }
+  });
 
 /** A non-built-in provider declared by the host via OPENGENI_MODEL_PROVIDERS_JSON. */
 const RegistryProviderSchema = z.object({
@@ -766,6 +1060,12 @@ const RegistryProviderSchema = z.object({
   apiKeyEnv: z.string().optional(), // ... OR name of the env var holding the key (preferred)
   defaultQuery: z.record(z.string(), z.string()).optional(),
   defaultHeaders: z.record(z.string(), z.string()).optional(),
+  publicDefaultQueryNames: z.array(z.string().min(1)).optional(),
+  publicDefaultHeaderNames: z.array(z.string().min(1)).optional(),
+  // V1 derives these from provider kind. Workspace BYOK is deliberately not a
+  // registry switch and requires a separately reviewed encrypted broker.
+  credentialSource: z.never().optional(),
+  billing: z.never().optional(),
   models: z.array(RegistryModelSchema).min(1),
 });
 export type RegistryProvider = z.infer<typeof RegistryProviderSchema>;
@@ -796,18 +1096,33 @@ export interface ResolvedModelProvider {
   apiKey?: string | undefined;
   defaultQuery?: Record<string, string> | undefined;
   defaultHeaders?: Record<string, string> | undefined;
+  publicDefaultQueryNames?: string[] | undefined;
+  publicDefaultHeaderNames?: string[] | undefined;
+  credentialSource: CredentialSourceV1;
+  billing: BillingAttributionV1;
 }
 
 /** A single exposed model + the provider that serves it. */
 export interface ConfiguredModel {
+  schemaVersion: 1;
   id: string;
+  aliases: string[];
   label: string;
   providerId: string;
   providerLabel: string;
   api: ModelProviderApi;
+  upstreamModelId: string;
+  deployment: ModelDeploymentV1;
+  executionLimits: ModelExecutionLimitsV1;
+  credentialSource: CredentialSourceV1;
+  billing: BillingAttributionV1;
+  capabilities: ModelCapabilitiesV1;
+  pricing?: ModelPricingScheduleV1 | undefined;
+  definitionVersion: string;
   contextWindowTokens?: number | undefined;
   effectiveContextWindowTokens?: number | undefined;
   autoCompactTokenLimit?: number | undefined;
+  toolOutputTruncationTokens?: number | undefined;
   reasoningEffort: boolean;
   hostedWebSearch: boolean;
 }
@@ -971,6 +1286,14 @@ export function getSettings(): Settings {
     temporalHost: optional("OPENGENI_TEMPORAL_HOST"),
     temporalNamespace: optional("OPENGENI_TEMPORAL_NAMESPACE"),
     temporalTaskQueue: optional("OPENGENI_TEMPORAL_TASK_QUEUE"),
+    temporalTlsEnabled: optional("OPENGENI_TEMPORAL_TLS_ENABLED"),
+    temporalApiKey: optional("OPENGENI_TEMPORAL_API_KEY"),
+    temporalTlsServerName: optional("OPENGENI_TEMPORAL_TLS_SERVER_NAME"),
+    temporalTlsRootCaCertificateBase64: optional(
+      "OPENGENI_TEMPORAL_TLS_ROOT_CA_CERTIFICATE_BASE64",
+    ),
+    temporalTlsClientCertificateBase64: optional("OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64"),
+    temporalTlsClientPrivateKeyBase64: optional("OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64"),
     startupDependencyRetryAttempts: optional("OPENGENI_STARTUP_DEPENDENCY_RETRY_ATTEMPTS"),
     startupDependencyRetryInitialDelayMs: optional(
       "OPENGENI_STARTUP_DEPENDENCY_RETRY_INITIAL_DELAY_MS",
@@ -993,8 +1316,10 @@ export function getSettings(): Settings {
     delegationSecret: optional("OPENGENI_DELEGATION_SECRET"),
     streamTokenSecret: optional("OPENGENI_STREAM_TOKEN_SECRET"),
     streamControlEnabled: optional("OPENGENI_STREAM_CONTROL_ENABLED"),
+    sessionTurnToolReplacementEnabled: optional("OPENGENI_SESSION_TURN_TOOL_REPLACEMENT_ENABLED"),
     toolspaceEnabled: optional("OPENGENI_TOOLSPACE_ENABLED"),
     toolspaceMaxCallsPerTurn: optional("OPENGENI_TOOLSPACE_MAX_CALLS_PER_TURN"),
+    ogtoolPackageSpec: optional("OPENGENI_OGTOOL_PACKAGE_SPEC"),
     environmentsEncryptionKey: optional("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY"),
     integrationsEnabled: optional("OPENGENI_INTEGRATIONS_ENABLED"),
     integrationsStateSecret: optional("OPENGENI_INTEGRATIONS_STATE_SECRET"),
@@ -1010,6 +1335,7 @@ export function getSettings(): Settings {
     contextCompactionThresholdRatio: optional("OPENGENI_COMPACTION_THRESHOLD_RATIO"),
     contextReservedOutputTokens: optional("OPENGENI_CONTEXT_RESERVED_OUTPUT_TOKENS"),
     contextAutoCompactThresholdTokens: optional("OPENGENI_CONTEXT_AUTO_COMPACT_THRESHOLD_TOKENS"),
+    modelToolOutputTruncationTokens: optional("OPENGENI_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS"),
     authRequired: optional("OPENGENI_AUTH_REQUIRED"),
     accessKey: optional("OPENGENI_ACCESS_KEY"),
     authAllowHealth: optional("OPENGENI_AUTH_ALLOW_HEALTH"),
@@ -1030,7 +1356,6 @@ export function getSettings(): Settings {
     codexToolSearchEnabled: optional("OPENGENI_CODEX_TOOL_SEARCH_ENABLED"),
     codexCredentialLeasingEnabled: optional("OPENGENI_CODEX_CREDENTIAL_LEASING_ENABLED"),
     codexProductSku: optional("OPENGENI_CODEX_PRODUCT_SKU"),
-    codexRotationNearExhaustionPct: optional("OPENGENI_CODEX_ROTATION_NEAR_EXHAUSTION_PCT"),
     openaiReasoningEffort: optional("OPENGENI_OPENAI_REASONING_EFFORT"),
     openaiAllowedReasoningEfforts: optional("OPENGENI_OPENAI_ALLOWED_REASONING_EFFORTS"),
     openaiResponsesTransport: optional("OPENGENI_OPENAI_RESPONSES_TRANSPORT"),
@@ -1108,6 +1433,9 @@ export function getSettings(): Settings {
     vercelTeamId: optional("OPENGENI_VERCEL_TEAM_ID"),
     vercelRuntime: optional("OPENGENI_VERCEL_RUNTIME"),
     sandboxOwnershipEnabled: optional("OPENGENI_SANDBOX_OWNERSHIP_ENABLED"),
+    rigVerificationLeaseOwnershipEnabled: optional(
+      "OPENGENI_RIG_VERIFICATION_LEASE_OWNERSHIP_ENABLED",
+    ),
     sandboxLazyProvisionEnabled: optional("OPENGENI_SANDBOX_LAZY_PROVISION"),
     sandboxSelfhostedEnabled: optional("OPENGENI_SANDBOX_SELFHOSTED_ENABLED"),
     agentOpStreamEnabled: optional("OPENGENI_AGENT_OP_STREAM_ENABLED"),
@@ -1247,6 +1575,353 @@ export function resolveProviderApiKey(
   return undefined;
 }
 
+const HTTP_FIELD_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const CREDENTIAL_LIKE_NAME_PARTS = new Set([
+  "apikey",
+  "auth",
+  "authorization",
+  "bearer",
+  "credential",
+  "cookie",
+  "key",
+  "password",
+  "secret",
+  "session",
+  "signature",
+  "token",
+]);
+const REASONING_EFFORT_ORDER = new Map(
+  ReasoningEffort.options.map((effort, index) => [effort, index]),
+);
+const MODALITY_ORDER = new Map(["text", "image", "audio"].map((value, index) => [value, index]));
+const LATENCY_MODE_ORDER = new Map(
+  ["standard", "priority", "fast"].map((value, index) => [value, index]),
+);
+
+function normalizeRegistryBaseUrl(value: string, providerId: string): string {
+  const url = new URL(value);
+  if (url.username || url.password) {
+    throw new Error(`provider ${providerId} baseUrl must not contain userinfo`);
+  }
+  if (url.search) {
+    throw new Error(
+      `provider ${providerId} baseUrl must not contain a query; move query entries to defaultQuery`,
+    );
+  }
+  if (url.hash) {
+    throw new Error(`provider ${providerId} baseUrl must not contain a fragment`);
+  }
+  return url.toString();
+}
+
+function isCredentialLikeMetadataName(name: string): boolean {
+  return name
+    .toLowerCase()
+    .split(/[-_.]/u)
+    .some((part) => CREDENTIAL_LIKE_NAME_PARTS.has(part));
+}
+
+function normalizeHeaderMap(
+  providerId: string,
+  headers: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!headers) {
+    return undefined;
+  }
+  const normalized: Record<string, string> = {};
+  const rawByNormalized = new Map<string, string>();
+  for (const [rawName, value] of Object.entries(headers)) {
+    if (!HTTP_FIELD_NAME.test(rawName)) {
+      throw new Error(
+        `provider ${providerId} defaultHeaders contains invalid HTTP field name ${JSON.stringify(rawName)}`,
+      );
+    }
+    const name = rawName.toLowerCase();
+    const previous = rawByNormalized.get(name);
+    if (previous !== undefined) {
+      throw new Error(
+        `provider ${providerId} defaultHeaders names ${JSON.stringify(previous)} and ${JSON.stringify(rawName)} collide after lowercase normalization`,
+      );
+    }
+    if (name === "authorization") {
+      throw new Error(
+        `provider ${providerId} defaultHeaders must not override SDK-managed Authorization`,
+      );
+    }
+    rawByNormalized.set(name, rawName);
+    normalized[name] = value;
+  }
+  return normalized;
+}
+
+function normalizePublicHeaderNames(
+  providerId: string,
+  names: string[] | undefined,
+  headers: Record<string, string> | undefined,
+): string[] | undefined {
+  if (!names) {
+    return undefined;
+  }
+  const normalized: string[] = [];
+  const seen = new Set<string>();
+  for (const rawName of names) {
+    if (!HTTP_FIELD_NAME.test(rawName)) {
+      throw new Error(
+        `provider ${providerId} publicDefaultHeaderNames contains invalid HTTP field name ${JSON.stringify(rawName)}`,
+      );
+    }
+    const name = rawName.toLowerCase();
+    if (seen.has(name)) {
+      throw new Error(
+        `provider ${providerId} publicDefaultHeaderNames contains duplicate normalized name ${JSON.stringify(name)}`,
+      );
+    }
+    if (!(name in (headers ?? {}))) {
+      throw new Error(
+        `provider ${providerId} publicDefaultHeaderNames declares absent defaultHeaders entry ${JSON.stringify(name)}`,
+      );
+    }
+    if (isCredentialLikeMetadataName(name)) {
+      throw new Error(
+        `provider ${providerId} publicDefaultHeaderNames cannot classify credential-like name ${JSON.stringify(name)} as public`,
+      );
+    }
+    seen.add(name);
+    normalized.push(name);
+  }
+  return normalized;
+}
+
+function normalizeQueryMap(
+  providerId: string,
+  query: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  if (!query) {
+    return undefined;
+  }
+  for (const name of Object.keys(query)) {
+    if (!name) {
+      throw new Error(`provider ${providerId} defaultQuery contains an empty name`);
+    }
+  }
+  return { ...query };
+}
+
+function normalizePublicQueryNames(
+  providerId: string,
+  names: string[] | undefined,
+  query: Record<string, string> | undefined,
+): string[] | undefined {
+  if (!names) {
+    return undefined;
+  }
+  const seen = new Set<string>();
+  for (const name of names) {
+    if (seen.has(name)) {
+      throw new Error(
+        `provider ${providerId} publicDefaultQueryNames contains duplicate name ${JSON.stringify(name)}`,
+      );
+    }
+    if (!(name in (query ?? {}))) {
+      throw new Error(
+        `provider ${providerId} publicDefaultQueryNames declares absent defaultQuery entry ${JSON.stringify(name)}`,
+      );
+    }
+    if (isCredentialLikeMetadataName(name)) {
+      throw new Error(
+        `provider ${providerId} publicDefaultQueryNames cannot classify credential-like name ${JSON.stringify(name)} as public`,
+      );
+    }
+    seen.add(name);
+  }
+  return [...names];
+}
+
+function normalizeRegistryProvider(provider: RegistryProvider): RegistryProvider {
+  const defaultHeaders = normalizeHeaderMap(provider.id, provider.defaultHeaders);
+  const defaultQuery = normalizeQueryMap(provider.id, provider.defaultQuery);
+  return {
+    ...provider,
+    baseUrl: normalizeRegistryBaseUrl(provider.baseUrl, provider.id),
+    ...(defaultHeaders === undefined ? {} : { defaultHeaders }),
+    ...(defaultQuery === undefined ? {} : { defaultQuery }),
+    ...(provider.publicDefaultHeaderNames === undefined
+      ? {}
+      : {
+          publicDefaultHeaderNames: normalizePublicHeaderNames(
+            provider.id,
+            provider.publicDefaultHeaderNames,
+            defaultHeaders,
+          ),
+        }),
+    ...(provider.publicDefaultQueryNames === undefined
+      ? {}
+      : {
+          publicDefaultQueryNames: normalizePublicQueryNames(
+            provider.id,
+            provider.publicDefaultQueryNames,
+            defaultQuery,
+          ),
+        }),
+  };
+}
+
+function normalizeModelPricingSchedule(
+  pricing: ModelPricing | ModelPricingScheduleV1,
+): ModelPricingScheduleV1 {
+  return "default" in pricing ? pricing : { default: pricing };
+}
+
+function normalizeCapabilities(capabilities: ModelCapabilitiesV1): ModelCapabilitiesV1 {
+  const parsed = ModelCapabilitiesV1Schema.parse(capabilities);
+  return {
+    ...parsed,
+    reasoning: {
+      ...parsed.reasoning,
+      efforts: [...parsed.reasoning.efforts].sort(
+        (left, right) =>
+          (REASONING_EFFORT_ORDER.get(left) ?? 0) - (REASONING_EFFORT_ORDER.get(right) ?? 0),
+      ),
+    },
+    inputModalities: [...parsed.inputModalities].sort(
+      (left, right) => (MODALITY_ORDER.get(left) ?? 0) - (MODALITY_ORDER.get(right) ?? 0),
+    ),
+    outputModalities: [...parsed.outputModalities].sort(
+      (left, right) => (MODALITY_ORDER.get(left) ?? 0) - (MODALITY_ORDER.get(right) ?? 0),
+    ),
+    latencyModes: [...parsed.latencyModes].sort(
+      (left, right) =>
+        (LATENCY_MODE_ORDER.get(left.id) ?? 0) - (LATENCY_MODE_ORDER.get(right.id) ?? 0),
+    ),
+  };
+}
+
+function legacyModelCapabilities(
+  settings: Settings,
+  input: { reasoningEffort: boolean; hostedWebSearch: boolean },
+): ModelCapabilitiesV1 {
+  const reasoningEfforts = input.reasoningEffort ? configuredAllowedReasoningEfforts(settings) : [];
+  return normalizeCapabilities({
+    reasoning: {
+      upstream: input.reasoningEffort ? "supported" : "unknown",
+      runnable: input.reasoningEffort,
+      efforts: reasoningEfforts,
+      defaultEffort: input.reasoningEffort ? settings.openaiReasoningEffort : null,
+      required: false,
+    },
+    functionCalling: { upstream: "unknown", runnable: true },
+    structuredOutput: { upstream: "unknown", runnable: false },
+    hostedTools: {
+      webSearch: {
+        upstream: input.hostedWebSearch ? "supported" : "unknown",
+        runnable: input.hostedWebSearch,
+      },
+      xSearch: { upstream: "unknown", runnable: false },
+      codeExecution: { upstream: "unknown", runnable: false },
+    },
+    inputModalities: ["text"],
+    outputModalities: ["text"],
+    transports: {
+      sse: { upstream: "unknown", runnable: true },
+      responsesWebSocket: { upstream: "unknown", runnable: false },
+      realtimeAudio: { upstream: "unknown", runnable: false },
+    },
+    latencyModes: [{ id: "standard", upstream: "unknown", runnable: true }],
+  });
+}
+
+function registryCredentialSource(provider: RegistryProvider): CredentialSourceV1 {
+  return provider.kind === "codex-subscription"
+    ? { kind: "connected_subscription", provider: "codex" }
+    : { kind: "deployment", mechanism: "api_key" };
+}
+
+function registryBilling(provider: RegistryProvider): BillingAttributionV1 {
+  return provider.kind === "codex-subscription"
+    ? { upstreamPayer: "connected_subscription", metering: "external" }
+    : { upstreamPayer: "deployment", metering: "opengeni_credits" };
+}
+
+function builtinCredentialSource(settings: Settings): CredentialSourceV1 {
+  if (settings.openaiProvider === "azure" && !settings.azureOpenaiApiKey) {
+    return { kind: "deployment", mechanism: "azure_ad_bearer" };
+  }
+  return { kind: "deployment", mechanism: "api_key" };
+}
+
+function staticRequestMetadataForDigest(provider: ResolvedModelProvider): {
+  headers: Array<{ name: string; classification: "public" | "secret"; value?: string }>;
+  query: Array<{ name: string; classification: "public" | "secret"; value?: string }>;
+} {
+  const publicHeaders = new Set(provider.publicDefaultHeaderNames ?? []);
+  const publicQuery = new Set(provider.publicDefaultQueryNames ?? []);
+  return {
+    headers: Object.entries(provider.defaultHeaders ?? {})
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, value]) =>
+        publicHeaders.has(name)
+          ? { name, classification: "public" as const, value }
+          : { name, classification: "secret" as const },
+      ),
+    query: Object.entries(provider.defaultQuery ?? {})
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, value]) =>
+        publicQuery.has(name)
+          ? { name, classification: "public" as const, value }
+          : { name, classification: "secret" as const },
+      ),
+  };
+}
+
+function canonicalJson(value: unknown): string {
+  const normalize = (input: unknown): unknown => {
+    if (Array.isArray(input)) {
+      return input.map((entry) => normalize(entry));
+    }
+    if (input && typeof input === "object") {
+      const out: Record<string, unknown> = {};
+      for (const key of Object.keys(input).sort()) {
+        const child = (input as Record<string, unknown>)[key];
+        if (child !== undefined) {
+          out[key] = normalize(child);
+        }
+      }
+      return out;
+    }
+    return input;
+  };
+  return JSON.stringify(normalize(value));
+}
+
+function definitionVersionFor(
+  model: Omit<ConfiguredModel, "definitionVersion">,
+  provider: ResolvedModelProvider,
+): string {
+  const requestMetadata = staticRequestMetadataForDigest(provider);
+  const digestInput = canonicalJson({
+    schemaVersion: model.schemaVersion,
+    id: model.id,
+    providerId: model.providerId,
+    deployment: model.deployment,
+    provider: {
+      adapterKind: provider.kind,
+      wireApi: provider.api,
+      baseUrl: provider.baseUrl ?? null,
+      defaultHeaders: requestMetadata.headers,
+      defaultQuery: requestMetadata.query,
+    },
+    credentialSource: model.credentialSource,
+    billing: model.billing,
+    executionLimits: model.executionLimits,
+    capabilities: model.capabilities,
+    pricing: model.pricing ?? null,
+  });
+  return `sha256:${createHash("sha256")
+    .update("opengeni:model-definition:v1\n", "utf8")
+    .update(digestInput, "utf8")
+    .digest("hex")}`;
+}
+
 /**
  * The built-in provider's stable id: "openai" on the OpenAI platform, "azure"
  * on Azure. Exported because the workspace model-policy gate must attribute
@@ -1271,18 +1946,24 @@ function builtinProviderLabel(settings: Pick<Settings, "openaiProvider">): strin
  * id — validateSettings rejects that at boot.
  */
 export function configuredProviders(settings: Settings): ResolvedModelProvider[] {
+  const credentialSource = builtinCredentialSource(settings);
   const builtin: ResolvedModelProvider = {
     id: builtinProviderId(settings),
     label: builtinProviderLabel(settings),
     kind: "api-key",
     api: "responses",
     builtin: true,
+    credentialSource,
+    billing: { upstreamPayer: "deployment", metering: "opengeni_credits" },
   };
   if (settings.openaiProvider === "azure") {
-    builtin.baseUrl = settings.azureOpenaiBaseUrl ?? settings.azureOpenaiEndpoint;
+    const baseUrl = settings.azureOpenaiBaseUrl ?? settings.azureOpenaiEndpoint;
+    builtin.baseUrl = baseUrl ? normalizeRegistryBaseUrl(baseUrl, builtin.id) : undefined;
     builtin.apiKey = settings.azureOpenaiApiKey ?? settings.azureOpenaiAdToken;
   } else {
-    builtin.baseUrl = settings.openaiBaseUrl;
+    builtin.baseUrl = settings.openaiBaseUrl
+      ? normalizeRegistryBaseUrl(settings.openaiBaseUrl, builtin.id)
+      : undefined;
     builtin.apiKey = settings.openaiApiKey;
   }
   const registry = parseModelProvidersJson(settings.modelProvidersJson).map(
@@ -1296,11 +1977,46 @@ export function configuredProviders(settings: Settings): ResolvedModelProvider[]
       apiKey: resolveProviderApiKey(provider),
       defaultQuery: provider.defaultQuery,
       defaultHeaders: provider.defaultHeaders,
+      publicDefaultQueryNames: provider.publicDefaultQueryNames,
+      publicDefaultHeaderNames: provider.publicDefaultHeaderNames,
+      credentialSource: registryCredentialSource(provider),
+      billing: registryBilling(provider),
     }),
   );
   return [builtin, ...registry];
 }
 
+/**
+ * Pure catalog overlay for a workspace whose existing Codex connection seam
+ * reports ready. This describes product/provider identity only; it does not
+ * select, lease, refresh, or expose a concrete credential; those runtime
+ * operations remain owned by the credential allocator.
+ */
+export function withCodexCatalogProvider(settings: Settings): Settings {
+  const providers = parseModelProvidersJson(settings.modelProvidersJson);
+  if (providers.some((provider) => provider.id === CODEX_PROVIDER_ID)) {
+    return settings;
+  }
+  const provider: RegistryProvider = {
+    kind: "codex-subscription",
+    id: CODEX_PROVIDER_ID,
+    label: "Codex (ChatGPT subscription)",
+    api: "responses",
+    baseUrl: CODEX_PROVIDER_BASE_URL,
+    models: CODEX_FALLBACK_MODEL_SLUGS.map((slug) => ({
+      id: `${CODEX_MODEL_ID_PREFIX}${slug}`,
+      upstreamModelId: slug,
+      label: slug,
+      reasoningEffort: true,
+      contextWindowTokens: CODEX_MODEL_CONTEXT_WINDOW_TOKENS,
+      effectiveContextWindowTokens: CODEX_MODEL_EFFECTIVE_CONTEXT_WINDOW_TOKENS,
+      autoCompactTokenLimit: CODEX_MODEL_AUTO_COMPACT_TOKEN_LIMIT,
+      toolOutputTruncationTokens: CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
+    })),
+  };
+  return { ...settings, modelProvidersJson: JSON.stringify([...providers, provider]) };
+}
+
 /**
  * The provider identity a model id resolves to, for workspace model-policy
  * evaluation — MUST agree with the real router (resolveTurnModel /
@@ -1315,13 +2031,83 @@ export function configuredProviders(settings: Settings): ResolvedModelProvider[]
  *     serves. A policy blocking the built-in must block this path too.
  */
 export function policyProviderIdForModel(settings: Settings, modelId: string): string {
-  if (modelId.startsWith(CODEX_MODEL_ID_PREFIX)) {
+  const canonicalModelId = canonicalizeConfiguredModelId(settings, modelId);
+  if (canonicalModelId.startsWith(CODEX_MODEL_ID_PREFIX)) {
     return CODEX_PROVIDER_ID;
   }
-  const configured = configuredModels(settings).find((model) => model.id === modelId);
+  const configured = configuredModels(settings).find((model) => model.id === canonicalModelId);
   return configured?.providerId ?? builtinProviderId(settings);
 }
 
+function resolvedExecutionLimits(
+  settings: Settings,
+  model: {
+    contextWindowTokens?: number | undefined;
+    effectiveContextWindowTokens?: number | undefined;
+    autoCompactTokenLimit?: number | undefined;
+    toolOutputTruncationTokens?: number | undefined;
+  },
+): ModelExecutionLimitsV1 {
+  return {
+    contextWindowTokens: model.contextWindowTokens ?? settings.contextWindowTokens,
+    effectiveContextWindowTokens:
+      model.effectiveContextWindowTokens ?? settings.contextEffectiveWindowTokens ?? null,
+    autoCompactTokenLimit:
+      model.autoCompactTokenLimit ?? settings.contextAutoCompactThresholdTokens ?? null,
+    toolOutputTruncationTokens:
+      model.toolOutputTruncationTokens ?? settings.modelToolOutputTruncationTokens ?? null,
+  };
+}
+
+function finalizeConfiguredModel(
+  settings: Settings,
+  provider: ResolvedModelProvider,
+  input: Omit<ConfiguredModel, "schemaVersion" | "definitionVersion" | "executionLimits">,
+): ConfiguredModel {
+  const modelWithoutVersion: Omit<ConfiguredModel, "definitionVersion"> = {
+    schemaVersion: 1,
+    ...input,
+    executionLimits: resolvedExecutionLimits(settings, input),
+  };
+  return {
+    ...modelWithoutVersion,
+    definitionVersion: definitionVersionFor(modelWithoutVersion, provider),
+  };
+}
+
+function assertUniqueModelIdentities(models: ConfiguredModel[]): void {
+  const canonicalOwners = new Map<string, string>();
+  for (const model of models) {
+    const previous = canonicalOwners.get(model.id);
+    if (previous !== undefined) {
+      throw new Error(
+        `OPENGENI_MODEL_PROVIDERS_JSON model id ${JSON.stringify(model.id)} is declared by both ${previous} and ${model.providerId}`,
+      );
+    }
+    canonicalOwners.set(model.id, model.providerId);
+  }
+
+  const acceptedInputs = new Map(canonicalOwners);
+  for (const model of models) {
+    const ownAliases = new Set<string>();
+    for (const alias of model.aliases) {
+      if (ownAliases.has(alias)) {
+        throw new Error(
+          `OPENGENI_MODEL_PROVIDERS_JSON model ${JSON.stringify(model.id)} contains duplicate alias ${JSON.stringify(alias)}`,
+        );
+      }
+      ownAliases.add(alias);
+      const previous = acceptedInputs.get(alias);
+      if (previous !== undefined) {
+        throw new Error(
+          `OPENGENI_MODEL_PROVIDERS_JSON alias ${JSON.stringify(alias)} for model ${JSON.stringify(model.id)} collides with model/provider ${previous}`,
+        );
+      }
+      acceptedInputs.set(alias, model.id);
+    }
+  }
+}
+
 /**
  * Every model a client may use, the built-in provider's models first
  * (configuredAllowedModels-from-openai, mapped to "responses" with
@@ -1333,6 +2119,9 @@ export function policyProviderIdForModel(settings: Settings, modelId: string): s
 export function configuredModels(settings: Settings): ConfiguredModel[] {
   const builtinId = builtinProviderId(settings);
   const builtinLabel = builtinProviderLabel(settings);
+  const providers = configuredProviders(settings);
+  const providerById = new Map(providers.map((provider) => [provider.id, provider]));
+  const pricingSchedules = configuredModelPricingSchedules(settings);
   // The built-in (OpenAI/Azure) provider must NEVER claim a registry-namespaced
   // model id. The worker overwrites settings.openaiModel with the turn's model
   // (apps/worker agent-turn runSettings) — including a `codex/<slug>` id, or a
@@ -1349,59 +2138,110 @@ export function configuredModels(settings: Settings): ConfiguredModel[] {
   // a codex/ id has NO codex provider injected (no active subscription) it then
   // resolves to nothing and getModel fails loud with
   // CodexSubscriptionUnavailableError instead of mis-routing to Azure.
+  const parsedRegistry = parseModelProvidersJson(settings.modelProvidersJson);
   const registryOwnedIds = new Set(
-    parseModelProvidersJson(settings.modelProvidersJson).flatMap((provider) =>
-      provider.models.map((model) => model.id),
-    ),
+    parsedRegistry.flatMap((provider) => provider.models.map((model) => model.id)),
+  );
+  const registryAliases = new Set(
+    parsedRegistry.flatMap((provider) => provider.models.flatMap((model) => model.aliases ?? [])),
   );
   const isRegistryNamespaced = (id: string): boolean =>
-    id.startsWith(CODEX_MODEL_ID_PREFIX) || (id.includes("/") && registryOwnedIds.has(id));
+    id.startsWith(CODEX_MODEL_ID_PREFIX) ||
+    registryAliases.has(id) ||
+    (id.includes("/") && registryOwnedIds.has(id));
+  const builtinProvider = providerById.get(builtinId);
+  if (!builtinProvider) {
+    throw new Error(`Built-in model provider ${builtinId} is not configured`);
+  }
   const out: ConfiguredModel[] = uniqueValues([
     settings.openaiModel,
     ...splitCsv(settings.openaiAllowedModels),
   ])
     .filter((id) => !isRegistryNamespaced(id))
-    .map((id) => ({
-      id,
-      label: id,
-      providerId: builtinId,
-      providerLabel: builtinLabel,
-      api: "responses" as const,
-      contextWindowTokens: settings.contextWindowTokens,
-      reasoningEffort: true,
-      hostedWebSearch: settings.webSearchEnabled,
-    }));
-  for (const provider of parseModelProvidersJson(settings.modelProvidersJson)) {
+    .map((id) => {
+      const capabilities = legacyModelCapabilities(settings, {
+        reasoningEffort: true,
+        hostedWebSearch: settings.webSearchEnabled,
+      });
+      return finalizeConfiguredModel(settings, builtinProvider, {
+        id,
+        aliases: [],
+        label: id,
+        providerId: builtinId,
+        providerLabel: builtinLabel,
+        api: "responses" as const,
+        upstreamModelId: id,
+        deployment: { upstreamModelId: id, wireApi: "responses" },
+        credentialSource: builtinProvider.credentialSource,
+        billing: builtinProvider.billing,
+        capabilities,
+        ...(pricingSchedules[id] === undefined ? {} : { pricing: pricingSchedules[id] }),
+        contextWindowTokens: settings.contextWindowTokens,
+        toolOutputTruncationTokens: settings.modelToolOutputTruncationTokens,
+        reasoningEffort: capabilities.reasoning.runnable,
+        hostedWebSearch: capabilities.hostedTools.webSearch.runnable,
+      });
+    });
+  for (const provider of parsedRegistry) {
     const providerLabel = provider.label ?? provider.id;
+    const resolvedProvider = providerById.get(provider.id);
+    if (!resolvedProvider) {
+      throw new Error(`Registry model provider ${provider.id} is not configured`);
+    }
     for (const model of provider.models) {
-      out.push({
-        id: model.id,
-        label: model.label ?? model.id,
-        providerId: provider.id,
-        providerLabel,
-        api: provider.api,
-        ...(model.contextWindowTokens === undefined
-          ? {}
-          : { contextWindowTokens: model.contextWindowTokens }),
-        ...(model.effectiveContextWindowTokens === undefined
-          ? {}
-          : { effectiveContextWindowTokens: model.effectiveContextWindowTokens }),
-        ...(model.autoCompactTokenLimit === undefined
-          ? {}
-          : { autoCompactTokenLimit: model.autoCompactTokenLimit }),
-        reasoningEffort: model.reasoningEffort ?? false,
-        hostedWebSearch: model.hostedWebSearch ?? false,
-      });
+      const capabilities = model.capabilities
+        ? normalizeCapabilities(model.capabilities)
+        : legacyModelCapabilities(settings, {
+            reasoningEffort: model.reasoningEffort ?? false,
+            hostedWebSearch: model.hostedWebSearch ?? false,
+          });
+      const upstreamModelId = model.upstreamModelId ?? model.id;
+      out.push(
+        finalizeConfiguredModel(settings, resolvedProvider, {
+          id: model.id,
+          aliases: [...(model.aliases ?? [])],
+          label: model.label ?? model.id,
+          providerId: provider.id,
+          providerLabel,
+          api: provider.api,
+          upstreamModelId,
+          deployment: { upstreamModelId, wireApi: provider.api },
+          credentialSource: resolvedProvider.credentialSource,
+          billing: resolvedProvider.billing,
+          capabilities,
+          ...(pricingSchedules[model.id] === undefined
+            ? {}
+            : { pricing: pricingSchedules[model.id] }),
+          ...(model.contextWindowTokens === undefined
+            ? {}
+            : { contextWindowTokens: model.contextWindowTokens }),
+          ...(model.effectiveContextWindowTokens === undefined
+            ? {}
+            : { effectiveContextWindowTokens: model.effectiveContextWindowTokens }),
+          ...(model.autoCompactTokenLimit === undefined
+            ? {}
+            : { autoCompactTokenLimit: model.autoCompactTokenLimit }),
+          ...(model.toolOutputTruncationTokens === undefined
+            ? {}
+            : { toolOutputTruncationTokens: model.toolOutputTruncationTokens }),
+          reasoningEffort: capabilities.reasoning.runnable,
+          hostedWebSearch: capabilities.hostedTools.webSearch.runnable,
+        }),
+      );
     }
   }
-  const seen = new Set<string>();
-  return out.filter((model) => {
-    if (seen.has(model.id)) {
-      return false;
-    }
-    seen.add(model.id);
-    return true;
-  });
+  assertUniqueModelIdentities(out);
+  return out;
+}
+
+/** Resolve a known canonical id or alias. Unknown strings are returned unchanged. */
+export function canonicalizeConfiguredModelId(settings: Settings, modelId: string): string {
+  const models = configuredModels(settings);
+  const canonical = models.find((model) => model.id === modelId);
+  if (canonical) {
+    return canonical.id;
+  }
+  return models.find((model) => model.aliases.includes(modelId))?.id ?? modelId;
 }
 
 /**
@@ -1425,7 +2265,8 @@ export function resolveModelProvider(
   settings: Settings,
   modelId: string,
 ): { provider: ResolvedModelProvider; model: ConfiguredModel } | undefined {
-  const model = configuredModels(settings).find((candidate) => candidate.id === modelId);
+  const canonicalModelId = canonicalizeConfiguredModelId(settings, modelId);
+  const model = configuredModels(settings).find((candidate) => candidate.id === canonicalModelId);
   if (!model) {
     return undefined;
   }
@@ -1438,28 +2279,169 @@ export function resolveModelProvider(
   return { provider, model };
 }
 
+export type ResolveTurnExecutionPolicyV1Input = {
+  /** Effective persisted turn model. Aliases are accepted and canonicalized. */
+  modelId: string;
+  /** Exact caller-supplied input before canonicalization, only for explicit switches. */
+  requestedModelId: string | null;
+  modelSource: TurnExecutionModelSourceV1;
+  reasoningEffort: Settings["openaiReasoningEffort"];
+  reasoningSource: TurnExecutionReasoningSourceV1;
+};
+
+function settingsForTurnExecutionPolicy(settings: Settings, modelId: string): Settings {
+  return settings.codexSubscriptionEnabled && modelId.startsWith(CODEX_MODEL_ID_PREFIX)
+    ? withCodexCatalogProvider(settings)
+    : settings;
+}
+
 /**
- * Effective per-model pricing. Merge order (later wins):
- *   defaultModelPricing → registry model `pricing` entries (keyed by model id)
- *   → parseModelPricingJson(settings.modelPricingJson) (explicit JSON wins).
+ * Build a trusted, secret-safe execution policy from the normalized catalog.
+ * The Codex overlay here contains static product/provider identity only; it
+ * neither proves readiness nor chooses, decrypts, leases, or exposes an account.
  */
-export function configuredModelPricing(settings: Settings): Record<string, ModelPricing> {
-  const registry: Record<string, ModelPricing> = {};
+export function resolveTurnExecutionPolicyV1(
+  settings: Settings,
+  input: ResolveTurnExecutionPolicyV1Input,
+): TurnExecutionPolicyV1 {
+  const catalogSettings = settingsForTurnExecutionPolicy(settings, input.modelId);
+  const productModelId = canonicalizeConfiguredModelId(catalogSettings, input.modelId);
+  const resolved = resolveModelProvider(catalogSettings, productModelId);
+  if (!resolved) {
+    throw new Error("Turn execution policy model is not present in the configured catalog");
+  }
+  if (
+    input.requestedModelId !== null &&
+    canonicalizeConfiguredModelId(catalogSettings, input.requestedModelId) !== productModelId
+  ) {
+    throw new Error("Turn execution policy requested model does not canonicalize to its product");
+  }
+  return TurnExecutionPolicyV1.parse({
+    schemaVersion: 1,
+    productModelId,
+    requestedModelId: input.requestedModelId,
+    modelSource: input.modelSource,
+    reasoningEffort: input.reasoningEffort,
+    reasoningSource: input.reasoningSource,
+    providerId: resolved.provider.id,
+    upstreamModelId: resolved.model.upstreamModelId,
+    wireApi: resolved.model.api,
+    credentialSource: resolved.model.credentialSource,
+    billing: resolved.model.billing,
+    definitionVersion: resolved.model.definitionVersion,
+  });
+}
+
+/**
+ * Parse-time validation lives in @opengeni/contracts; this verifier binds a
+ * present snapshot to the current executable definition and exact turn row.
+ * Any deployment/provider drift fails before a provider or compaction call.
+ */
+export function assertTurnExecutionPolicyMatchesConfigV1(
+  settings: Settings,
+  policy: TurnExecutionPolicyV1,
+  expected: {
+    modelId: string;
+    reasoningEffort: Settings["openaiReasoningEffort"];
+  },
+): {
+  policy: TurnExecutionPolicyV1;
+  provider: ResolvedModelProvider;
+  model: ConfiguredModel;
+} {
+  const parsed = TurnExecutionPolicyV1.parse(policy);
+  const catalogSettings = settingsForTurnExecutionPolicy(settings, parsed.productModelId);
+  const canonicalExpectedModel = canonicalizeConfiguredModelId(catalogSettings, expected.modelId);
+  if (
+    parsed.productModelId !== canonicalExpectedModel ||
+    parsed.reasoningEffort !== expected.reasoningEffort
+  ) {
+    throw new Error("Turn execution policy does not match the accepted turn model/reasoning");
+  }
+  if (
+    parsed.requestedModelId !== null &&
+    canonicalizeConfiguredModelId(catalogSettings, parsed.requestedModelId) !==
+      parsed.productModelId
+  ) {
+    throw new Error("Turn execution policy requested model does not match its product model");
+  }
+  const resolved = resolveModelProvider(catalogSettings, parsed.productModelId);
+  if (!resolved) {
+    throw new Error("Turn execution policy model is no longer configured");
+  }
+  const mismatched =
+    parsed.providerId !== resolved.provider.id ||
+    parsed.upstreamModelId !== resolved.model.upstreamModelId ||
+    parsed.wireApi !== resolved.model.api ||
+    parsed.definitionVersion !== resolved.model.definitionVersion ||
+    canonicalJson(parsed.credentialSource) !== canonicalJson(resolved.model.credentialSource) ||
+    canonicalJson(parsed.billing) !== canonicalJson(resolved.model.billing);
+  if (mismatched) {
+    throw new Error("Turn execution policy does not match the current provider definition");
+  }
+  return { policy: parsed, provider: resolved.provider, model: resolved.model };
+}
+
+/**
+ * Effective per-model pricing schedules. Merge order (later wins): built-in
+ * flat defaults → registry model flat/scheduled pricing → explicit legacy flat
+ * OPENGENI_MODEL_PRICING_JSON. The explicit legacy map intentionally replaces
+ * a registry schedule with one flat default so its historical precedence stays
+ * exact.
+ */
+export function configuredModelPricingSchedules(
+  settings: Settings,
+): Record<string, ModelPricingScheduleV1> {
+  const defaults = Object.fromEntries(
+    Object.entries(defaultModelPricing).map(([model, pricing]) => [model, { default: pricing }]),
+  );
+  const registry: Record<string, ModelPricingScheduleV1> = {};
   for (const provider of parseModelProvidersJson(settings.modelProvidersJson)) {
     for (const model of provider.models) {
       if (model.pricing) {
-        registry[model.id] = model.pricing;
+        registry[model.id] = normalizeModelPricingSchedule(model.pricing);
       }
     }
   }
-  const configured = parseModelPricingJson(settings.modelPricingJson);
+  const configured = Object.fromEntries(
+    Object.entries(parseModelPricingJson(settings.modelPricingJson)).map(([model, pricing]) => [
+      model,
+      { default: pricing },
+    ]),
+  );
   return {
-    ...defaultModelPricing,
+    ...defaults,
     ...registry,
     ...configured,
   };
 }
 
+/** Legacy flat projection: returns the default/below-threshold price. */
+export function configuredModelPricing(settings: Settings): Record<string, ModelPricing> {
+  return Object.fromEntries(
+    Object.entries(configuredModelPricingSchedules(settings)).map(([model, schedule]) => [
+      model,
+      schedule.default,
+    ]),
+  );
+}
+
+/** Select the per-provider-request price at an exact input-token threshold. */
+export function selectModelPricing(
+  schedule: ModelPricingScheduleV1,
+  inputTokens: number,
+): ModelPricing {
+  const normalizedInputTokens = Math.max(0, Math.floor(inputTokens));
+  let selected = schedule.default;
+  for (const tier of schedule.inputTokenTiers ?? []) {
+    if (normalizedInputTokens < tier.minimumInputTokens) {
+      break;
+    }
+    selected = tier.pricing;
+  }
+  return selected;
+}
+
 /**
  * Usable input-token budget: an explicit model-catalog effective window when
  * available, otherwise the deployment window minus its output reserve.
@@ -1485,7 +2467,10 @@ export function settingsWithResolvedModelContext(
   settings: Settings,
   model: Pick<
     ConfiguredModel,
-    "contextWindowTokens" | "effectiveContextWindowTokens" | "autoCompactTokenLimit"
+    | "contextWindowTokens"
+    | "effectiveContextWindowTokens"
+    | "autoCompactTokenLimit"
+    | "toolOutputTruncationTokens"
   >,
 ): Settings {
   const contextWindowTokens = model.contextWindowTokens ?? settings.contextWindowTokens;
@@ -1503,6 +2488,9 @@ export function settingsWithResolvedModelContext(
     ...(model.autoCompactTokenLimit === undefined
       ? {}
       : { contextAutoCompactThresholdTokens: model.autoCompactTokenLimit }),
+    ...(model.toolOutputTruncationTokens === undefined
+      ? {}
+      : { modelToolOutputTruncationTokens: model.toolOutputTruncationTokens }),
   };
 }
 
@@ -1533,17 +2521,28 @@ export function calculateModelUsageCostMicros(
   model: string,
   usage: ModelUsageInput,
 ): number {
-  const pricing = configuredModelPricing(settings)[model];
-  if (!pricing) {
+  const schedule = configuredModelPricingSchedules(settings)[model];
+  if (!schedule) {
     throw new Error(`Missing model pricing for ${model}`);
   }
   const entries =
     usage.requestUsageEntries && usage.requestUsageEntries.length > 0
       ? usage.requestUsageEntries
       : [usage];
-  const rawCost = entries.reduce((sum, entry) => sum + calculateEntryCostMicros(pricing, entry), 0);
-  const marginBps = pricing.marginBps ?? 0;
-  return Math.ceil((rawCost * (10_000 + marginBps)) / 10_000);
+  const rawCostByPricing = new Map<ModelPricing, number>();
+  for (const entry of entries) {
+    const pricing = selectModelPricing(schedule, positiveInt(entry.inputTokens));
+    rawCostByPricing.set(
+      pricing,
+      (rawCostByPricing.get(pricing) ?? 0) + calculateEntryCostMicros(pricing, entry),
+    );
+  }
+  let total = 0;
+  for (const [pricing, rawCost] of rawCostByPricing) {
+    const marginBps = pricing.marginBps ?? 0;
+    total += Math.ceil((rawCost * (10_000 + marginBps)) / 10_000);
+  }
+  return total;
 }
 
 export function configuredAllowedReasoningEfforts(
@@ -1573,6 +2572,77 @@ export function environmentsEncryptionKeyBytes(settings: Settings): Uint8Array |
   return new Uint8Array(decoded);
 }
 
+/**
+ * Build one structurally compatible connection policy for both
+ * `@temporalio/client` and `@temporalio/worker`. An API key or any custom TLS
+ * material enables TLS automatically; the explicit flag covers server-auth TLS
+ * without credentials. Secret values are never included in validation errors.
+ */
+export function temporalConnectionOptions(settings: Settings): TemporalConnectionOptions {
+  const apiKey = settings.temporalApiKey?.trim() || undefined;
+  const serverNameOverride = settings.temporalTlsServerName?.trim() || undefined;
+  const rootCa = decodeTemporalTlsMaterial(
+    settings.temporalTlsRootCaCertificateBase64,
+    "OPENGENI_TEMPORAL_TLS_ROOT_CA_CERTIFICATE_BASE64",
+  );
+  const clientCertificate = decodeTemporalTlsMaterial(
+    settings.temporalTlsClientCertificateBase64,
+    "OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64",
+  );
+  const clientPrivateKey = decodeTemporalTlsMaterial(
+    settings.temporalTlsClientPrivateKeyBase64,
+    "OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64",
+  );
+
+  if (Boolean(clientCertificate) !== Boolean(clientPrivateKey)) {
+    throw new Error(
+      "OPENGENI_TEMPORAL_TLS_CLIENT_CERTIFICATE_BASE64 and " +
+        "OPENGENI_TEMPORAL_TLS_CLIENT_PRIVATE_KEY_BASE64 must both be set or both omitted",
+    );
+  }
+
+  const tls: TemporalTlsConnectionConfig = {};
+  if (serverNameOverride) {
+    tls.serverNameOverride = serverNameOverride;
+  }
+  if (rootCa) {
+    tls.serverRootCACertificate = rootCa;
+  }
+  if (clientCertificate && clientPrivateKey) {
+    tls.clientCertPair = { crt: clientCertificate, key: clientPrivateKey };
+  }
+  const hasCustomTls = Object.keys(tls).length > 0;
+  const tlsEnabled = settings.temporalTlsEnabled || Boolean(apiKey) || hasCustomTls;
+
+  return {
+    address: settings.temporalHost,
+    ...(tlsEnabled ? { tls: hasCustomTls ? tls : true } : {}),
+    ...(apiKey ? { apiKey } : {}),
+  };
+}
+
+function decodeTemporalTlsMaterial(
+  value: string | undefined,
+  settingName: string,
+): Uint8Array | undefined {
+  // RFC 2045 base64 commonly arrives wrapped at 76 columns. Kubernetes
+  // stringData and external secret stores preserve those line breaks, so
+  // normalize whitespace before applying the strict alphabet/canonical check.
+  const encoded = value?.replace(/\s/g, "");
+  if (!encoded) {
+    return undefined;
+  }
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1) {
+    throw new Error(`${settingName} must contain valid base64`);
+  }
+  const decoded = Buffer.from(encoded, "base64");
+  const canonical = decoded.toString("base64").replace(/=+$/, "");
+  if (decoded.length === 0 || canonical !== encoded.replace(/=+$/, "")) {
+    throw new Error(`${settingName} must contain valid base64`);
+  }
+  return new Uint8Array(decoded);
+}
+
 /**
  * The connection `search_path` for OpenGeni's db handles + the managed-auth pool
  * (Step I, §7.8 runtime half). Returns `undefined` when `dbSchema` is unset
@@ -1580,7 +2650,7 @@ export function environmentsEncryptionKeyBytes(settings: Settings): Uint8Array |
  * default (`public`) applies — byte-for-byte today's behavior. When `dbSchema`
  * is set (embedded), returns `"<schema>,opengeni_private,public"` — `public`
  * stays LAST so `gen_random_uuid()` (pgcrypto) and the `vector` type still
- * resolve (the SPIKE-1 live footgun). `opengeni_private` is on the path so the
+ * resolve (the schema-isolation contract live footgun). `opengeni_private` is on the path so the
  * RLS GUC-reader helpers resolve when referenced unqualified.
  */
 export function dbSearchPath(settings: Pick<Settings, "dbSchema">): string | undefined {
@@ -1683,6 +2753,9 @@ export function stableSandboxEnvironmentForRun(
   }
   if (settings.toolspaceEnabled) {
     environment.OPENGENI_TOOLSPACE_TOKEN_FILE ??= `${environment.HOME ?? descriptor.workspaceRoot}/.opengeni/toolspace-token`;
+    if (settings.ogtoolPackageSpec) {
+      environment.OPENGENI_OGTOOL_PACKAGE_SPEC ??= settings.ogtoolPackageSpec;
+    }
     if (options.workspaceId) {
       environment.OPENGENI_TOOLSPACE_URL ??= firstPartyMcpWorkspaceUrl(
         settings,
@@ -1983,7 +3056,14 @@ export function parseModelProvidersJson(raw: string): RegistryProvider[] {
         `OPENGENI_MODEL_PROVIDERS_JSON provider[${index}] is invalid: ${result.error.message}`,
       );
     }
-    return result.data;
+    try {
+      return normalizeRegistryProvider(result.data);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`OPENGENI_MODEL_PROVIDERS_JSON provider[${index}] is invalid: ${message}`, {
+        cause: error,
+      });
+    }
   });
 }
 
@@ -2196,6 +3276,7 @@ function firstPartyDocumentsMcpServerUrl(mcpUrl: string): string {
 }
 
 function validateSettings(settings: Settings): void {
+  temporalConnectionOptions(settings);
   if (settings.toolspaceEnabled && !settings.delegationSecret) {
     throw new Error("OPENGENI_DELEGATION_SECRET is required when OPENGENI_TOOLSPACE_ENABLED=true");
   }
@@ -2507,7 +3588,7 @@ function validateSettings(settings: Settings): void {
       );
     }
   }
-  // --- stream-token secret: required-when-desktop, but GRACEFULLY DEGRADE (I8) ---
+  // --- stream-token secret: required-when-desktop, but GRACEFULLY DEGRADE (stream-token availability contract) ---
   // The desktop pixel plane needs an HMAC secret to mint scoped stream tokens.
   // It is REQUIRED when desktop is enabled — but per OD-8 a missing secret is NOT
   // a hard boot-fail: we emit a LOUD warning and the deployment ships with
@@ -2551,10 +3632,14 @@ function validateSettings(settings: Settings): void {
       );
     }
   }
+  // Materialize the normalized catalog at boot so canonical product ids,
+  // aliases, definition digests, and capability/pricing normalization are
+  // validated even when managed billing is disabled.
+  configuredModels(settings);
 }
 
 /**
- * Resolve the secret used to sign/verify scoped stream tokens (master-spine
+ * Resolve the secret used to sign/verify scoped stream tokens (sandbox contract
  * §C.3). Falls back to `delegationSecret` (the same HMAC envelope family —
  * `ogs_` vs `ogd_` prefix) so a deployment that already carries a delegation
  * secret does not need a second one. Returns undefined when neither is set,
@@ -2571,7 +3656,7 @@ export function resolveStreamTokenSecret(settings: Settings): string | undefined
 
 /**
  * True iff the desktop pixel plane must GRACEFULLY DEGRADE because desktop is
- * enabled but no stream-token secret is resolvable (I8/OD-8). When true,
+ * enabled but no stream-token secret is resolvable (stream-token availability contract). When true,
  * negotiateCapabilities forces DesktopStream.transport:null.
  */
 export function streamTokenDegraded(settings: Settings): boolean {
@@ -2580,7 +3665,7 @@ export function streamTokenDegraded(settings: Settings): boolean {
 
 /**
  * Resolve the secret the control plane signs the enrollment bearer credential
- * with (the `oge_` envelope the agent presents back — M5/dossier §10.2). Falls
+ * with (the `oge_` envelope the agent presents back — M5). Falls
  * back to `delegationSecret` (the same HMAC envelope family) so a deployment that
  * already carries a delegation secret needs no second one. Returns undefined when
  * neither is set; when selfhosted is enabled but this is undefined, the poll route
@@ -2598,7 +3683,7 @@ export function resolveEnrollmentSigningSecret(settings: Settings): string | und
 
 /**
  * Resolve the HMAC secret the control plane signs the agent's relay PRODUCER token
- * with (the `ogr_` envelope; M8b/dossier §10.5). The RELAY verifies the producer
+ * with (the `ogr_` envelope; M8b). The RELAY verifies the producer
  * token with the SAME secret (injected into the relay via env). Prefers an explicit
  * `selfhostedRelayTokenSecret`, then the `streamTokenSecret` (the relay already
  * needs that one to verify the viewer's `ogs_` token, so a single secret can back