@opengeni/contracts 0.44.1 → 1.0.0

package/src/slack-rest-mcp.ts

@@ -0,0 +1,194 @@
+/** The catalog and OAuth identity stay stable while calls use the ordinary Web API. */
+export const OFFICIAL_SLACK_MCP_URL = "https://mcp.slack.com/mcp";
+export const SLACK_REST_API_BASE = "https://slack.com/api/";
+
+export const OPENGENI_SLACK_REST_USER_SCOPES = [
+  "channels:read",
+  "groups:read",
+  "im:read",
+  "mpim:read",
+  "channels:history",
+  "groups:history",
+  "im:history",
+  "mpim:history",
+  "users:read",
+  "im:write",
+  "chat:write",
+] as const;
+
+/** Slack returns comma-delimited scopes, including in existing saved grants. */
+export function normalizeSlackScopes(
+  scopes: readonly string[] | string | undefined | null,
+): string[] {
+  return [
+    ...new Set(
+      (typeof scopes === "string" ? [scopes] : (scopes ?? []))
+        .flatMap((entry) => entry.split(/[\s,]+/u))
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+export type SlackRestMcpTool = {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required: string[];
+    additionalProperties: false;
+  };
+  annotations: {
+    readOnlyHint: boolean;
+    destructiveHint: false;
+    idempotentHint: boolean;
+    openWorldHint: true;
+  };
+};
+
+const conversationScopes = ["channels:read", "groups:read", "im:read", "mpim:read"];
+const historyScopes = ["channels:history", "groups:history", "im:history", "mpim:history"];
+const channel = { type: "string", description: "Slack conversation ID, such as C123 or D123." };
+const cursor = { type: "string", maxLength: 4096, description: "Cursor from the previous page." };
+const directoryPage = { type: "integer", minimum: 1, maximum: 100, default: 100 };
+const historyPage = { type: "integer", minimum: 1, maximum: 15, default: 15 };
+const timestamp = { type: "string", pattern: "^[0-9]+\\.[0-9]+$" };
+
+function tool(
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: string[] = [],
+  mutation = false,
+): SlackRestMcpTool {
+  return {
+    name,
+    description,
+    inputSchema: { type: "object", properties, required, additionalProperties: false },
+    annotations: {
+      readOnlyHint: !mutation,
+      destructiveHint: false,
+      idempotentHint: !mutation,
+      openWorldHint: true,
+    },
+  };
+}
+
+/** Static reviewed pilot surface. Each call reads only one explicitly requested page. */
+export const SLACK_REST_MCP_TOOLS: SlackRestMcpTool[] = [
+  tool(
+    "slack_list_channels",
+    "Lists one page of conversations visible to your connected Slack account. Conversation types without a granted read scope are omitted.",
+    {
+      types: {
+        type: "array",
+        items: { type: "string", enum: ["public_channel", "private_channel", "im", "mpim"] },
+        minItems: 1,
+        maxItems: 4,
+      },
+      cursor,
+      limit: directoryPage,
+      exclude_archived: { type: "boolean", default: true },
+    },
+  ),
+  tool(
+    "slack_get_channel_info",
+    "Gets metadata for one conversation visible to your connected Slack account.",
+    { channel },
+    ["channel"],
+  ),
+  tool(
+    "slack_list_channel_members",
+    "Lists one page of members in a visible channel or group conversation.",
+    { channel, cursor, limit: directoryPage },
+    ["channel"],
+  ),
+  tool("slack_list_users", "Lists one page of users in the connected Slack workspace.", {
+    cursor,
+    limit: directoryPage,
+  }),
+  tool(
+    "slack_get_user_info",
+    "Gets a user's profile by their Slack user ID. Email is included only when Slack has granted that scope.",
+    { user: { type: "string" } },
+    ["user"],
+  ),
+  tool(
+    "slack_read_channel",
+    "Reads one page of at most 15 messages from a selected conversation. Slack history limits are shared across the workspace. No automatic pagination or backfill.",
+    {
+      channel,
+      cursor,
+      limit: historyPage,
+      oldest: timestamp,
+      latest: timestamp,
+      inclusive: { type: "boolean", default: false },
+    },
+    ["channel"],
+  ),
+  tool(
+    "slack_read_thread",
+    "Reads one page of at most 15 messages in a selected thread. Slack thread limits are shared across the workspace. No automatic pagination or backfill.",
+    {
+      channel,
+      ts: { ...timestamp, description: "Thread root message timestamp." },
+      cursor,
+      limit: historyPage,
+    },
+    ["channel", "ts"],
+  ),
+  tool(
+    "slack_open_dm",
+    "Opens or resumes a direct message with one Slack user as your connected account.",
+    { user: { type: "string" } },
+    ["user"],
+    true,
+  ),
+  tool(
+    "slack_send_message",
+    "Sends a message as your connected Slack account. Supply thread_ts to reply in a thread. Review the recipient and text before approving. An uncertain submission is never automatically retried.",
+    {
+      channel,
+      text: { type: "string", minLength: 1, maxLength: 40000 },
+      thread_ts: { ...timestamp, description: "Optional thread root timestamp for a reply." },
+      unfurl_links: { type: "boolean", default: false },
+      unfurl_media: { type: "boolean", default: false },
+    },
+    ["channel", "text"],
+    true,
+  ),
+];
+
+const REQUIRED_ANY_SCOPES: Readonly<Record<string, readonly string[]>> = {
+  slack_list_channels: conversationScopes,
+  slack_get_channel_info: conversationScopes,
+  slack_list_channel_members: ["channels:read", "groups:read", "mpim:read"],
+  slack_list_users: ["users:read"],
+  slack_get_user_info: ["users:read"],
+  slack_read_channel: historyScopes,
+  slack_read_thread: historyScopes,
+  slack_open_dm: ["im:write"],
+  slack_send_message: ["chat:write"],
+};
+
+export function slackRestMcpToolsForScopes(scopes: readonly string[] | string): SlackRestMcpTool[] {
+  const granted = new Set(normalizeSlackScopes(scopes));
+  return SLACK_REST_MCP_TOOLS.filter((entry) =>
+    REQUIRED_ANY_SCOPES[entry.name]?.some((scope) => granted.has(scope)),
+  ).map((entry) => ({
+    ...entry,
+    inputSchema: {
+      ...entry.inputSchema,
+      required: [...entry.inputSchema.required],
+      properties: { ...entry.inputSchema.properties },
+    },
+    annotations: { ...entry.annotations },
+  }));
+}
+
+export const SLACK_CONVERSATION_READ_SCOPE_BY_TYPE = {
+  public_channel: "channels:read",
+  private_channel: "groups:read",
+  im: "im:read",
+  mpim: "mpim:read",
+} as const;

package/src/slack-task-policy.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+
+export const SLACK_TASK_POLICY_ID_MAX_CHARS = 128;
+export const SLACK_TASK_POLICY_REASON_MAX_CHARS = 4_096;
+export const SLACK_TASK_POLICY_MAX_IDS = 256;
+
+const SlackOpaqueId = z.string().min(1).max(SLACK_TASK_POLICY_ID_MAX_CHARS);
+
+export const SlackSharedConversationMode = z.enum(["deny", "private_handoff"]);
+export type SlackSharedConversationMode = z.infer<typeof SlackSharedConversationMode>;
+
+export const SlackResultPublicationMode = z.enum(["never", "approval_required", "allow"]);
+export type SlackResultPublicationMode = z.infer<typeof SlackResultPublicationMode>;
+
+function uniqueSortedIds(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export const SlackTaskPolicyContent = z
+  .object({
+    allowedTeamIds: z
+      .array(SlackOpaqueId)
+      .max(SLACK_TASK_POLICY_MAX_IDS)
+      .transform(uniqueSortedIds),
+    allowedConversationIds: z
+      .array(SlackOpaqueId)
+      .max(SLACK_TASK_POLICY_MAX_IDS)
+      .transform(uniqueSortedIds),
+    allowGuestInitiators: z.boolean(),
+    allowExternalInitiators: z.boolean(),
+    allowMpim: z.boolean(),
+    sharedConversationMode: SlackSharedConversationMode,
+    resultPublicationMode: SlackResultPublicationMode,
+  })
+  .strict();
+export type SlackTaskPolicyContent = z.infer<typeof SlackTaskPolicyContent>;
+
+export const DEFAULT_SLACK_TASK_POLICY: SlackTaskPolicyContent = Object.freeze({
+  allowedTeamIds: [],
+  allowedConversationIds: [],
+  allowGuestInitiators: false,
+  allowExternalInitiators: false,
+  allowMpim: false,
+  sharedConversationMode: "deny",
+  resultPublicationMode: "never",
+});
+
+export function canonicalizeSlackTaskPolicy(value: SlackTaskPolicyContent): SlackTaskPolicyContent {
+  const parsed = SlackTaskPolicyContent.parse(value);
+  return {
+    allowedTeamIds: parsed.allowedTeamIds,
+    allowedConversationIds: parsed.allowedConversationIds,
+    allowGuestInitiators: parsed.allowGuestInitiators,
+    allowExternalInitiators: parsed.allowExternalInitiators,
+    allowMpim: parsed.allowMpim,
+    sharedConversationMode: parsed.sharedConversationMode,
+    resultPublicationMode: parsed.resultPublicationMode,
+  };
+}
+
+export const SlackTaskPolicyRevisionIdentity = z.object({
+  id: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+});
+export type SlackTaskPolicyRevisionIdentity = z.infer<typeof SlackTaskPolicyRevisionIdentity>;
+
+export const SlackTaskPolicyRevision = SlackTaskPolicyRevisionIdentity.extend({
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  policy: SlackTaskPolicyContent,
+  supersedesRevisionId: z.string().uuid().nullable(),
+  createdBySubjectId: z.string().min(1).max(1_024),
+  createdAt: z.string().datetime(),
+});
+export type SlackTaskPolicyRevision = z.infer<typeof SlackTaskPolicyRevision>;
+
+export const SlackTaskPolicyHead = z.object({
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  revisionId: z.string().uuid(),
+  revision: z.number().int().positive(),
+  policyHash: z.string().regex(/^[0-9a-f]{64}$/),
+  activationVersion: z.number().int().positive(),
+  activatedAt: z.string().datetime(),
+});
+export type SlackTaskPolicyHead = z.infer<typeof SlackTaskPolicyHead>;
+
+export const SlackTaskPolicyActivationEvent = z.object({
+  id: z.string().uuid(),
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  activationVersion: z.number().int().positive(),
+  oldRevision: SlackTaskPolicyRevisionIdentity.nullable(),
+  newRevision: SlackTaskPolicyRevisionIdentity,
+  actorSubjectId: z.string().min(1).max(1_024),
+  reason: z.string().min(1).max(SLACK_TASK_POLICY_REASON_MAX_CHARS),
+  createdAt: z.string().datetime(),
+});
+export type SlackTaskPolicyActivationEvent = z.infer<typeof SlackTaskPolicyActivationEvent>;
+
+export const SlackTaskPolicyListResponse = z.object({
+  current: SlackTaskPolicyHead.nullable(),
+  activeRevision: SlackTaskPolicyRevision.nullable(),
+  revisions: z.array(SlackTaskPolicyRevision),
+  activationEvents: z.array(SlackTaskPolicyActivationEvent),
+});
+export type SlackTaskPolicyListResponse = z.infer<typeof SlackTaskPolicyListResponse>;
+
+export const UpdateSlackTaskPolicyRequest = z.object({
+  operationId: z.string().uuid().optional(),
+  policy: SlackTaskPolicyContent,
+  expectedCurrentRevisionId: z.string().uuid().nullable(),
+  expectedActivationVersion: z.number().int().nonnegative(),
+  reason: z.string().trim().min(1).max(SLACK_TASK_POLICY_REASON_MAX_CHARS),
+});
+export type UpdateSlackTaskPolicyRequest = z.infer<typeof UpdateSlackTaskPolicyRequest>;
+
+export const SlackTaskPolicyMutationResponse = z.object({
+  revision: SlackTaskPolicyRevision,
+  head: SlackTaskPolicyHead,
+  event: SlackTaskPolicyActivationEvent,
+});
+export type SlackTaskPolicyMutationResponse = z.infer<typeof SlackTaskPolicyMutationResponse>;
+
+export type SlackTaskPolicyConversationFacts = Readonly<{
+  installationTeamId: string;
+  conversationId: string;
+  contextTeamId: string | null;
+  connectedTeamIds: readonly string[] | null;
+  sharedTeamIds: readonly string[] | null;
+  isShared: boolean;
+  isExternallyShared: boolean;
+  isOrgShared: boolean;
+  isPendingExternallyShared: boolean;
+  isMpim: boolean;
+}>;
+
+export type SlackTaskPolicyInitiatorFacts = Readonly<{
+  teamId: string | null;
+  isGuest: boolean | null;
+  isExternal: boolean | null;
+}>;
+
+export type SlackTaskPolicyDecision = Readonly<{
+  disposition: "ordinary" | "deny" | "private_handoff";
+  publication: SlackResultPublicationMode;
+  reason:
+    | "ordinary_conversation"
+    | "policy_missing"
+    | "conversation_not_allowed"
+    | "team_not_allowed"
+    | "ambiguous_shared_facts"
+    | "mpim_not_allowed"
+    | "guest_not_allowed"
+    | "external_not_allowed"
+    | "allowed";
+}>;
+
+export function evaluateSlackTaskPolicy(input: {
+  policy: SlackTaskPolicyContent | null;
+  conversation: SlackTaskPolicyConversationFacts;
+  initiator: SlackTaskPolicyInitiatorFacts;
+}): SlackTaskPolicyDecision {
+  const { conversation, initiator } = input;
+  const governed =
+    conversation.isShared ||
+    conversation.isExternallyShared ||
+    conversation.isOrgShared ||
+    conversation.isPendingExternallyShared ||
+    conversation.isMpim;
+  if (!governed) {
+    return { disposition: "ordinary", publication: "allow", reason: "ordinary_conversation" };
+  }
+  if (!input.policy) return { disposition: "deny", publication: "never", reason: "policy_missing" };
+  const policy = canonicalizeSlackTaskPolicy(input.policy);
+  if (!policy.allowedConversationIds.includes(conversation.conversationId)) {
+    return { disposition: "deny", publication: "never", reason: "conversation_not_allowed" };
+  }
+  if (conversation.isMpim && !policy.allowMpim) {
+    return { disposition: "deny", publication: "never", reason: "mpim_not_allowed" };
+  }
+  if (initiator.isGuest === null || initiator.isExternal === null || initiator.teamId === null) {
+    return { disposition: "deny", publication: "never", reason: "ambiguous_shared_facts" };
+  }
+  if (initiator.isGuest && !policy.allowGuestInitiators) {
+    return { disposition: "deny", publication: "never", reason: "guest_not_allowed" };
+  }
+  if (initiator.isExternal && !policy.allowExternalInitiators) {
+    return { disposition: "deny", publication: "never", reason: "external_not_allowed" };
+  }
+  const teams = [
+    conversation.installationTeamId,
+    conversation.contextTeamId,
+    initiator.teamId,
+    ...(conversation.connectedTeamIds ?? []),
+    ...(conversation.sharedTeamIds ?? []),
+  ];
+  if (conversation.connectedTeamIds === null || conversation.sharedTeamIds === null) {
+    return { disposition: "deny", publication: "never", reason: "ambiguous_shared_facts" };
+  }
+  if (teams.some((teamId) => teamId === null || !policy.allowedTeamIds.includes(teamId))) {
+    return { disposition: "deny", publication: "never", reason: "team_not_allowed" };
+  }
+  if (policy.sharedConversationMode === "deny") {
+    return { disposition: "deny", publication: "never", reason: "allowed" };
+  }
+  return {
+    disposition: "private_handoff",
+    publication: policy.resultPublicationMode,
+    reason: "allowed",
+  };
+}

package/src/spreadsheet-artifact-commands.ts

@@ -2,6 +2,7 @@ import {
   canonicalSpreadsheetDateFromMilliseconds,
   canonicalSpreadsheetDateMilliseconds,
 } from "./spreadsheet-artifact-date";
+import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions";
 
 /**
  * Canonical, identity-free spreadsheet mutation commands nested inside
@@ -10,14 +11,14 @@ import {
  * authority.
  */
 
-export const SPREADSHEET_ARTIFACT_COMMAND_VERSION = 1 as const;
+export { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "./editable-artifact-versions";
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_BYTES = 4 * 1024 * 1024;
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_COMMANDS = 4_096;
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_CELLS = 1_000_000;
 export const SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES = 1 * 1024 * 1024;
 export const SPREADSHEET_ARTIFACT_SHEET_NAME_MAX_UTF16_UNITS = 31;
 
-const MAGIC = new TextEncoder().encode("OGASC001");
+const MAGIC = new TextEncoder().encode("OGASC002");
 const HEADER_BYTES = 8 + 2 + 2 + 4 + 8;
 const CHECKSUM_BYTES = 8;
 const textEncoder = new TextEncoder();
@@ -78,7 +79,6 @@ export type SpreadsheetCellScalar =
   | SpreadsheetFormulaError;
 export type SpreadsheetFormulaCell = Readonly<{
   formula: string;
-  cached: SpreadsheetCellScalar;
 }>;
 export type SpreadsheetCellInput = SpreadsheetCellScalar | SpreadsheetFormulaCell;
 
@@ -491,7 +491,7 @@ function batchRecord(input: unknown): SpreadsheetArtifactCommandBatch {
   const batch = plainRecord(input, "spreadsheet command batch");
   exactKeys(batch, ["commands", "version"], "spreadsheet command batch");
   if (batch.version !== SPREADSHEET_ARTIFACT_COMMAND_VERSION) {
-    throw new TypeError("spreadsheet command batch version must be 1");
+    throw new TypeError("spreadsheet command batch version must be 2");
   }
   if (!Array.isArray(batch.commands)) throw new TypeError("commands must be an array");
   if (
@@ -770,13 +770,12 @@ class BinaryWriter {
   cell(value: unknown): void {
     if (isFormulaCell(value)) {
       const cell = plainRecord(value, "formula cell");
-      exactKeys(cell, ["cached", "formula"], "formula cell");
+      exactKeys(cell, ["formula"], "formula cell");
       if (typeof cell.formula !== "string" || cell.formula.length === 0) {
         throw new TypeError("formula source must be a nonempty string");
       }
       this.u8(1);
       this.string(cell.formula, SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES);
-      this.scalar(cell.cached);
       return;
     }
     this.u8(0);
@@ -902,12 +901,12 @@ class BinaryReader {
   cell(): SpreadsheetCellInput {
     const formulaTag = this.u8();
     if (formulaTag > 1) throw new TypeError("spreadsheet formula presence tag is invalid");
-    const formula =
-      formulaTag === 1
-        ? this.nonemptyFormula(this.string(SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES))
-        : null;
-    const cached = this.scalar();
-    return formula === null ? cached : Object.freeze({ formula, cached });
+    if (formulaTag === 1) {
+      return Object.freeze({
+        formula: this.nonemptyFormula(this.string(SPREADSHEET_ARTIFACT_COMMAND_MAX_STRING_BYTES)),
+      });
+    }
+    return this.scalar();
   }
 
   done(message: string): void {
@@ -981,7 +980,7 @@ function isFormulaError(value: unknown): value is SpreadsheetFormulaError {
     typeof value === "object" &&
     value !== null &&
     !Array.isArray(value) &&
-    typeof (value as Record<string, unknown>).error === "string"
+    Object.hasOwn(value, "error")
   );
 }
 

package/src/subscription-account-pools.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ClaudeSubscriptionUsage } from "./claude-subscription-usage";
+
+/** Shared, secret-free account list contract for native subscription pools. */
+export const SubscriptionAccountSummary = z.object({
+  id: z.string().uuid(),
+  scope: z.enum(["organization", "workspace", "user"]),
+  subject: z.string().min(1),
+  email: z.string().email().nullable(),
+  label: z.string().nullable(),
+  plan: z.string().nullable(),
+  status: z.enum(["active", "needs_relogin", "error", "disabled"]),
+  active: z.boolean(),
+  expiresAt: z.string().datetime().nullable(),
+  lastRefreshAt: z.string().datetime().nullable(),
+  lastError: z.string().nullable(),
+  allocatorEnabled: z.boolean(),
+  allocatorVersion: z.number().int().positive(),
+  allocatorUpdatedAt: z.string().datetime().nullable(),
+});
+export type SubscriptionAccountSummary = z.infer<typeof SubscriptionAccountSummary>;
+export const SubscriptionPoolSettings = z
+  .object({
+    rotationEnabled: z.boolean(),
+    rotationStrategy: z.literal("sharded"),
+    activeCredentialId: z.string().uuid().nullable(),
+  })
+  .strict();
+export type SubscriptionPoolSettings = z.infer<typeof SubscriptionPoolSettings>;
+export const ClaudeSubscriptionAccount = SubscriptionAccountSummary.extend({
+  version: z.number().int().positive(),
+  usage: ClaudeSubscriptionUsage.optional(),
+}).strict();
+export type ClaudeSubscriptionAccount = z.infer<typeof ClaudeSubscriptionAccount>;
+export const ClaudeSubscriptionAccountsResponse = z
+  .object({
+    accounts: z.array(ClaudeSubscriptionAccount),
+    activeAccountId: z.string().uuid().nullable(),
+    source: z.enum(["organization", "workspace", "user"]),
+    organizationId: z.string().uuid(),
+    settings: SubscriptionPoolSettings,
+  })
+  .strict();
+export type ClaudeSubscriptionAccountsResponse = z.infer<typeof ClaudeSubscriptionAccountsResponse>;

package/src/task-notes.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+export const TASK_NOTE_TEXT_MAX_BYTES = 4_096;
+export const TASK_NOTE_REASON_MAX_BYTES = 2_048;
+export const TASK_NOTE_MAX_LIFETIME_DAYS = 90;
+export const TASK_NOTE_ACTIVE_RECORD_CAP = 500;
+export const TASK_NOTE_LIST_DEFAULT_LIMIT = 10;
+export const TASK_NOTE_LIST_MAX_LIMIT = 20;
+export const TASK_NOTE_LIST_RESPONSE_MAX_BYTES = 96 * 1_024;
+
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
+
+export function boundedTaskNoteText(maxBytes: number, label: string) {
+  return z
+    .string()
+    .min(1)
+    .superRefine((value, ctx) => {
+      if (value !== value.trim()) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must not have leading or trailing whitespace`,
+        });
+      }
+      if (utf8Bytes(value) > maxBytes) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
+        });
+      }
+    });
+}
+
+export const TaskNoteText = boundedTaskNoteText(TASK_NOTE_TEXT_MAX_BYTES, "task note text");
+export const TaskNoteReason = boundedTaskNoteText(
+  TASK_NOTE_REASON_MAX_BYTES,
+  "task note archive reason",
+);
+
+export const TaskNoteKind = z.enum([
+  "finding",
+  "decision",
+  "blocker",
+  "ownership",
+  "artifact",
+  "handoff",
+]);
+export type TaskNoteKind = z.infer<typeof TaskNoteKind>;
+
+export const TaskNoteStatus = z.enum(["active", "archived"]);
+export type TaskNoteStatus = z.infer<typeof TaskNoteStatus>;
+
+export const TaskNoteActorKind = z.enum(["human", "service"]);
+export type TaskNoteActorKind = z.infer<typeof TaskNoteActorKind>;
+
+export const TaskNote = z.object({
+  id: z.string().uuid(),
+  rootSessionId: z.string().uuid(),
+  kind: TaskNoteKind,
+  text: TaskNoteText,
+  status: TaskNoteStatus,
+  version: z.number().int().positive(),
+  expiresAt: z.string().datetime({ offset: true }),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+  archivedAt: z.string().datetime({ offset: true }).nullable(),
+  provenance: z.object({
+    actorKind: TaskNoteActorKind,
+    sourceSessionId: z.string().uuid(),
+    sourceTurnId: z.string().uuid(),
+  }),
+});
+export type TaskNote = z.infer<typeof TaskNote>;
+
+export const TaskNoteMutationResult = z.object({
+  note: TaskNote,
+  replayed: z.boolean(),
+});
+export type TaskNoteMutationResult = z.infer<typeof TaskNoteMutationResult>;
+
+/** Atomic correction lineage: archive one exact v1 note and create one v1 replacement. */
+export const TaskNoteReplacementResult = z.object({
+  operationId: z.string().uuid(),
+  inputHash: z.string().regex(/^[0-9a-f]{64}$/),
+  replaces: z.object({
+    noteId: z.string().uuid(),
+    archivedVersion: z.literal(2),
+  }),
+  replacement: TaskNote,
+  replayed: z.boolean(),
+});
+export type TaskNoteReplacementResult = z.infer<typeof TaskNoteReplacementResult>;
+
+export const TaskNoteListResponse = z
+  .object({
+    notes: z.array(TaskNote).max(TASK_NOTE_LIST_MAX_LIMIT),
+  })
+  .superRefine((value, ctx) => {
+    if (utf8Bytes(JSON.stringify(value)) > TASK_NOTE_LIST_RESPONSE_MAX_BYTES) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `task note list response must be at most ${TASK_NOTE_LIST_RESPONSE_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+export type TaskNoteListResponse = z.infer<typeof TaskNoteListResponse>;