@opengeni/contracts 1.0.1 → 2.3.0-canary.0

package/src/personal-github.ts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+
+import { ConnectionMetadata } from "./index";
+
+export const PERSONAL_GITHUB_PROVIDER_DOMAIN = "github.com" as const;
+export const PERSONAL_GITHUB_PROVIDER_FAMILY = "github" as const;
+export const PERSONAL_GITHUB_CREDENTIAL_ROLE = "opengeni_github_personal" as const;
+export const PERSONAL_GITHUB_CONNECTION_SURFACE_ID = "github:personal" as const;
+export const PERSONAL_GITHUB_REQUESTED_SCOPES = ["repo"] as const;
+export const PERSONAL_GITHUB_AUTHORIZATION_URL =
+  "https://github.com/login/oauth/authorize" as const;
+export const PERSONAL_GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token" as const;
+export const PERSONAL_GITHUB_USER_URL = "https://api.github.com/user" as const;
+export const PERSONAL_GITHUB_API_ORIGIN = "https://api.github.com" as const;
+export const PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX = 100 as const;
+
+export const PersonalGitHubRepositoryId = z.string().regex(/^[1-9]\d*$/u);
+export type PersonalGitHubRepositoryId = z.infer<typeof PersonalGitHubRepositoryId>;
+
+export const PersonalGitHubRepositoryAccess = z.enum(["read", "write"]);
+export type PersonalGitHubRepositoryAccess = z.infer<typeof PersonalGitHubRepositoryAccess>;
+
+export const PersonalGitHubRepositoryPermissions = z
+  .object({
+    pull: z.boolean(),
+    push: z.boolean(),
+    admin: z.boolean(),
+    maintain: z.boolean(),
+    triage: z.boolean(),
+  })
+  .strict();
+export type PersonalGitHubRepositoryPermissions = z.infer<
+  typeof PersonalGitHubRepositoryPermissions
+>;
+
+export const PersonalGitHubRepositoryVisibility = z.enum(["public", "private", "internal"]);
+export type PersonalGitHubRepositoryVisibility = z.infer<typeof PersonalGitHubRepositoryVisibility>;
+
+const PersonalGitHubRepositoryFullName = z
+  .string()
+  .min(3)
+  .max(140)
+  .regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9_.-]{1,100}$/u);
+
+export function canonicalPersonalGitHubRepositoryUrl(fullName: string): string {
+  return `https://github.com/${fullName}`;
+}
+
+/** A bounded, credential-free projection verified directly against GitHub. */
+export const PersonalGitHubRepository = z
+  .object({
+    repositoryId: PersonalGitHubRepositoryId,
+    fullName: PersonalGitHubRepositoryFullName,
+    canonicalUrl: z.string().url().max(512),
+    defaultBranch: z.string().min(1).max(255),
+    visibility: PersonalGitHubRepositoryVisibility,
+    private: z.boolean(),
+    archived: z.boolean(),
+    disabled: z.boolean(),
+    permissions: PersonalGitHubRepositoryPermissions,
+  })
+  .strict()
+  .superRefine((repository, context) => {
+    if (repository.canonicalUrl !== canonicalPersonalGitHubRepositoryUrl(repository.fullName)) {
+      context.addIssue({
+        code: "custom",
+        path: ["canonicalUrl"],
+        message: "canonicalUrl must be derived from fullName",
+      });
+    }
+    if (repository.private !== (repository.visibility === "private")) {
+      context.addIssue({
+        code: "custom",
+        path: ["private"],
+        message: "private must agree with visibility",
+      });
+    }
+  });
+export type PersonalGitHubRepository = z.infer<typeof PersonalGitHubRepository>;
+
+export const PersonalGitHubSelectedRepository = PersonalGitHubRepository.safeExtend({
+  selectedAccess: PersonalGitHubRepositoryAccess,
+  selectionGeneration: z.number().int().positive(),
+  selectedAt: z.string().datetime({ offset: true }),
+  lastVerifiedAt: z.string().datetime({ offset: true }),
+}).strict();
+export type PersonalGitHubSelectedRepository = z.infer<typeof PersonalGitHubSelectedRepository>;
+
+export const PersonalGitHubRepositorySelectionState = z
+  .object({
+    connectionAuthorityGeneration: z.number().int().positive(),
+    credentialBindingId: z.string().uuid(),
+    providerPrincipalId: PersonalGitHubRepositoryId,
+    selectionGeneration: z.number().int().nonnegative(),
+    repositories: z
+      .array(PersonalGitHubSelectedRepository)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+  })
+  .strict();
+export type PersonalGitHubRepositorySelectionState = z.infer<
+  typeof PersonalGitHubRepositorySelectionState
+>;
+
+export const ListPersonalGitHubRepositoriesQuery = z
+  .object({
+    cursor: z.coerce.number().int().positive().max(10_000).default(1),
+    limit: z.coerce.number().int().min(1).max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX).default(50),
+  })
+  .strict();
+export type ListPersonalGitHubRepositoriesQuery = z.infer<
+  typeof ListPersonalGitHubRepositoriesQuery
+>;
+
+export const PersonalGitHubRepositoryCatalogItem = PersonalGitHubRepository.safeExtend({
+  selectedAccess: PersonalGitHubRepositoryAccess.nullable(),
+}).strict();
+export type PersonalGitHubRepositoryCatalogItem = z.infer<
+  typeof PersonalGitHubRepositoryCatalogItem
+>;
+
+export const ListPersonalGitHubRepositoriesResponse = z
+  .object({
+    repositories: z
+      .array(PersonalGitHubRepositoryCatalogItem)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+    nextCursor: z.number().int().positive().nullable(),
+    selection: PersonalGitHubRepositorySelectionState,
+  })
+  .strict();
+export type ListPersonalGitHubRepositoriesResponse = z.infer<
+  typeof ListPersonalGitHubRepositoriesResponse
+>;
+
+export const PersonalGitHubRepositorySelectionInput = z
+  .object({
+    repositoryId: PersonalGitHubRepositoryId,
+    fullName: PersonalGitHubRepositoryFullName,
+    access: PersonalGitHubRepositoryAccess,
+  })
+  .strict();
+export type PersonalGitHubRepositorySelectionInput = z.infer<
+  typeof PersonalGitHubRepositorySelectionInput
+>;
+
+export const ReplacePersonalGitHubRepositorySelectionsRequest = z
+  .object({
+    expectedConnectionAuthorityGeneration: z.number().int().positive(),
+    expectedSelectionGeneration: z.number().int().nonnegative(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+    repositories: z
+      .array(PersonalGitHubRepositorySelectionInput)
+      .max(PERSONAL_GITHUB_REPOSITORY_CATALOG_MAX),
+  })
+  .strict()
+  .superRefine((request, context) => {
+    const repositoryIds = new Set<string>();
+    const fullNames = new Set<string>();
+    request.repositories.forEach((repository, index) => {
+      const normalizedFullName = repository.fullName.toLowerCase();
+      if (repositoryIds.has(repository.repositoryId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["repositories", index, "repositoryId"],
+          message: "repositoryId must be unique",
+        });
+      }
+      if (fullNames.has(normalizedFullName)) {
+        context.addIssue({
+          code: "custom",
+          path: ["repositories", index, "fullName"],
+          message: "fullName must be unique",
+        });
+      }
+      repositoryIds.add(repository.repositoryId);
+      fullNames.add(normalizedFullName);
+    });
+  });
+export type ReplacePersonalGitHubRepositorySelectionsRequest = z.infer<
+  typeof ReplacePersonalGitHubRepositorySelectionsRequest
+>;
+
+export const VerifyPersonalGitHubRepositorySelectionsRequest = z
+  .object({
+    expectedConnectionAuthorityGeneration: z.number().int().positive(),
+    expectedSelectionGeneration: z.number().int().nonnegative(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .strict();
+export type VerifyPersonalGitHubRepositorySelectionsRequest = z.infer<
+  typeof VerifyPersonalGitHubRepositorySelectionsRequest
+>;
+
+/**
+ * Owner-visible, credential-free metadata for one dedicated personal GitHub
+ * OAuth connection. Repository selections are a separate authority and never
+ * live in this credential record.
+ */
+export const PersonalGitHubConnectionMetadata = z
+  .object({
+    credentialRole: z.literal(PERSONAL_GITHUB_CREDENTIAL_ROLE),
+    providerFamily: z.literal(PERSONAL_GITHUB_PROVIDER_FAMILY),
+    providerPrincipalId: z.string().regex(/^\d+$/u),
+    githubUserId: z.string().regex(/^\d+$/u),
+    githubLogin: z.string().min(1).max(100),
+    oauthEnvironment: z.string().min(1).max(128),
+    oauthClientMarker: z.string().regex(/^[a-f0-9]{32}$/u),
+    credentialBindingId: z.string().uuid(),
+    connectedAt: z.string().datetime({ offset: true }),
+    lastVerifiedAt: z.string().datetime({ offset: true }),
+    disconnectedAt: z.string().datetime({ offset: true }).nullable().optional(),
+    refreshTokenExpiresAt: z.string().datetime({ offset: true }).nullable().optional(),
+  })
+  .passthrough();
+export type PersonalGitHubConnectionMetadata = z.infer<typeof PersonalGitHubConnectionMetadata>;
+
+export const PersonalGitHubOAuthStartRequest = z
+  .object({
+    /** Existing exact connection generation to re-authorize in place. */
+    connectionId: z.string().uuid().optional(),
+    /** Same-workspace UI path restored after the callback. */
+    returnPath: z.string().min(1).max(2048).optional(),
+  })
+  .strict();
+export type PersonalGitHubOAuthStartRequest = z.infer<typeof PersonalGitHubOAuthStartRequest>;
+
+export const PersonalGitHubOAuthStartResponse = z
+  .object({
+    authorizationUrl: z.string().url(),
+    expiresAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+export type PersonalGitHubOAuthStartResponse = z.infer<typeof PersonalGitHubOAuthStartResponse>;
+
+export const PersonalGitHubConnectionStatusResponse = z
+  .object({
+    enabled: z.boolean(),
+    connection: ConnectionMetadata.nullable(),
+    reviewUrl: z.string().url().nullable(),
+  })
+  .strict();
+export type PersonalGitHubConnectionStatusResponse = z.infer<
+  typeof PersonalGitHubConnectionStatusResponse
+>;
+
+export const PersonalGitHubDisconnectRequest = z
+  .object({
+    expectedVersion: z.number().int().positive(),
+    idempotencyKey: z.string().trim().min(1).max(200),
+  })
+  .strict();
+export type PersonalGitHubDisconnectRequest = z.infer<typeof PersonalGitHubDisconnectRequest>;
+
+export function isPersonalGitHubConnection(
+  connection: Pick<z.infer<typeof ConnectionMetadata>, "providerDomain" | "kind" | "metadata">,
+): boolean {
+  return (
+    connection.providerDomain.toLowerCase() === PERSONAL_GITHUB_PROVIDER_DOMAIN &&
+    connection.kind === "oauth2" &&
+    PersonalGitHubConnectionMetadata.safeParse(connection.metadata).success
+  );
+}
+
+export function hasReservedPersonalGitHubMetadata(
+  metadata: Record<string, unknown> | undefined,
+): boolean {
+  return metadata?.credentialRole === PERSONAL_GITHUB_CREDENTIAL_ROLE;
+}

package/src/preference-registry.ts

@@ -174,6 +174,11 @@ export const PreferenceRegistryEvent = z.object({
 });
 export type PreferenceRegistryEvent = z.infer<typeof PreferenceRegistryEvent>;
 
+export const PreferenceRegistryActivationAuthority = z.enum(["human_confirmed", "automatic"]);
+export type PreferenceRegistryActivationAuthority = z.infer<
+  typeof PreferenceRegistryActivationAuthority
+>;
+
 export const PreferenceRegistryDescriptor = z.object({
   id: z.string().uuid(),
   stableKey: PreferenceRegistryStableKey,
@@ -185,6 +190,18 @@ export const PreferenceRegistryDescriptor = z.object({
   contentHash: hash,
   precedence: PreferenceRegistryPrecedence,
   provenance: PreferenceRegistryDescriptorProvenance,
+  // How the active revision became active, derived from the governed-learning
+  // activation receipt rather than stored on the revision. `provenance.trust`
+  // stays the frozen creation-time fact - a revision proposed by an agent is
+  // `untrusted_proposal` forever, which is correct and immutable - while this
+  // says whether a human explicitly confirmed the activation or policy
+  // activated it automatically. Null when the revision became active outside
+  // governed learning, so no receipt describes it.
+  // Defaulted, not merely nullable: snapshots written before this field
+  // existed are immutable and their stored JSON simply has no answer. Parsing
+  // those as null is the truthful reading, and it keeps their pinned
+  // descriptor hash valid because the stored text is untouched.
+  activationAuthority: PreferenceRegistryActivationAuthority.nullable().default(null),
   expiresAt: z.string().datetime().nullable(),
   retrievalHandle: z.string().min(1).max(512),
 });

package/src/remember.ts

@@ -0,0 +1,242 @@
+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 {
+  CompanyBrainLearningDecisionSummary,
+  CompanyBrainLearningStepFailure,
+} from "./company-brain-governed-writes";
+import { GovernedLearningActivationDestination } from "./governed-learning-activation";
+import { HumanInputQuestion } from "./index";
+import {
+  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
+  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
+  PreferenceRegistryStableKey,
+} from "./preference-registry";
+import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-policies";
+
+/**
+ * Explicit user-directed durable write ("remember X for this workspace").
+ *
+ * The lane is the Company Brain area the content belongs to:
+ * - `preference`: a Ways-of-working preference (how agents should act);
+ * - `instruction_policy`: a mandatory workspace rule ("always"/"never");
+ * - `knowledge`: a company/product/people fact.
+ *
+ * v1 supports the workspace scope only. Personal and organization scopes are
+ * separate authorities that are not yet active for governed writes.
+ */
+export const RememberLane = z.enum(["preference", "instruction_policy", "knowledge"]);
+export type RememberLane = z.infer<typeof RememberLane>;
+
+export const RememberScope = z.enum(["workspace"]);
+export type RememberScope = z.infer<typeof RememberScope>;
+
+/**
+ * Ceiling for the Knowledge lane, which is retrieval evidence rather than
+ * always-composed prompt text. The prompt-composed lanes are bounded far more
+ * tightly: see `AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS` and
+ * `AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS`.
+ */
+export const REMEMBER_CONTENT_MAX_CHARS = 4_000;
+
+const rememberBase = {
+  operationId: z.string().uuid(),
+  scope: RememberScope.default("workspace"),
+  /** The exact user-directed content to remember, in the user's words. */
+  content: z.string().trim().min(1).max(REMEMBER_CONTENT_MAX_CHARS),
+  /** Why the agent believes the user asked for this to be remembered. */
+  reason: z.string().trim().min(1).max(4_096),
+};
+
+export const RememberRequest = z.discriminatedUnion("lane", [
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("preference"),
+      // Only the short title/description descriptors are prompt-composed; the
+      // content is retrieved on demand, so this length is retrieval cost rather
+      // than standing prompt cost, and gets more room than a rule rather than
+      // less.
+      content: z
+        .string()
+        .trim()
+        .min(1)
+        .max(
+          AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+          AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+        ),
+      stableKey: PreferenceRegistryStableKey,
+      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),
+    })
+    .strict(),
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("instruction_policy"),
+      // A mandatory rule is composed verbatim into the prompt of every session
+      // it applies to, for as long as it stays active, so this is the tightest
+      // agent budget in the Company Brain.
+      content: z
+        .string()
+        .trim()
+        .min(1)
+        .max(
+          AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+          AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+        ),
+      target: WorkspaceInstructionPolicyTarget.default({
+        kind: "policy",
+        scope: "global",
+        roleKey: null,
+      }),
+    })
+    .strict(),
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("knowledge"),
+      /** Short entity label the fact is about (company, product, person, team, ...). */
+      subject: z.string().trim().min(1).max(512),
+    })
+    .strict(),
+]);
+export type RememberRequest = z.infer<typeof RememberRequest>;
+
+/**
+ * Bound structured human-input question that authorizes a confirmed remember.
+ * The question id binds the exact confirmation target: the
+ * `knowledge_change_proposals` id for Ways-of-working lanes, or the
+ * `knowledge_claims` id for the Knowledge lane.
+ */
+export const REMEMBER_HUMAN_INPUT_SAVE_OPTION = "save" as const;
+export const REMEMBER_HUMAN_INPUT_SKIP_OPTION = "skip" as const;
+export function rememberHumanInputQuestionId(targetId: string): string {
+  return `remember:${targetId}`;
+}
+
+// z.lazy: this module is re-exported from ./index, so resolve the question
+// schema at parse time instead of at import time.
+export const RememberHumanInputPrompt = z.object({
+  questions: z.array(z.lazy(() => HumanInputQuestion)).length(1),
+  allowSkip: z.literal(false),
+});
+export type RememberHumanInputPrompt = z.infer<typeof RememberHumanInputPrompt>;
+
+export const RememberActivationSummary = z.discriminatedUnion("destination", [
+  z.object({
+    destination: GovernedLearningActivationDestination,
+    receiptId: z.string().uuid(),
+    destinationRevisionId: z.string().uuid().nullable(),
+    effectiveAt: z.string().datetime().nullable(),
+    authorityKind: z.enum(["automatic", "human_confirmed"]),
+    /** The `/learning` API/SDK history exposes exact undo for this receipt. */
+    undo: z.literal("learning_history"),
+  }),
+  z.object({
+    destination: z.literal("knowledge"),
+    receiptId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    approvalReviewId: z.string().uuid(),
+    effectiveAt: z.string().datetime().nullable(),
+    authorityKind: z.literal("human_confirmed"),
+    /** Knowledge approvals are undone through the Knowledge review lifecycle (`knowledge_correct` or a human revocation). */
+    undo: z.literal("knowledge_review"),
+  }),
+]);
+export type RememberActivationSummary = z.infer<typeof RememberActivationSummary>;
+
+export const RememberReceipt = z.discriminatedUnion("status", [
+  /** Learning policy is off for this source: nothing durable was written. */
+  z.object({
+    status: z.literal("blocked"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    reason: z.literal("learning_policy_off"),
+  }),
+  /** Kept for callers that still expect review-only Knowledge; not returned by `remember` today. */
+  z.object({
+    status: z.literal("proposed_for_review"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    evidenceId: z.string().uuid(),
+    reviewId: z.string().uuid().nullable(),
+  }),
+  /** Activated immediately (automatic policy) through the destination lifecycle. */
+  z.object({
+    status: z.literal("activated"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    proposalId: z.string().uuid(),
+    learning: CompanyBrainLearningDecisionSummary.nullable(),
+    activation: RememberActivationSummary,
+  }),
+  /**
+   * The proposal is durable but the workspace policy will not activate it on
+   * its own. The agent must ask the human exactly this question through the
+   * built-in `request_human_input` tool, then call `remember_confirm` with the
+   * returned request id.
+   */
+  z.object({
+    status: z.literal("confirmation_required"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    /** Ways-of-working lanes confirm a change proposal; Knowledge confirms the claim. */
+    proposalId: z.string().uuid().nullable(),
+    claimId: z.string().uuid(),
+    learning: CompanyBrainLearningDecisionSummary.nullable(),
+    learningFailure: CompanyBrainLearningStepFailure.nullable(),
+    humanInput: RememberHumanInputPrompt,
+    confirmWith: z.literal("remember_confirm"),
+  }),
+]);
+export type RememberReceipt = z.infer<typeof RememberReceipt>;
+
+export const RememberConfirmRequest = z.discriminatedUnion("target", [
+  z
+    .object({
+      target: z.literal("proposal"),
+      operationId: z.string().uuid(),
+      proposalId: z.string().uuid(),
+      /** `learning.receiptId` from the `confirmation_required` remember receipt. */
+      decisionReceiptId: z.string().uuid(),
+      /** The `requestId` returned by `request_human_input`. */
+      humanInputRequestId: z.string().uuid(),
+    })
+    .strict(),
+  z
+    .object({
+      target: z.literal("knowledge_claim"),
+      operationId: z.string().uuid(),
+      claimId: z.string().uuid(),
+      humanInputRequestId: z.string().uuid(),
+    })
+    .strict(),
+]);
+export type RememberConfirmRequest = z.infer<typeof RememberConfirmRequest>;
+
+export const RememberConfirmReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  proposalId: z.string().uuid().nullable(),
+  claimId: z.string().uuid(),
+  decisionReceiptId: z.string().uuid().nullable(),
+  activation: RememberActivationSummary,
+});
+export type RememberConfirmReceipt = z.infer<typeof RememberConfirmReceipt>;

package/src/sandbox-file-artifacts.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+import { RetainedArtifactReferenceSchema } from "./retained-output";
+
+/**
+ * Channel-A currently returns one bounded binary-safe read. Keep publication
+ * below that ceiling so an extra sentinel byte can distinguish an exact file
+ * from a truncated prefix.
+ */
+export const SANDBOX_FILE_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024 - 1;
+
+export const PublishSandboxFileArtifactRequest = z
+  .object({
+    path: z.string().min(1).max(4_096),
+  })
+  .strict();
+export type PublishSandboxFileArtifactRequest = z.infer<typeof PublishSandboxFileArtifactRequest>;
+
+/**
+ * Closed model/UI receipt for one exact sandbox-file publication. Storage
+ * locators and signed URLs never cross this boundary.
+ */
+export const SandboxFileArtifactReceipt = z
+  .object({
+    type: z.literal("sandbox_file"),
+    sandboxPath: z.string().min(1).max(4_096),
+    filename: z.string().min(1).max(1_024),
+    artifact: RetainedArtifactReferenceSchema,
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const pathSegments = value.sandboxPath.split("/");
+    if (
+      !value.sandboxPath.startsWith("/workspace/") ||
+      value.sandboxPath.includes("\0") ||
+      pathSegments.some(
+        (segment, index) => index > 1 && (!segment || segment === "." || segment === ".."),
+      ) ||
+      pathSegments.at(-1) !== value.filename
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["sandboxPath"],
+        message: "sandbox path must canonically identify the published filename in /workspace",
+      });
+    }
+    if (value.artifact.kind !== "file" || value.artifact.retention.policy !== "workspace_file") {
+      context.addIssue({
+        code: "custom",
+        path: ["artifact"],
+        message: "sandbox files require a permanent workspace-file artifact",
+      });
+    }
+    if (
+      value.artifact.originalBytes < 1 ||
+      value.artifact.originalBytes > SANDBOX_FILE_ARTIFACT_MAX_BYTES
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["artifact", "originalBytes"],
+        message: "sandbox file size is outside the publication byte limit",
+      });
+    }
+  });
+export type SandboxFileArtifactReceipt = z.infer<typeof SandboxFileArtifactReceipt>;

package/src/sandbox-snapshots.ts

@@ -52,6 +52,84 @@ export type NativeSnapshotDescriptor = {
 
 export type WorkspaceArchiveDescriptor = TarWorkspaceArchiveDescriptor | NativeSnapshotDescriptor;
 
+export const WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA = "sandbox_archive_object_v1" as const;
+
+/** Compact object-storage locator for portable tar bytes. The SHA-256/size in
+ * `workspaceArchiveMeta` remain the verification authority. */
+export type WorkspaceArchiveObjectRef = {
+  schema: typeof WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA;
+  key: string;
+  sha256: string;
+  bytes: number;
+  backend: string;
+};
+
+const OBJECT_KEY =
+  /^sandbox-archives\/v1\/[0-9a-f-]{36}\/[0-9a-f-]{36}\/[0-9a-f-]{36}\/wa1:[0-9]{13}:[0-9a-f]{64}\.tar$/i;
+
+export function parseWorkspaceArchiveObjectRef(value: unknown): WorkspaceArchiveObjectRef | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const candidate = value as Partial<WorkspaceArchiveObjectRef>;
+  if (
+    candidate.schema !== WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA ||
+    typeof candidate.key !== "string" ||
+    !OBJECT_KEY.test(candidate.key) ||
+    typeof candidate.sha256 !== "string" ||
+    !SHA256.test(candidate.sha256) ||
+    !nonnegativeInteger(candidate.bytes) ||
+    candidate.bytes <= 0 ||
+    typeof candidate.backend !== "string" ||
+    candidate.backend.length === 0 ||
+    candidate.backend.length > 64
+  ) {
+    return null;
+  }
+  return {
+    schema: WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA,
+    key: candidate.key,
+    sha256: candidate.sha256,
+    bytes: candidate.bytes,
+    backend: candidate.backend,
+  };
+}
+
+export function workspaceArchiveObjectKey(input: {
+  accountId: string;
+  workspaceId: string;
+  sandboxGroupId: string;
+  revision: string;
+}): string {
+  return `sandbox-archives/v1/${input.accountId}/${input.workspaceId}/${input.sandboxGroupId}/${input.revision}.tar`;
+}
+
+export function workspaceArchivePayloadPresent(
+  sessionState: Record<string, unknown> | null | undefined,
+): boolean {
+  if (!sessionState) return false;
+  if (
+    typeof sessionState.workspaceArchive === "string" &&
+    sessionState.workspaceArchive.length > 0
+  ) {
+    return true;
+  }
+  return parseWorkspaceArchiveObjectRef(sessionState.workspaceArchiveRef) !== null;
+}
+
+/** Restore may inline object bytes in memory for hydrate. That copy must never
+ *  be published onto a lease when a durable object-storage ref exists. */
+export function omitInlineWorkspaceArchiveWhenObjectRefPresent(
+  sessionState: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...sessionState };
+  if (parseWorkspaceArchiveObjectRef(next.workspaceArchiveRef)) {
+    delete next.workspaceArchive;
+  }
+  if (parseWorkspaceArchiveObjectRef(next.workspaceArchivePrevRef)) {
+    delete next.workspaceArchivePrev;
+  }
+  return next;
+}
+
 export const NATIVE_SNAPSHOT_PREFIXES: ReadonlyArray<{
   provider: NativeSnapshotProvider;
   prefix: string;