@opengeni/contracts 0.50.0 → 1.0.0

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/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
+>;

package/src/company-brain.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+
+import { WorkspaceStateKnowledge } from "./workspace-state";
+
+export const COMPANY_BRAIN_OKF_SCHEMA_VERSION = 1 as const;
+export const COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES = 512;
+export const COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS = 262_144;
+export const COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES = 4 * 1024 * 1024;
+export const COMPANY_BRAIN_INSPECTOR_DEFAULT_LIMIT = 20;
+export const COMPANY_BRAIN_INSPECTOR_MAX_LIMIT = 50;
+export const COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS = 1_024;
+export const COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES = 16 * 1_024;
+export const COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES = 64 * 1_024;
+
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
+const boundedUtf8 = (maxBytes: number) =>
+  z.string().superRefine((value, context) => {
+    if (utf8Bytes(value) > maxBytes) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
+
+export const CompanyBrainContextReceipt = z
+  .object({
+    id: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    rootSessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    acceptedAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+    sessionRole: z.enum(["root", "child"]),
+    memoryEnabled: z.boolean(),
+    // Snapshots are immutable: a turn accepted before the standing block was
+    // retired recorded `legacy_standing` and still reads back that way. This
+    // is a historical fact about that turn, not a mode anyone can select.
+    memoryPromptMode: z.enum(["legacy_standing", "retrieval_only"]),
+    companyProfileIncluded: z.boolean(),
+    instructionPolicyEntryHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    preferenceDescriptorHash: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/u)
+      .nullable(),
+    companyProfileSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotId: z.string().uuid(),
+    turnContextSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotSource: z.enum(["accepted_turn", "legacy_first_claim"]),
+    selectionHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    selectedMemoryCount: z.number().int().nonnegative().max(50),
+    renderedMemoryCount: z.number().int().nonnegative().max(50),
+    budgetOmittedMemoryCount: z.number().int().nonnegative().max(50),
+  })
+  .strict();
+export type CompanyBrainContextReceipt = z.infer<typeof CompanyBrainContextReceipt>;
+
+export const CompanyBrainContextReceiptPage = z
+  .object({
+    receipts: z.array(CompanyBrainContextReceipt).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    nextCursor: z.string().min(1).max(COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS).nullable(),
+    hasMore: z.boolean(),
+  })
+  .strict();
+export type CompanyBrainContextReceiptPage = z.infer<typeof CompanyBrainContextReceiptPage>;
+
+export const CompanyBrainKnowledgeProposal = z
+  .object({
+    id: z.string().uuid(),
+    authority: z.object({ kind: z.enum(["organization", "workspace", "personal"]) }).strict(),
+    targetKind: z.enum(["instruction_policy", "preference"]),
+    targetScope: z.string().min(1).max(96),
+    targetKey: z.string().min(1).max(96).nullable(),
+    content: boundedUtf8(COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    source: z.object({ claimId: z.string().uuid(), evidenceId: z.string().uuid() }).strict(),
+    status: z.literal("proposed"),
+    createdAt: z.string().datetime(),
+    projection: z
+      .object({
+        truncated: z.boolean(),
+        originalContentUtf8Bytes: z.number().int().nonnegative().max(1_048_576),
+      })
+      .strict(),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposal = z.infer<typeof CompanyBrainKnowledgeProposal>;
+
+export const CompanyBrainKnowledgeProposalPage = z
+  .object({
+    proposals: z.array(CompanyBrainKnowledgeProposal).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    truncatedForCount: z.boolean(),
+    truncatedForResponseBytes: z.boolean(),
+    responseBytes: z.number().int().nonnegative().max(COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposalPage = z.infer<typeof CompanyBrainKnowledgeProposalPage>;
+
+export const CompanyBrainGuidanceClassification = z.enum([
+  "company_profile",
+  "mandatory_rule",
+  "guide",
+]);
+export type CompanyBrainGuidanceClassification = z.infer<typeof CompanyBrainGuidanceClassification>;
+
+export const CompanyBrainGuidanceScope = z.enum(["organization", "workspace", "personal"]);
+export type CompanyBrainGuidanceScope = z.infer<typeof CompanyBrainGuidanceScope>;
+
+export const CompanyBrainGuidanceLifecycle = z.enum([
+  "active",
+  "proposal",
+  "inactive",
+  "rejected",
+  "superseded",
+  "expired",
+  "historical",
+]);
+export type CompanyBrainGuidanceLifecycle = z.infer<typeof CompanyBrainGuidanceLifecycle>;
+
+export const CompanyBrainGuidanceRelationship = z
+  .object({
+    type: z.enum(["corrects", "supersedes", "superseded_by"]),
+    targetId: z.string().min(1).max(512),
+  })
+  .strict();
+export type CompanyBrainGuidanceRelationship = z.infer<typeof CompanyBrainGuidanceRelationship>;
+
+export const CompanyBrainGuidanceEntry = z
+  .object({
+    id: z.string().min(1).max(512),
+    revisionId: z.string().uuid(),
+    path: z.string().min(1).max(512),
+    scope: CompanyBrainGuidanceScope,
+    classification: CompanyBrainGuidanceClassification,
+    title: z.string().min(1).max(160),
+    description: z.string().max(512).nullable(),
+    content: z.string().min(1).max(COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    revision: z.number().int().positive(),
+    active: z.boolean(),
+    lifecycle: CompanyBrainGuidanceLifecycle,
+    provenance: z
+      .object({
+        source: z.string().min(1).max(96),
+        sourceId: z.string().min(1).max(512).nullable(),
+        trust: z.string().min(1).max(96).nullable(),
+      })
+      .strict(),
+    relationships: z.array(CompanyBrainGuidanceRelationship).max(32),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type CompanyBrainGuidanceEntry = z.infer<typeof CompanyBrainGuidanceEntry>;
+
+export const CompanyBrainGuidanceTruncationReason = z.enum([
+  "company_profile_history",
+  "instruction_policy_history",
+  "preference_count",
+  "preference_history",
+  "aggregate_item_count",
+  "aggregate_content_bytes",
+]);
+export type CompanyBrainGuidanceTruncationReason = z.infer<
+  typeof CompanyBrainGuidanceTruncationReason
+>;
+
+export const CompanyBrainOkfPackage = z
+  .object({
+    kind: z.literal("opengeni.company_brain.okf"),
+    schemaVersion: z.literal(COMPANY_BRAIN_OKF_SCHEMA_VERSION),
+    workspaceId: z.string().uuid(),
+    generatedAt: z.string().datetime(),
+    permissions: z
+      .object({
+        guidance: z.literal("available"),
+        knowledge: z.enum(["available", "unavailable"]),
+      })
+      .strict(),
+    guidance: z
+      .object({
+        entries: z.array(CompanyBrainGuidanceEntry).max(COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES),
+        truncated: z.boolean(),
+        truncationReasons: z.array(CompanyBrainGuidanceTruncationReason).max(6),
+      })
+      .strict(),
+    knowledge: WorkspaceStateKnowledge,
+    omissions: z
+      .array(
+        z.enum([
+          "inaccessible_knowledge",
+          "document_bodies_use_documents_export",
+          "memory_bodies_and_provenance",
+          "secret_values_and_credentials",
+          "session_messages_and_task_notes",
+          "policy_and_preference_actor_identifiers",
+        ]),
+      )
+      .max(6),
+  })
+  .strict();
+export type CompanyBrainOkfPackage = z.infer<typeof CompanyBrainOkfPackage>;