@opengeni/contracts 0.32.0 → 0.36.0

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

@@ -5,6 +5,7 @@ export const WORKSPACE_INSTRUCTION_POLICY_PROMPT_MAX_UTF8_BYTES = 131_072;
 export const WORKSPACE_INSTRUCTION_POLICY_REASON_MAX_CHARS = 4_096;
 export const WORKSPACE_INSTRUCTION_POLICY_ROLE_KEY_MAX_CHARS = 64;
 export const WORKSPACE_INSTRUCTION_POLICY_SOURCE_ID_MAX_CHARS = 512;
+export const WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_SOURCE_VERSION_MAX_CHARS = 256;
 
 export const WorkspaceInstructionPolicyKind = z.enum(["charter", "policy"]);
 export type WorkspaceInstructionPolicyKind = z.infer<typeof WorkspaceInstructionPolicyKind>;
@@ -130,6 +131,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 +214,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 +232,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 +257,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 +310,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 +320,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 +346,108 @@ 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
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalSource = z.object({
+  id: z.string().min(1).max(WORKSPACE_INSTRUCTION_POLICY_SOURCE_ID_MAX_CHARS),
+  version: z.string().min(1).max(WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_SOURCE_VERSION_MAX_CHARS),
+  confidenceBps: z.number().int().min(0).max(10_000),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalSource = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalSource
+>;
+
+export const CreateWorkspaceInstructionPolicyOnboardingProposalRequest = z
+  .object({
+    operationId: z.string().uuid().optional(),
+    kind: WorkspaceInstructionPolicyKind,
+    scope: WorkspaceInstructionPolicyScope,
+    roleKey: WorkspaceInstructionPolicyRoleKeyInput.nullable().default(null),
+    // Content bounds are enforced by the domain layer so empty and oversized
+    // proposals retain their typed API outcomes instead of collapsing into a
+    // generic request-shape error.
+    content: z.string(),
+    sourceId: z.string().trim().min(1).max(WORKSPACE_INSTRUCTION_POLICY_SOURCE_ID_MAX_CHARS),
+    sourceVersion: z
+      .string()
+      .trim()
+      .min(1)
+      .max(WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_SOURCE_VERSION_MAX_CHARS),
+    confidenceBps: z.number().int().min(0).max(10_000),
+    expectedCurrentRevisionId: z.string().uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+  })
+  .superRefine(validateTarget);
+export type CreateWorkspaceInstructionPolicyOnboardingProposalRequest = z.infer<
+  typeof CreateWorkspaceInstructionPolicyOnboardingProposalRequest
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposal = z.object({
+  id: z.string().uuid(),
+  operationId: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  ...targetShape,
+  source: WorkspaceInstructionPolicyOnboardingProposalSource,
+  baseline: WorkspaceInstructionPolicyHead.nullable(),
+  draft: WorkspaceInstructionPolicyRevision,
+  status: z.literal("proposed"),
+  createdBySubjectId: z.string().min(1),
+  createdAt: z.string().datetime(),
+});
+export type WorkspaceInstructionPolicyOnboardingProposal = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposal
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalListQuery = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalListQuery = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalListQuery
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalListResponse = z.object({
+  proposals: z.array(WorkspaceInstructionPolicyOnboardingProposal),
+  truncated: z.boolean(),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalListResponse = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalListResponse
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse = z.object({
+  code: z.enum([
+    "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_EMPTY",
+    "WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_OVERSIZED",
+  ]),
+  message: z.string(),
+  maxChars: z.number().int().positive(),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalContentErrorResponse
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalStaleResponse = z.object({
+  code: z.literal("WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_STALE"),
+  message: z.string(),
+  currentHead: WorkspaceInstructionPolicyHead.nullable(),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalStaleResponse = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalStaleResponse
+>;
+
+export const WorkspaceInstructionPolicyOnboardingProposalConflictResponse = z.object({
+  code: z.literal("WORKSPACE_INSTRUCTION_POLICY_ONBOARDING_PROPOSAL_CONFLICT"),
+  message: z.string(),
+  existingProposalId: z.string().uuid(),
+  existingDraftRevisionId: z.string().uuid(),
+});
+export type WorkspaceInstructionPolicyOnboardingProposalConflictResponse = z.infer<
+  typeof WorkspaceInstructionPolicyOnboardingProposalConflictResponse
+>;

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,