@opengeni/contracts 0.44.1 → 1.0.0

package/src/client-error-report.ts

@@ -0,0 +1,184 @@
+/**
+ * Wire grammar of the content-free web client error beacon
+ * (`POST /v1/client-errors`).
+ *
+ * A report is only a closed error kind, the matched route PATTERN (never a
+ * concrete URL), and the bundle revision. The web client that projects a
+ * report, the API route that admits it, and the public structured-log
+ * projection that prints it all validate against these exact values, so the
+ * browser can only send what the API accepts and logs.
+ *
+ * The same route also admits the closed operational signals below (requests
+ * that never reached the server, live-stream health, and web vitals). They
+ * follow the same rules: closed values only, a route pattern or page label,
+ * never a URL, message, identifier, or user content.
+ */
+export const CLIENT_ERRORS_PATH = "/v1/client-errors";
+
+export const CLIENT_ERROR_KINDS = [
+  "route_error",
+  "unhandled_rejection",
+  "window_error",
+  "chunk_load",
+] as const;
+export type ClientErrorKind = (typeof CLIENT_ERROR_KINDS)[number];
+
+/** Largest accepted report body. A valid report is well under 256 bytes. */
+export const CLIENT_ERROR_REPORT_MAX_BYTES = 512;
+
+const ROUTE_SEGMENT = String.raw`(?:[a-z]+(?:-[a-z]+)*|\$[A-Za-z][A-Za-z0-9]{0,31})`;
+
+/**
+ * A route pattern of at most 160 characters that is `/`, `unknown`, or up to
+ * twelve `/`-separated segments that are each either a lowercase literal
+ * (`variable-sets`) or a `$param` placeholder. The grammar excludes digits in
+ * literals, so a concrete id cannot pass as one.
+ */
+export const CLIENT_ERROR_ROUTE_PATTERN = new RegExp(
+  String.raw`^(?=.{1,160}$)(?:unknown|/|(?:/${ROUTE_SEGMENT}){1,12})$`,
+);
+
+/** The bundle revision token (a commit SHA, `dev`, or `unknown`). */
+export const CLIENT_ERROR_REVISION_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+export type ClientErrorReport = { kind: ClientErrorKind; route: string; revision: string };
+
+/**
+ * Content-free operational signals that share the error beacon route. A
+ * signal report carries a `signal` discriminator and only closed values; a
+ * report without `signal` is a {@link ClientErrorReport}. Older API servers
+ * reject signal reports as invalid, so the extension is backward compatible in
+ * both directions.
+ */
+export const CLIENT_SIGNALS = ["request_failure", "stream", "web_vital"] as const;
+export type ClientSignal = (typeof CLIENT_SIGNALS)[number];
+
+/**
+ * Key product mutations whose failure before any HTTP response is counted.
+ * `send_message` includes sends the server queues behind an active turn.
+ */
+export const CLIENT_REQUEST_ACTIONS = [
+  "create_session",
+  "send_message",
+  "steer_message",
+  "composer_submit",
+  "retry_turn",
+  "connect_integration",
+  "connect_model",
+  "checkout_start",
+] as const;
+export type ClientRequestAction = (typeof CLIENT_REQUEST_ACTIONS)[number];
+
+/**
+ * Why a request never produced an HTTP response: the browser reported no
+ * connectivity (`offline`), the client's own deadline expired (`timeout`), or
+ * the transport failed (`network`). Cancellations the user or the app
+ * initiated are never reported.
+ */
+export const CLIENT_REQUEST_FAILURE_REASONS = ["network", "timeout", "offline"] as const;
+export type ClientRequestFailureReason = (typeof CLIENT_REQUEST_FAILURE_REASONS)[number];
+
+/** Browser live streams: one session's event stream, or the workspace live stream. */
+export const CLIENT_STREAMS = ["session", "workspace"] as const;
+export type ClientStream = (typeof CLIENT_STREAMS)[number];
+
+/**
+ * Live stream health: a live stream dropped and started reconnecting
+ * (`reconnect`), stopped reconnecting (`reconnect_exhausted`), or stayed
+ * disconnected for longer than the long-disconnect threshold while the tab
+ * was visible (`long_disconnect`).
+ */
+export const CLIENT_STREAM_EVENTS = [
+  "reconnect",
+  "reconnect_exhausted",
+  "long_disconnect",
+] as const;
+export type ClientStreamEvent = (typeof CLIENT_STREAM_EVENTS)[number];
+
+/** Core Web Vitals plus time to first byte, measured once per document. */
+export const CLIENT_WEB_VITAL_METRICS = ["lcp", "inp", "cls", "ttfb"] as const;
+export type ClientWebVitalMetric = (typeof CLIENT_WEB_VITAL_METRICS)[number];
+
+/**
+ * Largest accepted value: seconds for the timing metrics, the unitless layout
+ * shift score for `cls`.
+ */
+export const CLIENT_WEB_VITAL_MAX_VALUE: Readonly<Record<ClientWebVitalMetric, number>> = {
+  lcp: 600,
+  inp: 600,
+  cls: 100,
+  ttfb: 600,
+};
+
+/**
+ * The closed page labels of the web console's product-journey projection
+ * (`journeyPage` in apps/web/src/lib/analytics-journey.ts; a drift test keeps
+ * the two identical). Workspace pages are the first path segment after
+ * `/workspaces/<id>/`; the rest are exact top-level routes.
+ */
+export const CLIENT_PAGES = [
+  "sessions",
+  "priority",
+  "plugins",
+  "capabilities",
+  "documents",
+  "state",
+  "memory",
+  "schedules",
+  "artifacts",
+  "settings",
+  "organization",
+  "insights",
+  "machines",
+  "files",
+  "agents",
+  "variable-sets",
+  "environments",
+  "rigs",
+  "home",
+  "session-link",
+  "identity-link",
+  "checkout-return",
+  "integration-return",
+  "device",
+  "connect-agent",
+  "reset-password",
+  "setup-account",
+  "account-auth",
+  "personal-security",
+  "other",
+] as const;
+export type ClientPage = (typeof CLIENT_PAGES)[number];
+
+export type ClientRequestFailureReport = {
+  signal: "request_failure";
+  action: ClientRequestAction;
+  reason: ClientRequestFailureReason;
+  route: string;
+  revision: string;
+};
+
+export type ClientStreamReport = {
+  signal: "stream";
+  stream: ClientStream;
+  event: ClientStreamEvent;
+  route: string;
+  revision: string;
+};
+
+export type ClientWebVitalReport = {
+  signal: "web_vital";
+  metric: ClientWebVitalMetric;
+  page: ClientPage;
+  /** Seconds for timing metrics, the unitless score for `cls`. */
+  value: number;
+  revision: string;
+};
+
+export type ClientSignalReport =
+  | ClientRequestFailureReport
+  | ClientStreamReport
+  | ClientWebVitalReport;
+
+/** Every body the beacon route accepts. */
+export type ClientBeaconReport = ClientErrorReport | ClientSignalReport;

package/src/code-search.ts

@@ -0,0 +1,105 @@
+// Resolvers for the optional Jev-backed `code_search` agent tool. A separate
+// subpath keeps them out of browser bundles; only server code decides.
+
+/**
+ * Directories holding platform credential material that `code_search` never
+ * searches or reads, as path segments matched at any depth: OpenGeni's
+ * sandbox state (`.opengeni/`: Codemode bearer tokens, Git credential files
+ * and bindings), the Azure CLI login cache (`.azure/`, from the sandbox's
+ * service-principal login with HOME=/workspace) and a Connected Machine
+ * agent's enrollment credentials (`.config/opengeni/`). The sandbox channel
+ * enforces this list; `@opengeni/jev` keeps the same list for its engine, and
+ * a worker test pins that the two agree.
+ */
+export const CODE_SEARCH_CREDENTIAL_DIRS: readonly (readonly string[])[] = [
+  [".opengeni"],
+  [".azure"],
+  [".config", "opengeni"],
+];
+
+/**
+ * The deployment half of the `code_search` decision. `split` gives the tool to
+ * a fixed half of sessions (see `codeSearchSessionInExperiment`) so staging can
+ * compare sessions with and without it.
+ */
+export type CodeSearchWorkspaceDefault = "off" | "on" | "split";
+export type CodeSearchDeploymentPolicy = {
+  available: boolean;
+  workspaceDefault: CodeSearchWorkspaceDefault;
+};
+
+/**
+ * What a workspace gets: the deployment decides first, so nothing enables the
+ * tool where the deployment does not offer it. Otherwise an explicit workspace
+ * choice wins, and an absent, null or malformed setting follows the deployment
+ * default. Only this field is read, so an invalid sibling setting cannot turn
+ * an explicit Off back into the deployment default.
+ */
+export function resolveWorkspaceCodeSearchMode(
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+): CodeSearchWorkspaceDefault {
+  if (!deployment.available) return "off";
+  const explicit = explicitWorkspaceCodeSearchSetting(settings);
+  if (explicit === true) return "on";
+  if (explicit === false) return "off";
+  return deployment.workspaceDefault;
+}
+
+function explicitWorkspaceCodeSearchSetting(settings: unknown): boolean | undefined {
+  const explicit =
+    typeof settings === "object" && settings !== null
+      ? (settings as { codeSearchEnabled?: unknown }).codeSearchEnabled
+      : undefined;
+  return typeof explicit === "boolean" ? explicit : undefined;
+}
+
+/**
+ * Fixed per-session half for the `split` experiment: 32-bit FNV-1a of the
+ * session id, low bit 0 gets the tool. Deterministic and dependency-free, so
+ * a root session's arm can be recomputed from its id. Child sessions inherit
+ * their parent's decision instead.
+ */
+export function codeSearchSessionInExperiment(sessionId: string): boolean {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < sessionId.length; index++) {
+    hash ^= sessionId.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return (hash & 1) === 0;
+}
+
+/**
+ * The decision frozen on a new root session when it is created. Later changes
+ * to the workspace setting or the deployment mode never turn the tool on for a
+ * session that was created without it.
+ */
+export function resolveSessionCodeSearchEnabled(
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+  sessionId: string,
+): boolean {
+  const mode = resolveWorkspaceCodeSearchMode(settings, deployment);
+  return mode === "on" || (mode === "split" && codeSearchSessionInExperiment(sessionId));
+}
+
+/**
+ * Whether a turn of this session gets `code_search`. Only a session frozen on
+ * at creation can have it. The deployment (mode off or no usable key) and an
+ * explicit workspace Off still pause it in running sessions, because they stop
+ * repository content going to Jev; undoing that switch-off gives it back to
+ * sessions frozen on. Each such change costs every affected session one
+ * prompt-cache miss, which is accepted for a deliberate switch. Nothing else
+ * changes the tool list of a running session.
+ */
+export function codeSearchEnabledForTurn(
+  frozen: boolean | null | undefined,
+  settings: unknown,
+  deployment: CodeSearchDeploymentPolicy,
+): boolean {
+  return (
+    frozen === true &&
+    deployment.available &&
+    explicitWorkspaceCodeSearchSetting(settings) !== false
+  );
+}

package/src/codex-provider-account-authority.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+const PositiveSafeInteger = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+
+/**
+ * Opaque authority frozen at a Codex provider-account acceptance boundary.
+ *
+ * The snapshot deliberately carries no organization, membership, credential,
+ * provider-account, subject, label, quota, token, or plan identity. A later
+ * activation slice may use the user generation only together with separately
+ * authorized durable state; this value is never sufficient authority alone.
+ */
+export const CodexProviderAccountAuthoritySnapshotV1 = z.discriminatedUnion("scope", [
+  z
+    .object({
+      version: z.literal(1),
+      scope: z.literal("workspace"),
+    })
+    .strict(),
+  z
+    .object({
+      version: z.literal(1),
+      scope: z.literal("user"),
+      authorityGeneration: PositiveSafeInteger,
+    })
+    .strict(),
+]);
+
+export type CodexProviderAccountAuthoritySnapshotV1 = z.infer<
+  typeof CodexProviderAccountAuthoritySnapshotV1
+>;
+
+/** Explicit compatibility value for all pre-foundation accepted work. */
+export const LEGACY_WORKSPACE_CODEX_PROVIDER_ACCOUNT_AUTHORITY_SNAPSHOT_V1 = {
+  version: 1,
+  scope: "workspace",
+} as const satisfies CodexProviderAccountAuthoritySnapshotV1;

package/src/company-brain-governed-writes.ts

@@ -0,0 +1,356 @@
+import { z } from "zod";
+import {
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import {
+  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
+  PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS,
+  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
+  PreferenceRegistryConflictStrategy,
+  PreferenceRegistryStableKey,
+} from "./preference-registry";
+import { GovernedLearningActivationDestination } from "./governed-learning-activation";
+import {
+  GovernedLearningDecisionOutcome,
+  GovernedLearningDecisionReason,
+} from "./governed-learning-evaluator";
+import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-policies";
+import { WorkspaceLearningPolicyEffectiveMode } from "./workspace-learning-policy";
+
+const boundedReason = z.string().trim().min(1).max(4_096);
+const operationId = z.string().uuid();
+const exactEvidence = {
+  claimId: z.string().uuid(),
+  evidenceId: z.string().uuid(),
+};
+
+/** Exact accepted-attempt authority. It is validated again inside the write transaction. */
+export const CompanyBrainGovernedWriteAttempt = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+  })
+  .strict();
+export type CompanyBrainGovernedWriteAttempt = z.infer<typeof CompanyBrainGovernedWriteAttempt>;
+
+export const ProposeWorkspaceKnowledgeClaimRequest = z
+  .object({
+    kind: z.literal("propose_knowledge"),
+    operationId,
+    ...exactEvidence,
+    reason: boundedReason,
+  })
+  .strict();
+export type ProposeWorkspaceKnowledgeClaimRequest = z.infer<
+  typeof ProposeWorkspaceKnowledgeClaimRequest
+>;
+
+export const CorrectWorkspaceKnowledgeClaimRequest = z
+  .object({
+    kind: z.literal("correct_knowledge"),
+    operationId,
+    ...exactEvidence,
+    replacesClaimId: z.string().uuid(),
+    reason: boundedReason,
+  })
+  .strict();
+export type CorrectWorkspaceKnowledgeClaimRequest = z.infer<
+  typeof CorrectWorkspaceKnowledgeClaimRequest
+>;
+
+/**
+ * Promote one still-active task-tree note into a normalized, workspace-local
+ * Knowledge claim proposal. The note text is the exact fact value and source
+ * evidence; callers may describe the subject and predicate but cannot widen
+ * authority or supply replacement source bytes.
+ */
+export const PromoteTaskNoteKnowledgeRequest = z
+  .object({
+    kind: z.literal("promote_task_note_knowledge"),
+    operationId,
+    noteId: z.string().uuid(),
+    expectedNoteVersion: z.literal(1),
+    entityType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(96)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    normalizedKey: z.string().trim().min(1).max(512),
+    displayName: z.string().trim().min(1).max(512),
+    predicateKey: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    confidenceBps: z.number().int().min(0).max(10_000),
+    reason: boundedReason,
+  })
+  .strict();
+export type PromoteTaskNoteKnowledgeRequest = z.infer<typeof PromoteTaskNoteKnowledgeRequest>;
+
+/**
+ * Promote the exact immutable Task-note bytes into an inactive mandatory-rule
+ * draft. The caller selects only the governed target and active-head baseline;
+ * it cannot replace the source content or activate the draft.
+ */
+export const PromoteTaskNoteInstructionPolicyRequest = z
+  .strictObject({
+    kind: z.literal("promote_task_note_instruction_policy"),
+    operationId,
+    noteId: z.string().uuid(),
+    expectedNoteVersion: z.literal(1),
+    entityType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(96)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    normalizedKey: z.string().trim().min(1).max(512),
+    displayName: z.string().trim().min(1).max(512),
+    predicateKey: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    confidenceBps: z.number().int().min(0).max(10_000),
+    target: WorkspaceInstructionPolicyTarget,
+    expectedCurrentRevisionId: z.string().uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+    reason: boundedReason,
+  })
+  .superRefine((value, context) => {
+    const target = WorkspaceInstructionPolicyTarget.safeParse(value.target);
+    if (!target.success) {
+      for (const issue of target.error.issues) {
+        context.addIssue({ ...issue, path: ["target", ...issue.path] });
+      }
+    }
+  });
+export type PromoteTaskNoteInstructionPolicyRequest = z.infer<
+  typeof PromoteTaskNoteInstructionPolicyRequest
+>;
+
+/**
+ * Promote the exact immutable Task-note bytes into an inactive workspace
+ * preference proposal. Descriptor metadata is caller-supplied and bounded,
+ * while the full proposal content always comes from the admitted note.
+ */
+export const PromoteTaskNotePreferenceRequest = z.strictObject({
+  kind: z.literal("promote_task_note_preference"),
+  operationId,
+  noteId: z.string().uuid(),
+  expectedNoteVersion: z.literal(1),
+  entityType: z
+    .string()
+    .trim()
+    .min(1)
+    .max(96)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  normalizedKey: z.string().trim().min(1).max(512),
+  displayName: z.string().trim().min(1).max(512),
+  predicateKey: z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  confidenceBps: z.number().int().min(0).max(10_000),
+  stableKey: PreferenceRegistryStableKey.max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+  title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+  description: z.string().trim().min(1).max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+  precedenceRank: z.number().int().min(-1_000).max(1_000).default(0),
+  conflictStrategy: PreferenceRegistryConflictStrategy.default("override"),
+  conflictsWith: z.array(PreferenceRegistryStableKey).max(32).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().default(null),
+  reason: boundedReason,
+});
+export type PromoteTaskNotePreferenceRequest = z.infer<typeof PromoteTaskNotePreferenceRequest>;
+
+export const ProposeWorkspaceInstructionPolicyRequest = z
+  .strictObject({
+    kind: z.literal("propose_instruction_policy"),
+    operationId,
+    ...exactEvidence,
+    target: WorkspaceInstructionPolicyTarget,
+    // Instruction drafts use the same storage bound as the human editor.
+    // Prompt composition retains its separate byte limit after activation.
+    content: z
+      .string()
+      .min(1)
+      .max(
+        AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+        AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+      )
+      .refine((value) => value.trim().length > 0, "instruction proposal must not be blank"),
+    expectedCurrentRevisionId: z.string().uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+    reason: boundedReason,
+  })
+  .superRefine((value, context) => {
+    const target = WorkspaceInstructionPolicyTarget.safeParse(value.target);
+    if (!target.success) {
+      for (const issue of target.error.issues) {
+        context.addIssue({ ...issue, path: ["target", ...issue.path] });
+      }
+    }
+  });
+export type ProposeWorkspaceInstructionPolicyRequest = z.infer<
+  typeof ProposeWorkspaceInstructionPolicyRequest
+>;
+
+export const ProposeWorkspacePreferenceRequest = z.strictObject({
+  kind: z.literal("propose_preference"),
+  operationId,
+  ...exactEvidence,
+  stableKey: PreferenceRegistryStableKey.max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+  title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+  description: z.string().trim().min(1).max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+  // Agent-authored: the descriptor pair is prompt-composed in every session and
+  // the content is retrieved on demand, so it stays short.
+  content: z
+    .string()
+    .min(1)
+    .max(
+      AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+      AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+    )
+    .refine((value) => value.trim().length > 0, "preference proposal must not be blank"),
+  precedenceRank: z.number().int().min(-1_000).max(1_000).default(0),
+  conflictStrategy: PreferenceRegistryConflictStrategy.default("override"),
+  conflictsWith: z.array(PreferenceRegistryStableKey).max(32).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().default(null),
+  reason: boundedReason,
+});
+export type ProposeWorkspacePreferenceRequest = z.infer<typeof ProposeWorkspacePreferenceRequest>;
+
+/**
+ * Destination selection is explicit and structured. There is deliberately no
+ * generic "remember" operation, classifier, personal scope, or active authority.
+ */
+export const CompanyBrainGovernedWriteRequest = z.discriminatedUnion("kind", [
+  ProposeWorkspaceKnowledgeClaimRequest,
+  CorrectWorkspaceKnowledgeClaimRequest,
+  PromoteTaskNoteKnowledgeRequest,
+  PromoteTaskNoteInstructionPolicyRequest,
+  PromoteTaskNotePreferenceRequest,
+  ProposeWorkspaceInstructionPolicyRequest,
+  ProposeWorkspacePreferenceRequest,
+]);
+export type CompanyBrainGovernedWriteRequest = z.infer<typeof CompanyBrainGovernedWriteRequest>;
+
+export const CompanyBrainGovernedWriteDestination = z.enum([
+  "knowledge",
+  "instruction_policy",
+  "preference",
+]);
+export type CompanyBrainGovernedWriteDestination = z.infer<
+  typeof CompanyBrainGovernedWriteDestination
+>;
+
+export const CompanyBrainGovernedWriteReceipt = z.object({
+  operationId,
+  inputHash: z.string().regex(/^[0-9a-f]{64}$/),
+  workspaceId: z.string().uuid(),
+  destination: CompanyBrainGovernedWriteDestination,
+  outcome: z.literal("proposed"),
+  claimId: z.string().uuid(),
+  evidenceId: z.string().uuid(),
+  relationId: z.string().uuid().nullable(),
+  reviewId: z.string().uuid().nullable(),
+  knowledgeChangeProposalId: z.string().uuid().nullable(),
+  destinationProposalId: z.string().uuid().nullable(),
+  destinationRevisionId: z.string().uuid().nullable(),
+  taskNoteSource: z
+    .object({
+      noteId: z.string().uuid(),
+      rootSessionId: z.string().uuid(),
+      noteVersion: z.literal(1),
+      textHash: z.string().regex(/^[0-9a-f]{64}$/),
+    })
+    .nullable()
+    .optional(),
+  effectiveBoundary: z.literal("human_review_required"),
+  rollback: z.object({
+    supported: z.literal(false),
+    mechanism: z.literal("not_applicable_proposal_only"),
+  }),
+});
+export type CompanyBrainGovernedWriteReceipt = z.infer<typeof CompanyBrainGovernedWriteReceipt>;
+
+/**
+ * Policy routing is deliberately separate from destination admission. The
+ * immutable accepted-attempt snapshot decides whether derived evidence may
+ * create a proposal; the destination still owns activation and rollback.
+ */
+export const CompanyBrainLearningPolicyDecision = z.enum([
+  "blocked",
+  "proposal_created",
+  "activation_requested",
+  "activated",
+]);
+export type CompanyBrainLearningPolicyDecision = z.infer<typeof CompanyBrainLearningPolicyDecision>;
+
+/**
+ * Content-free summary of the governed-learning decision receipt recorded for
+ * a Ways-of-working proposal (instruction policy or preference). Knowledge
+ * destinations create no `knowledge_change_proposals` row and are therefore
+ * never evaluated; they report `null`.
+ */
+export const CompanyBrainLearningDecisionSummary = z.object({
+  receiptId: z.string().uuid(),
+  outcome: GovernedLearningDecisionOutcome,
+  automaticEligible: z.boolean(),
+  reasons: z.array(GovernedLearningDecisionReason).max(16),
+});
+export type CompanyBrainLearningDecisionSummary = z.infer<
+  typeof CompanyBrainLearningDecisionSummary
+>;
+
+/**
+ * Bounded, content-free reason why evaluation or activation did not complete.
+ * The proposal write itself remains durable regardless.
+ */
+export const CompanyBrainLearningStepFailure = z.object({
+  stage: z.enum(["evaluation", "activation"]),
+  code: z.enum(["authority", "conflict", "invalid_operation", "unavailable"]),
+});
+export type CompanyBrainLearningStepFailure = z.infer<typeof CompanyBrainLearningStepFailure>;
+
+export const CompanyBrainLearningPolicyRouteReceipt = z.object({
+  operationId,
+  workspaceId: z.string().uuid(),
+  effectivePolicy: WorkspaceLearningPolicyEffectiveMode,
+  decision: CompanyBrainLearningPolicyDecision,
+  write: CompanyBrainGovernedWriteReceipt.nullable(),
+  learning: CompanyBrainLearningDecisionSummary.nullable().default(null),
+  learningFailure: CompanyBrainLearningStepFailure.nullable().default(null),
+  activation: z.object({
+    requested: z.boolean(),
+    activated: z.boolean(),
+    boundary: z.enum([
+      "policy_off",
+      "human_review",
+      "destination_authority",
+      "not_eligible",
+      "human_activation_required",
+      "activated",
+    ]),
+    receiptId: z.string().uuid().nullable().default(null),
+    destination: GovernedLearningActivationDestination.nullable().default(null),
+    destinationRevisionId: z.string().uuid().nullable().default(null),
+    effectiveAt: z.string().datetime().nullable().default(null),
+  }),
+});
+export type CompanyBrainLearningPolicyRouteReceipt = z.infer<
+  typeof CompanyBrainLearningPolicyRouteReceipt
+>;