@opengeni/contracts 0.32.0 → 0.35.0

package/dist/workspace-state.d.ts

@@ -6,6 +6,10 @@ export declare const WORKSPACE_STATE_MAX_GAPS = 16;
 export declare const WORKSPACE_STATE_BASE_NAME_MAX_CHARS = 160;
 export declare const WORKSPACE_STATE_TOPIC_MAX_CHARS = 96;
 export declare const WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT = 100;
+export declare const WorkspaceStateQuery: z.ZodObject<{
+    attemptId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceStateQuery = z.infer<typeof WorkspaceStateQuery>;
 export declare const WorkspaceStateDocumentStatusCounts: z.ZodObject<{
     queued: z.ZodNumber;
     indexing: z.ZodNumber;
@@ -364,6 +368,118 @@ export declare const WorkspaceStateKnowledge: z.ZodDiscriminatedUnion<[z.ZodObje
     requiredPermission: z.ZodLiteral<"documents:search">;
 }, z.core.$strict>], "availability">;
 export type WorkspaceStateKnowledge = z.infer<typeof WorkspaceStateKnowledge>;
+export declare const WorkspaceStateGovernanceDriftStatus: z.ZodEnum<{
+    changed: "changed";
+    identical: "identical";
+    missing: "missing";
+    superseded: "superseded";
+    truncated: "truncated";
+    unavailable: "unavailable";
+}>;
+export type WorkspaceStateGovernanceDriftStatus = z.infer<typeof WorkspaceStateGovernanceDriftStatus>;
+export declare const WorkspaceStateAttemptGovernance: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"not_requested">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodLiteral<"attempt_not_found_or_not_authorized">;
+    driftStatus: z.ZodLiteral<"unavailable">;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"available">;
+    attemptId: z.ZodString;
+    executionGeneration: z.ZodNumber;
+    acceptedAt: z.ZodString;
+    policySnapshot: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+        id: z.ZodString;
+        createdAt: z.ZodString;
+        entryHash: z.ZodString;
+        policyRole: z.ZodNullable<z.ZodString>;
+        roleSource: z.ZodEnum<{
+            invalid_metadata_fallback: "invalid_metadata_fallback";
+            metadata_fallback: "metadata_fallback";
+            none: "none";
+            session_binding: "session_binding";
+        }>;
+        entries: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                charter: "charter";
+                policy: "policy";
+            }>;
+            scope: z.ZodEnum<{
+                global: "global";
+                role: "role";
+            }>;
+            roleKey: z.ZodNullable<z.ZodString>;
+            revisionId: z.ZodString;
+            revision: z.ZodNumber;
+            contentHash: z.ZodString;
+            activationVersion: z.ZodNumber;
+            activatedAt: z.ZodString;
+            provenance: z.ZodObject<{
+                source: z.ZodEnum<{
+                    human: "human";
+                    knowledge_proposal: "knowledge_proposal";
+                    legacy_import: "legacy_import";
+                    onboarding: "onboarding";
+                }>;
+                sourceIdHash: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"missing">;
+    }, z.core.$strict>], "status">;
+    preferenceSnapshot: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        status: z.ZodLiteral<"available">;
+        id: z.ZodString;
+        createdAt: z.ZodString;
+        descriptorHash: z.ZodString;
+        descriptorCount: z.ZodNumber;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodObject<{
+        status: z.ZodLiteral<"missing">;
+    }, z.core.$strict>], "status">;
+    drift: z.ZodObject<{
+        overall: z.ZodEnum<{
+            changed: "changed";
+            identical: "identical";
+            missing: "missing";
+            superseded: "superseded";
+            truncated: "truncated";
+            unavailable: "unavailable";
+        }>;
+        policy: z.ZodObject<{
+            status: z.ZodEnum<{
+                changed: "changed";
+                identical: "identical";
+                missing: "missing";
+                superseded: "superseded";
+                truncated: "truncated";
+                unavailable: "unavailable";
+            }>;
+            snapshotHash: z.ZodNullable<z.ZodString>;
+            currentHash: z.ZodNullable<z.ZodString>;
+            snapshotTargetCount: z.ZodNumber;
+            currentTargetCount: z.ZodNumber;
+        }, z.core.$strict>;
+        preferences: z.ZodObject<{
+            status: z.ZodEnum<{
+                changed: "changed";
+                identical: "identical";
+                missing: "missing";
+                superseded: "superseded";
+                truncated: "truncated";
+                unavailable: "unavailable";
+            }>;
+            snapshotHash: z.ZodNullable<z.ZodString>;
+            currentHash: z.ZodNullable<z.ZodString>;
+            snapshotDescriptorCount: z.ZodNumber;
+            currentDescriptorCount: z.ZodNumber;
+            snapshotTruncated: z.ZodBoolean;
+            currentTruncated: z.ZodBoolean;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "status">;
+export type WorkspaceStateAttemptGovernance = z.infer<typeof WorkspaceStateAttemptGovernance>;
 export declare const WorkspaceStateResponse: z.ZodObject<{
     workspaceId: z.ZodString;
     generatedAt: z.ZodString;
@@ -372,10 +488,108 @@ export declare const WorkspaceStateResponse: z.ZodObject<{
             source: z.ZodLiteral<"read_time_projection">;
             capturedAt: z.ZodString;
         }, z.core.$strict>;
-        policySnapshot: z.ZodObject<{
-            status: z.ZodLiteral<"not_captured">;
-            reason: z.ZodLiteral<"workspace_instruction_policy_snapshot_not_implemented">;
-        }, z.core.$strict>;
+        attemptGovernance: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"not_requested">;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"unavailable">;
+            reason: z.ZodLiteral<"attempt_not_found_or_not_authorized">;
+            driftStatus: z.ZodLiteral<"unavailable">;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"available">;
+            attemptId: z.ZodString;
+            executionGeneration: z.ZodNumber;
+            acceptedAt: z.ZodString;
+            policySnapshot: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                status: z.ZodLiteral<"available">;
+                id: z.ZodString;
+                createdAt: z.ZodString;
+                entryHash: z.ZodString;
+                policyRole: z.ZodNullable<z.ZodString>;
+                roleSource: z.ZodEnum<{
+                    invalid_metadata_fallback: "invalid_metadata_fallback";
+                    metadata_fallback: "metadata_fallback";
+                    none: "none";
+                    session_binding: "session_binding";
+                }>;
+                entries: z.ZodArray<z.ZodObject<{
+                    kind: z.ZodEnum<{
+                        charter: "charter";
+                        policy: "policy";
+                    }>;
+                    scope: z.ZodEnum<{
+                        global: "global";
+                        role: "role";
+                    }>;
+                    roleKey: z.ZodNullable<z.ZodString>;
+                    revisionId: z.ZodString;
+                    revision: z.ZodNumber;
+                    contentHash: z.ZodString;
+                    activationVersion: z.ZodNumber;
+                    activatedAt: z.ZodString;
+                    provenance: z.ZodObject<{
+                        source: z.ZodEnum<{
+                            human: "human";
+                            knowledge_proposal: "knowledge_proposal";
+                            legacy_import: "legacy_import";
+                            onboarding: "onboarding";
+                        }>;
+                        sourceIdHash: z.ZodNullable<z.ZodString>;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strict>, z.ZodObject<{
+                status: z.ZodLiteral<"missing">;
+            }, z.core.$strict>], "status">;
+            preferenceSnapshot: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                status: z.ZodLiteral<"available">;
+                id: z.ZodString;
+                createdAt: z.ZodString;
+                descriptorHash: z.ZodString;
+                descriptorCount: z.ZodNumber;
+                truncated: z.ZodBoolean;
+            }, z.core.$strict>, z.ZodObject<{
+                status: z.ZodLiteral<"missing">;
+            }, z.core.$strict>], "status">;
+            drift: z.ZodObject<{
+                overall: z.ZodEnum<{
+                    changed: "changed";
+                    identical: "identical";
+                    missing: "missing";
+                    superseded: "superseded";
+                    truncated: "truncated";
+                    unavailable: "unavailable";
+                }>;
+                policy: z.ZodObject<{
+                    status: z.ZodEnum<{
+                        changed: "changed";
+                        identical: "identical";
+                        missing: "missing";
+                        superseded: "superseded";
+                        truncated: "truncated";
+                        unavailable: "unavailable";
+                    }>;
+                    snapshotHash: z.ZodNullable<z.ZodString>;
+                    currentHash: z.ZodNullable<z.ZodString>;
+                    snapshotTargetCount: z.ZodNumber;
+                    currentTargetCount: z.ZodNumber;
+                }, z.core.$strict>;
+                preferences: z.ZodObject<{
+                    status: z.ZodEnum<{
+                        changed: "changed";
+                        identical: "identical";
+                        missing: "missing";
+                        superseded: "superseded";
+                        truncated: "truncated";
+                        unavailable: "unavailable";
+                    }>;
+                    snapshotHash: z.ZodNullable<z.ZodString>;
+                    currentHash: z.ZodNullable<z.ZodString>;
+                    snapshotDescriptorCount: z.ZodNumber;
+                    currentDescriptorCount: z.ZodNumber;
+                    snapshotTruncated: z.ZodBoolean;
+                    currentTruncated: z.ZodBoolean;
+                }, z.core.$strict>;
+            }, z.core.$strict>;
+        }, z.core.$strict>], "status">;
     }, z.core.$strict>;
     policy: z.ZodObject<{
         authority: z.ZodLiteral<"workspace_instruction_policy_heads">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/contracts",
-  "version": "0.32.0",
+  "version": "0.35.0",
   "description": "Shared zod schemas and wire-contract types for the OpenGeni API.",
   "license": "Apache-2.0",
   "repository": {

package/src/google-drive.ts

@@ -72,6 +72,59 @@ export type GoogleDriveSyncCadence = z.infer<typeof GoogleDriveSyncCadence>;
 export const GoogleDriveReadPolicy = z.enum(["allow", "ask", "block"]);
 export type GoogleDriveReadPolicy = z.infer<typeof GoogleDriveReadPolicy>;
 
+export const GoogleDriveConnectionLifecycleState = z.enum([
+  "active",
+  "paused",
+  "token_revoked",
+  "app_removed",
+  "disconnected",
+  "reconnect_required",
+  "reconsent_required",
+]);
+export type GoogleDriveConnectionLifecycleState = z.infer<
+  typeof GoogleDriveConnectionLifecycleState
+>;
+
+const GoogleDriveLifecycleObservedAt = z.string().datetime({ offset: true });
+export const GoogleDriveConnectionLifecycle = z.discriminatedUnion("state", [
+  z.object({
+    state: z.literal("active"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("paused"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("token_revoked"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("app_removed"),
+    recoverable: z.literal(false),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("disconnected"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("reconnect_required"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+  z.object({
+    state: z.literal("reconsent_required"),
+    recoverable: z.literal(true),
+    observedAt: GoogleDriveLifecycleObservedAt,
+  }),
+]);
+export type GoogleDriveConnectionLifecycle = z.infer<typeof GoogleDriveConnectionLifecycle>;
+
 export const GoogleDriveSelectedSource = z.object({
   id: z.string().min(1).max(256),
   name: z.string().min(1).max(1024),
@@ -93,6 +146,7 @@ export const GoogleDriveConnectionMetadata = z
     googleDisplayName: z.string().min(1).max(512).nullable(),
     verifiedAt: z.string().datetime({ offset: true }),
     accessMode: z.enum(["metadata_readonly", "readonly"]),
+    lifecycle: GoogleDriveConnectionLifecycle.optional(),
     selectedSources: z.array(GoogleDriveSelectedSource).max(100).optional(),
     /** @deprecated Read `selectedSources`; retained while existing connections migrate. */
     selectedSource: GoogleDriveSelectedSource.nullable().optional(),
@@ -111,6 +165,18 @@ export const GoogleDriveOAuthStartResponse = z.object({
 });
 export type GoogleDriveOAuthStartResponse = z.infer<typeof GoogleDriveOAuthStartResponse>;
 
+export const GoogleDriveLifecycleActionRequest = z.object({
+  action: z.enum(["pause", "resume"]),
+  expectedVersion: z.number().int().positive(),
+});
+export type GoogleDriveLifecycleActionRequest = z.infer<typeof GoogleDriveLifecycleActionRequest>;
+
+export const GoogleDriveDisconnectRequest = z.object({
+  expectedVersion: z.number().int().positive(),
+  idempotencyKey: z.string().trim().min(1).max(200),
+});
+export type GoogleDriveDisconnectRequest = z.infer<typeof GoogleDriveDisconnectRequest>;
+
 export const GoogleDriveBrowseItem = z.object({
   id: z.string().min(1).max(256),
   name: z.string().min(1).max(1024),

package/src/index.ts

@@ -2957,6 +2957,14 @@ export const FileResourceRef = z.object({
 });
 export type FileResourceRef = z.infer<typeof FileResourceRef>;
 
+/**
+ * Private durable metadata carried on user history items. It contains only
+ * stable file references, never file bytes, and is removed before model wire
+ * serialization. Keeping the references beside the message lets a later turn
+ * reconstruct the same typed attachment input after a model switch or retry.
+ */
+export const MODEL_ATTACHMENT_REFS_FIELD = "opengeni_attachment_refs" as const;
+
 export const ResourceRef = z.discriminatedUnion("kind", [RepositoryResourceRef, FileResourceRef]);
 export type ResourceRef = z.infer<typeof ResourceRef>;
 
@@ -3043,10 +3051,12 @@ export function defaultRepositoryMountPath(uri: string): string {
 }
 
 /** Resolve the exact mount used by API normalization, manifests, and clone hooks. */
+export const DEFAULT_FILE_RESOURCE_MOUNT_ROOT = ".opengeni/files" as const;
+
 export function resourceMountPath(resource: ResourceRef): string {
   if (resource.mountPath) return normalizeResourceMountPath(resource.mountPath);
   return resource.kind === "file"
-    ? normalizeResourceMountPath(`files/${resource.fileId}`)
+    ? normalizeResourceMountPath(`${DEFAULT_FILE_RESOURCE_MOUNT_ROOT}/${resource.fileId}`)
     : defaultRepositoryMountPath(resource.uri);
 }
 
@@ -3138,8 +3148,15 @@ export type KnowledgeSourceKind = z.infer<typeof KnowledgeSourceKind>;
 export const DocumentSearchMode = z.enum(["hybrid", "vector", "keyword"]);
 export type DocumentSearchMode = z.infer<typeof DocumentSearchMode>;
 
+// Durable document authority. Collections/bases are organizational metadata,
+// never an authorization boundary.
+export const DocumentAuthorityKind = z.enum(["organization", "workspace", "personal"]);
+export type DocumentAuthorityKind = z.infer<typeof DocumentAuthorityKind>;
+
 // 'workspace' documents are readable by anyone with workspace access;
 // 'private' documents are readable only by the grant subject that created them.
+// Retained as a compatibility projection over authorityKind:
+// personal -> private; organization/workspace -> workspace.
 export const DocumentVisibility = z.enum(["workspace", "private"]);
 export type DocumentVisibility = z.infer<typeof DocumentVisibility>;
 
@@ -3198,6 +3215,9 @@ export const Document = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  authorityKind: DocumentAuthorityKind,
+  authorityWorkspaceId: z.string().uuid().nullable(),
+  authoritySubjectId: z.string().nullable(),
   visibility: DocumentVisibility,
   createdBy: z.string().nullable(),
   agentAccess: z.boolean(),
@@ -3212,6 +3232,9 @@ export type Document = z.infer<typeof Document>;
 
 export const DocumentSearchResult = z.object({
   chunkId: z.string().uuid(),
+  // The workspace that ingested the document. Organization-authority results
+  // may originate in another workspace in the same account; this identifier
+  // is provenance and does not grant access to that workspace or its resources.
   workspaceId: z.string().uuid(),
   documentId: z.string().uuid(),
   baseId: z.string().uuid(),
@@ -3233,9 +3256,17 @@ export const DocumentSearchResult = z.object({
   sourceUpdatedAt: z.string().nullable(),
   sourceVersion: z.string().nullable(),
   aclTags: z.array(z.string()),
+  authorityKind: DocumentAuthorityKind,
+  authorityWorkspaceId: z.string().uuid().nullable(),
+  authoritySubjectId: z.string().nullable(),
 });
 export type DocumentSearchResult = z.infer<typeof DocumentSearchResult>;
 
+export const DocumentSearchResponse = z.object({
+  results: z.array(DocumentSearchResult),
+});
+export type DocumentSearchResponse = z.infer<typeof DocumentSearchResponse>;
+
 export const CreateDocumentBaseRequest = z.object({
   name: z.string().min(1),
   description: z.string().optional(),
@@ -3254,6 +3285,7 @@ export const AddDocumentRequest = z.object({
   sourceUpdatedAt: z.string().datetime({ offset: true }).optional(),
   sourceVersion: z.string().min(1).optional(),
   aclTags: z.array(z.string().min(1)).optional(),
+  authorityKind: DocumentAuthorityKind.optional(),
   visibility: DocumentVisibility.optional(),
   agentAccess: z.boolean().optional(),
 });
@@ -3270,6 +3302,7 @@ export const CreateKnowledgeDropRequest = z
     fileId: z.string().uuid().optional(),
     filename: z.string().min(1).optional(),
     title: z.string().min(1).optional(),
+    authorityKind: DocumentAuthorityKind.optional(),
     visibility: DocumentVisibility.optional(),
     agentAccess: z.boolean().optional(),
   })
@@ -8579,10 +8612,10 @@ export const HumanInputQuestion = z
     options: z.array(HumanInputOption).max(20).default([]),
     required: z.boolean().default(true),
     allowOther: z.boolean().default(false),
+    // Selection bounds only — agents invent useless text char mins/maxes.
+    // Answer strings stay platform-capped on HumanInputAnswer (~8192).
     validation: z
       .object({
-        minLength: z.number().int().nonnegative().max(8192).nullable().optional(),
-        maxLength: z.number().int().positive().max(8192).nullable().optional(),
         minSelections: z.number().int().nonnegative().max(20).nullable().optional(),
         maxSelections: z.number().int().positive().max(20).nullable().optional(),
       })
@@ -8621,17 +8654,6 @@ export const HumanInputQuestion = z
       });
     }
     const validation = question.validation;
-    if (
-      validation?.minLength != null &&
-      validation?.maxLength != null &&
-      validation.minLength > validation.maxLength
-    ) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["validation"],
-        message: "minLength exceeds maxLength",
-      });
-    }
     if (
       validation?.minSelections != null &&
       validation?.maxSelections != null &&
@@ -9507,6 +9529,7 @@ export const ModelCapabilitiesV1 = /* @__PURE__ */ defineModelContractSchema(()
       codeExecution: ModelCapabilityStateV1,
     }),
     inputModalities: z.array(z.enum(["text", "image", "audio"])),
+    inputFileMediaTypes: z.array(z.string()).optional(),
     outputModalities: z.array(z.enum(["text", "image", "audio"])),
     transports: z.object({
       sse: ModelCapabilityStateV1,

package/src/workspace-instruction-policies.ts

@@ -130,6 +130,7 @@ export type WorkspaceInstructionPolicyRevisionIdentity = z.infer<
 
 export const WorkspaceInstructionPolicyRevision = z.object({
   ...revisionIdentityShape,
+  operationId: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   ...targetShape,
@@ -212,6 +213,7 @@ export type ResolvedWorkspaceInstructionPolicySnapshot = z.infer<
 
 export const WorkspaceInstructionPolicyActivationEvent = z.object({
   id: z.string().uuid(),
+  operationId: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   ...targetShape,
@@ -229,6 +231,7 @@ export type WorkspaceInstructionPolicyActivationEvent = z.infer<
 
 export const CreateWorkspaceInstructionPolicyDraftRequest = z
   .object({
+    operationId: z.string().uuid().optional(),
     kind: WorkspaceInstructionPolicyKind,
     scope: WorkspaceInstructionPolicyScope,
     roleKey: WorkspaceInstructionPolicyRoleKeyInput.nullable().default(null),
@@ -253,6 +256,7 @@ export type CreateWorkspaceInstructionPolicyDraftRequest = z.infer<
 
 export const ImportLegacyWorkspaceInstructionPolicyDraftRequest = z
   .object({
+    operationId: z.string().uuid().optional(),
     supersedesRevisionId: z.string().uuid().nullable().default(null),
   })
   .strict();
@@ -305,7 +309,9 @@ export type WorkspaceInstructionPolicyDiffResponse = z.infer<
 >;
 
 export const ActivateWorkspaceInstructionPolicyRequest = z.object({
+  operationId: z.string().uuid().optional(),
   expectedCurrentRevisionId: z.string().uuid().nullable(),
+  expectedActivationVersion: z.number().int().nonnegative().optional(),
   reason: z.string().trim().min(1).max(WORKSPACE_INSTRUCTION_POLICY_REASON_MAX_CHARS),
 });
 export type ActivateWorkspaceInstructionPolicyRequest = z.infer<
@@ -313,8 +319,10 @@ export type ActivateWorkspaceInstructionPolicyRequest = z.infer<
 >;
 
 export const RollbackWorkspaceInstructionPolicyRequest = z.object({
+  operationId: z.string().uuid().optional(),
   targetRevisionId: z.string().uuid(),
   expectedCurrentRevisionId: z.string().uuid(),
+  expectedActivationVersion: z.number().int().positive().optional(),
   reason: z.string().trim().min(1).max(WORKSPACE_INSTRUCTION_POLICY_REASON_MAX_CHARS),
 });
 export type RollbackWorkspaceInstructionPolicyRequest = z.infer<
@@ -337,3 +345,11 @@ export const WorkspaceInstructionPolicyConflictResponse = z.object({
 export type WorkspaceInstructionPolicyConflictResponse = z.infer<
   typeof WorkspaceInstructionPolicyConflictResponse
 >;
+
+export const WorkspaceInstructionPolicyOperationReuseResponse = z.object({
+  code: z.literal("WORKSPACE_INSTRUCTION_POLICY_OPERATION_REUSED"),
+  message: z.string(),
+});
+export type WorkspaceInstructionPolicyOperationReuseResponse = z.infer<
+  typeof WorkspaceInstructionPolicyOperationReuseResponse
+>;

package/src/workspace-state.ts

@@ -4,7 +4,9 @@ import {
   WorkspaceInstructionPolicyKind,
   WorkspaceInstructionPolicyProvenanceSource,
   WorkspaceInstructionPolicyRoleKey,
+  WorkspaceInstructionPolicyRoleSource,
   WorkspaceInstructionPolicyScope,
+  WorkspaceInstructionPolicySnapshotEntry,
 } from "./workspace-instruction-policies";
 
 export const WORKSPACE_STATE_MAX_ACTIVE_POLICY_HEADS = 32;
@@ -17,6 +19,9 @@ export const WORKSPACE_STATE_MEMORY_SAMPLE_LIMIT = 100;
 
 const Count = z.number().int().nonnegative();
 
+export const WorkspaceStateQuery = z.object({ attemptId: z.string().uuid().optional() }).strict();
+export type WorkspaceStateQuery = z.infer<typeof WorkspaceStateQuery>;
+
 export const WorkspaceStateDocumentStatusCounts = z
   .object({
     queued: Count,
@@ -196,6 +201,112 @@ export const WorkspaceStateKnowledge = z.discriminatedUnion("availability", [
 ]);
 export type WorkspaceStateKnowledge = z.infer<typeof WorkspaceStateKnowledge>;
 
+export const WorkspaceStateGovernanceDriftStatus = z.enum([
+  "identical",
+  "changed",
+  "superseded",
+  "missing",
+  "unavailable",
+  "truncated",
+]);
+export type WorkspaceStateGovernanceDriftStatus = z.infer<
+  typeof WorkspaceStateGovernanceDriftStatus
+>;
+
+const WorkspaceStatePolicySnapshotAvailable = z
+  .object({
+    status: z.literal("available"),
+    id: z.string().uuid(),
+    createdAt: z.string().datetime(),
+    entryHash: z.string().regex(/^[0-9a-f]{64}$/),
+    policyRole: WorkspaceInstructionPolicyRoleKey.nullable(),
+    roleSource: WorkspaceInstructionPolicyRoleSource,
+    entries: z.array(WorkspaceInstructionPolicySnapshotEntry).max(3),
+  })
+  .strict();
+
+const WorkspaceStatePolicySnapshotMissing = z.object({ status: z.literal("missing") }).strict();
+
+const WorkspaceStatePreferenceSnapshotAvailable = z
+  .object({
+    status: z.literal("available"),
+    id: z.string().uuid(),
+    createdAt: z.string().datetime(),
+    descriptorHash: z.string().regex(/^[0-9a-f]{64}$/),
+    descriptorCount: Count.max(64),
+    truncated: z.boolean(),
+  })
+  .strict();
+
+const WorkspaceStatePreferenceSnapshotMissing = z.object({ status: z.literal("missing") }).strict();
+
+const WorkspaceStateGovernanceDrift = z
+  .object({
+    overall: WorkspaceStateGovernanceDriftStatus,
+    policy: z
+      .object({
+        status: WorkspaceStateGovernanceDriftStatus,
+        snapshotHash: z
+          .string()
+          .regex(/^[0-9a-f]{64}$/)
+          .nullable(),
+        currentHash: z
+          .string()
+          .regex(/^[0-9a-f]{64}$/)
+          .nullable(),
+        snapshotTargetCount: Count,
+        currentTargetCount: Count,
+      })
+      .strict(),
+    preferences: z
+      .object({
+        status: WorkspaceStateGovernanceDriftStatus,
+        snapshotHash: z
+          .string()
+          .regex(/^[0-9a-f]{64}$/)
+          .nullable(),
+        currentHash: z
+          .string()
+          .regex(/^[0-9a-f]{64}$/)
+          .nullable(),
+        snapshotDescriptorCount: Count,
+        currentDescriptorCount: Count,
+        snapshotTruncated: z.boolean(),
+        currentTruncated: z.boolean(),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const WorkspaceStateAttemptGovernance = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("not_requested") }).strict(),
+  z
+    .object({
+      status: z.literal("unavailable"),
+      reason: z.literal("attempt_not_found_or_not_authorized"),
+      driftStatus: z.literal("unavailable"),
+    })
+    .strict(),
+  z
+    .object({
+      status: z.literal("available"),
+      attemptId: z.string().uuid(),
+      executionGeneration: z.number().int().positive(),
+      acceptedAt: z.string().datetime(),
+      policySnapshot: z.discriminatedUnion("status", [
+        WorkspaceStatePolicySnapshotAvailable,
+        WorkspaceStatePolicySnapshotMissing,
+      ]),
+      preferenceSnapshot: z.discriminatedUnion("status", [
+        WorkspaceStatePreferenceSnapshotAvailable,
+        WorkspaceStatePreferenceSnapshotMissing,
+      ]),
+      drift: WorkspaceStateGovernanceDrift,
+    })
+    .strict(),
+]);
+export type WorkspaceStateAttemptGovernance = z.infer<typeof WorkspaceStateAttemptGovernance>;
+
 export const WorkspaceStateResponse = z
   .object({
     workspaceId: z.string().uuid(),
@@ -208,12 +319,7 @@ export const WorkspaceStateResponse = z
             capturedAt: z.string().datetime(),
           })
           .strict(),
-        policySnapshot: z
-          .object({
-            status: z.literal("not_captured"),
-            reason: z.literal("workspace_instruction_policy_snapshot_not_implemented"),
-          })
-          .strict(),
+        attemptGovernance: WorkspaceStateAttemptGovernance,
       })
       .strict(),
     policy: WorkspaceStatePolicy,