@opengeni/api-router 0.30.1 → 1.0.0

package/src/connected-machine-computer-access.ts

@@ -0,0 +1,33 @@
+export type ConnectedMachineComputerAccessState = {
+  hasDisplay: boolean;
+  desktopUnavailableReason: string | null;
+  allowScreenControl: boolean;
+};
+
+export type ConnectedMachineComputerAccessError = {
+  status: 403 | 409;
+  message: string;
+};
+
+/** Keep passive desktop viewing separate from input consent. */
+export function connectedMachineComputerAccessError(
+  state: ConnectedMachineComputerAccessState,
+  requiresControl: boolean,
+): ConnectedMachineComputerAccessError | null {
+  if (!state.hasDisplay) {
+    const reason = state.desktopUnavailableReason?.trim();
+    return {
+      status: 409,
+      message: reason
+        ? `Connected Machine desktop is unavailable. ${reason}`
+        : "Connected Machine desktop is unavailable because this machine has no capturable display.",
+    };
+  }
+  if (requiresControl && !state.allowScreenControl) {
+    return {
+      status: 403,
+      message: "Screen control is not enabled for this Connected Machine.",
+    };
+  }
+  return null;
+}

package/src/connection-ownership.ts

@@ -0,0 +1,199 @@
+import type { ConnectionOwnership } from "@opengeni/contracts";
+import {
+  externalActorContinuationForAuthorization,
+  isVerifiedDelegatedHumanAuthorization,
+  type AccessGrantAuthorization,
+} from "@opengeni/core";
+import { HTTPException } from "hono/http-exception";
+
+/** Signing in to a third-party provider is the person's own step in the
+ * browser; an agent acting as them through the organization MCP server is told
+ * to finish it there. */
+export function requireProviderConsentInBrowser(access: AccessGrantAuthorization): void {
+  if (isVerifiedDelegatedHumanAuthorization(access))
+    throw new HTTPException(403, {
+      message:
+        "Signing in to a provider has to be done by the person in the Opengeni app in a browser.",
+    });
+}
+
+/** A verified external actor must not enter a native callback that has no
+ * corresponding key/identity reauthorization proof. Remove at an entry point
+ * only when that provider's signed continuation and commit fence are wired. */
+export function requireLegacyOAuthActor(access: AccessGrantAuthorization): void {
+  requireProviderConsentInBrowser(access);
+  if (externalActorContinuationForAuthorization(access))
+    throw new HTTPException(422, {
+      message: "This provider does not yet support external-user OAuth continuation",
+    });
+}
+
+/**
+ * Who may own a *personal* Connection.
+ *
+ * Connection setup defaults to a workspace-owned Connection; personal ownership
+ * is the explicit "Connect only for me" choice (AGENTS.md, "Connection
+ * ownership and executable personal authority are separate from turn
+ * initiation"). Only a managed human can own one, for two independent reasons:
+ * personal authority executes only through the immutable delegation snapshot
+ * frozen on a *human's* causal turn or scheduled task, and
+ * `bind_connection_authority` (migration 0256) can mint the `user` authority
+ * scope only for a subject holding an active organization membership. A
+ * machine-owned personal row therefore lands on the `legacy_user` compatibility
+ * lane and can never become a real organization-scoped authority.
+ *
+ * `principalKind` is the trusted, allow-listed signal: exactly `human_session`
+ * passes and every other value - including absent/unknown provenance - fails
+ * closed. The delegated-token contract forbids a `human_session` claim from
+ * carrying `serviceInitiator` or exact agent-attempt authority, so the claim
+ * cannot be combined with machine authority.
+ */
+
+/**
+ * Subject namespaces OpenGeni itself mints for machines. This is deliberately
+ * NOT an allow-list of human subjects: `docs/embedding.md` states that
+ * `subjectId` "remains opaque to OpenGeni" and that the kind must not be
+ * inferred from a subject-id prefix "because the host owns that namespace", so
+ * a trusted embedding host legitimately signs `human_session` over an opaque
+ * subject that is not `user:`-prefixed. Restricting personal ownership to
+ * `user:`/`dev` would break those hosts and would itself be the prefix-based
+ * kind inference the embedding contract forbids.
+ *
+ * The allow-list that actually decides is `principalKind === "human_session"`.
+ * This list is defence-in-depth against exactly one residual threat: a holder
+ * of the first-party delegation secret signing a human claim over an
+ * OpenGeni-minted machine subject.
+ *
+ * `connection-ownership.test.ts` asserts that every machine subject named in
+ * its list is rejected. Note what that does and does not buy: it catches a
+ * namespace being *removed* from this constant, and it documents the known
+ * machine subjects, but it is a hand-maintained list on both sides, so it
+ * cannot fail when a genuinely new machine namespace is introduced elsewhere in
+ * the repo. Adding one here is a manual step. That residual gap is acceptable
+ * only because this check is not the deciding signal anywhere: a new machine
+ * namespace still arrives with a non-`human_session` `principalKind` and is
+ * refused on that basis.
+ *
+ * It is also no longer the sole signal on any OAuth callback: a callback that
+ * persists a personal owner requires the HMAC-signed `personalOwnerVerified`
+ * state claim minted by a start path that saw the live principal.
+ */
+const RESERVED_MACHINE_SUBJECT_NAMESPACES = [
+  // packages/core/src/access/index.ts
+  "api_key",
+  "configured",
+  // packages/runtime/src/index.ts (signFirstPartyDelegatedBearer default)
+  "worker",
+  // packages/runtime/src/sandbox/codemode-authority.ts
+  "sandbox",
+  // apps/worker/src/activities/scheduled-tasks.ts
+  "scheduled_task",
+  // packages/db/src/session-queue-commands.ts
+  "attempt",
+  // Service principals (e.g. governed-learning activation).
+  "service",
+] as const;
+
+/** True only for an exact authenticated managed human. Unknown provenance fails closed. */
+export function isPersonalConnectionOwnerPrincipal(access: AccessGrantAuthorization): boolean {
+  const { grant } = access;
+  return (
+    // Every context grant must agree on the authenticated principal and account.
+    access.contextIntegrity &&
+    access.authenticatedSubjectId === grant.subjectId &&
+    grant.principalKind === "human_session" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext &&
+    isPersonalConnectionOwnerSubject(grant.subjectId)
+  );
+}
+
+/** Rejects an OpenGeni-minted machine subject; see the namespace list's rationale. */
+export function isPersonalConnectionOwnerSubject(subjectId: string): boolean {
+  const separator = subjectId.indexOf(":");
+  if (separator < 0) {
+    return true;
+  }
+  const namespace = subjectId.slice(0, separator);
+  return !RESERVED_MACHINE_SUBJECT_NAMESPACES.some((reserved) => reserved === namespace);
+}
+
+export const PERSONAL_CONNECTION_PRINCIPAL_MESSAGE =
+  "personal Connection ownership requires an authenticated human; API keys, configured keys, " +
+  "services, and agent attempts can create only workspace-owned Connections";
+
+/** Personal-only connectors cannot degrade to workspace ownership, so they say so exactly. */
+export function personalOnlyConnectionPrincipalMessage(label: string): string {
+  return (
+    `${label} connects only as a personal Connection, which requires an authenticated human; ` +
+    "API keys, configured keys, services, and agent attempts cannot own one"
+  );
+}
+
+/**
+ * Rejects a non-human principal before a personal Connection is created.
+ * `label` names a personal-only connector, whose message must not suggest a
+ * workspace-owned alternative that its provider profile forbids.
+ *
+ * This shares that helper's core caller-integrity checks, then additionally
+ * rejects every reserved machine-subject namespace as defence-in-depth. The
+ * sibling guards a self-service authority surface where the caller claims to
+ * *be* the owner (403 "not you"), while this one rejects an ownership *value*
+ * that is unavailable to the caller (422).
+ */
+export function assertPersonalConnectionOwnerPrincipal(
+  access: AccessGrantAuthorization,
+  label?: string,
+): void {
+  if (isPersonalConnectionOwnerPrincipal(access)) {
+    return;
+  }
+  throw new HTTPException(422, {
+    message: label
+      ? personalOnlyConnectionPrincipalMessage(label)
+      : PERSONAL_CONNECTION_PRINCIPAL_MESSAGE,
+  });
+}
+
+/** The same fence expressed for a flow that resolves ownership after admission. */
+export function assertConnectionOwnershipAllowedForPrincipal(
+  ownership: ConnectionOwnership,
+  personalOwnershipAllowed: boolean,
+): void {
+  if (ownership === "personal" && !personalOwnershipAllowed) {
+    throw new HTTPException(422, { message: PERSONAL_CONNECTION_PRINCIPAL_MESSAGE });
+  }
+}
+
+/**
+ * The claim a start path mints into its HMAC-signed OAuth state when it has
+ * verified the live principal may own a personal Connection.
+ *
+ * An OAuth callback carries signed state, not a live principal, so it cannot
+ * re-evaluate `principalKind`. Requiring this claim makes the callback enforce
+ * exactly what the start path decided with the full signal, instead of guessing
+ * from the subject's shape. A state minted before this claim existed simply
+ * lacks it and fails closed for personal ownership - which is precisely the
+ * in-flight rolling-deploy window these fences exist to close.
+ */
+export const PERSONAL_OWNER_VERIFIED_STATE_CLAIM = "personalOwnerVerified" as const;
+
+/** True only for an explicit boolean `true` claim; absent or malformed fails closed. */
+export function personalOwnerVerifiedInState(payload: Record<string, unknown>): boolean {
+  return payload[PERSONAL_OWNER_VERIFIED_STATE_CLAIM] === true;
+}
+
+/**
+ * Callback-side fence for every path that persists a personal owner. Requires
+ * both the signed start-time verification and a non-machine subject.
+ */
+export function personalOwnerStateAccepted(state: {
+  ownership: ConnectionOwnership;
+  subjectId: string;
+  personalOwnerVerified: boolean;
+}): boolean {
+  if (state.ownership !== "personal") {
+    return true;
+  }
+  return state.personalOwnerVerified && isPersonalConnectionOwnerSubject(state.subjectId);
+}

package/src/controller-data-plane.ts

@@ -1,7 +1,56 @@
 import {
   BrowserControlRequestError,
   BrowserControlTransportError,
+  exposedPortAllowsHostFetch,
+  exposedPortEndpointFromUrl,
+  parseOpenSandboxSignedUriPath,
+  signedEndpointNeedsRefresh,
 } from "@opengeni/runtime/sandbox";
+import type { InteractionPlacement } from "@opengeni/contracts";
+import type { ChannelAOperation } from "./sandbox/channel-a";
+
+/** Modal/Daytona/Blaxel tunnels serve browserd at `/`, so a cached
+ * controller-only session can host-fetch JSON. OpenSandbox's lifecycle proxy
+ * prefixes `/v1/sandboxes/<id>/proxy/<port>` and rewrites Authorization; JSON
+ * must stay on an exec-capable in-box curl session. OSEP-0011 signed URIs are
+ * Authorization-preserving and host-fetch like a native tunnel, but they are
+ * not durable cache keys. */
+export function controllerCacheAllowsHostFetch(url: string): boolean {
+  try {
+    return exposedPortAllowsHostFetch(exposedPortEndpointFromUrl(url));
+  } catch {
+    return false;
+  }
+}
+
+export function isOpenSandboxSignedControllerUrl(url: string): boolean {
+  try {
+    return parseOpenSandboxSignedUriPath(new URL(url).pathname) !== null;
+  } catch {
+    return false;
+  }
+}
+
+/** Signed Channel B URLs expire. Do not treat a lease-cached signed URI as an
+ * infinite controller endpoint. Unsigned native `/` tunnels stay cacheable. */
+export function controllerCachedUrlIsUsable(url: string, nowMs = Date.now()): boolean {
+  if (!controllerCacheAllowsHostFetch(url)) return false;
+  if (!isOpenSandboxSignedControllerUrl(url)) return true;
+  try {
+    return !signedEndpointNeedsRefresh(new URL(url).pathname, nowMs);
+  } catch {
+    return false;
+  }
+}
+
+export function shouldPersistControllerDataPlaneUrl(input: {
+  backend: string | null | undefined;
+  signedEndpoints: boolean;
+  url: string;
+}): boolean {
+  if (input.backend === "opensandbox" && input.signedEndpoints) return false;
+  return controllerCachedUrlIsUsable(input.url);
+}
 
 /** Prefer a lease-fenced controller endpoint for the idempotent create path.
  * Only a transport-class failure invalidates the cache and provisions once;
@@ -33,3 +82,35 @@ export function isRetryableControllerTransport(error: unknown): boolean {
     (error instanceof BrowserControlRequestError && error.retryable)
   );
 }
+
+/** A stopped sidecar needs provisioning on its original, fenced placement.
+ * Only reads and journaled actions may recover, once across provider retries.
+ * Revalidate controller authority before starting the sidecar. */
+export async function withControllerTransportRecovery<T>(options: {
+  channelOperation: ChannelAOperation;
+  placementKind: InteractionPlacement["kind"];
+  recoveryState: { attempted: boolean };
+  transportAlreadyFailed: boolean;
+  use: () => Promise<T>;
+  admitRecovery: () => Promise<void>;
+  recover: () => Promise<T>;
+}): Promise<T> {
+  if (
+    (options.channelOperation !== "browser.read" &&
+      options.channelOperation !== "browser.action") ||
+    options.placementKind !== "sandbox_group" ||
+    options.recoveryState.attempted
+  ) {
+    return await options.use();
+  }
+  if (!options.transportAlreadyFailed) {
+    try {
+      return await options.use();
+    } catch (error) {
+      if (!isRetryableControllerTransport(error)) throw error;
+    }
+  }
+  options.recoveryState.attempted = true;
+  await options.admitRecovery();
+  return await options.recover();
+}

package/src/editable-artifact-native-kernel.ts

@@ -17,6 +17,13 @@ import {
 } from "@opengeni/contracts/editable-artifact-causal-frontier";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
 import { decodeEditableArtifactMutationIntent } from "@opengeni/contracts/editable-artifacts";
+import {
+  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+  DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION,
+  PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION,
+  SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
+  SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
+} from "@opengeni/contracts/editable-artifact-versions";
 import {
   MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES,
   causalFrontiersEqual,
@@ -39,9 +46,6 @@ import {
 } from "@opengeni/core";
 import type { BoundedObjectReadPort } from "@opengeni/storage";
 
-const MODEL_SCHEMA_VERSION = 1;
-const OPERATION_PROTOCOL_VERSION = 1;
-const CRDT_STATE_VERSION = 1;
 const SNAPSHOT_CHUNK_BYTES = 1024 * 1024;
 
 type RuntimeFacadeModule = Readonly<{
@@ -104,7 +108,7 @@ export class NativeEditableArtifactKernelAdapter
           modality: "spreadsheet" as const,
           committedTransactionBytes,
           kernelVersion: this.runtime.buildIdentity,
-          modelSchemaVersion: MODEL_SCHEMA_VERSION,
+          modelSchemaVersion: SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
         });
       }
       if (session.modality !== request.modality) {
@@ -116,7 +120,7 @@ export class NativeEditableArtifactKernelAdapter
         nativeReceiptBytes,
         resultingStateHash: editableArtifactStateHash(session.stateHash()),
         kernelVersion: this.runtime.buildIdentity,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(request.modality),
       });
     } finally {
       session.dispose();
@@ -188,7 +192,7 @@ export class NativeEditableArtifactKernelAdapter
         ),
         stateHash: editableArtifactStateHash(session.stateHash()),
         coveredHeadSequence: 0 as const,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(input.modality),
         kernelVersion: this.runtime.buildIdentity,
       };
       if (session.modality === "spreadsheet") {
@@ -196,8 +200,8 @@ export class NativeEditableArtifactKernelAdapter
           ...common,
           modality: "spreadsheet" as const,
           coveredCausalFrontier: domainFrontier(session.frontier()),
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
         });
       }
       return Object.freeze({
@@ -239,7 +243,7 @@ export class NativeEditableArtifactKernelAdapter
         ),
         stateHash: editableArtifactStateHash(session.stateHash()),
         coveredHeadSequence: input.state.artifact.headSequence,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(input.state.modality),
         kernelVersion: this.runtime.buildIdentity,
       } as const;
       if (session.modality === "spreadsheet") {
@@ -248,8 +252,8 @@ export class NativeEditableArtifactKernelAdapter
           ...common,
           modality: session.modality,
           coveredCausalFrontier: domainFrontier(session.frontier()),
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
         });
       }
       if (session.modality !== input.state.modality) throw new Error("Native modality mismatch");
@@ -310,12 +314,12 @@ export class NativeEditableArtifactKernelAdapter
           canonicalContentHash,
           coveredHeadSequence,
           stateHash,
-          modelSchemaVersion: MODEL_SCHEMA_VERSION,
+          modelSchemaVersion: SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION,
           kernelVersion: this.runtime.buildIdentity,
           fullCrdtStateVerified: true as const,
           coveredCausalFrontier,
-          operationProtocolVersion: OPERATION_PROTOCOL_VERSION,
-          crdtStateVersion: CRDT_STATE_VERSION,
+          operationProtocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
+          crdtStateVersion: SPREADSHEET_COLLABORATION_SNAPSHOT_VERSION,
           ...(replayedTarget ? { replayedTarget } : {}),
         });
       }
@@ -339,7 +343,7 @@ export class NativeEditableArtifactKernelAdapter
         canonicalContentHash,
         coveredHeadSequence,
         stateHash,
-        modelSchemaVersion: MODEL_SCHEMA_VERSION,
+        modelSchemaVersion: modelSchemaVersionFor(session.modality),
         kernelVersion: this.runtime.buildIdentity,
         nativeRevision,
         ...(replayedTarget ? { replayedTarget } : {}),
@@ -350,6 +354,13 @@ export class NativeEditableArtifactKernelAdapter
   }
 }
 
+function modelSchemaVersionFor(modality: "spreadsheet" | "document" | "presentation"): 1 | 2 {
+  if (modality === "spreadsheet") return SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION;
+  return modality === "document"
+    ? DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION
+    : PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION;
+}
+
 function assertRuntime(
   candidate: unknown,
   location: ConfiguredArtifactRuntimeLocation,

package/src/editable-artifact-office-import.ts

@@ -12,13 +12,17 @@ import {
   editableArtifactReplicaId,
   editableArtifactStateHash,
   EditableArtifactOfficeImportError,
+  type EditableArtifactActor,
   type EditableArtifactOfficeImportPort,
   type EditableArtifactModality,
+  type EditableArtifactScope,
 } from "@opengeni/core/editable-artifacts";
-import { getFile } from "@opengeni/db";
+import { requireLiveAgentAttemptAuthorization } from "@opengeni/core";
+import { getFilesForSubject } from "@opengeni/db";
 import {
   MAX_BOUNDED_OBJECT_CHUNK_BYTES,
   type BoundedImmutableObjectWritePort,
+  retryWhileMissing,
   type ObjectStorage,
 } from "@opengeni/storage";
 import type { Database } from "@opengeni/db";
@@ -32,23 +36,37 @@ export type EditableArtifactOfficeImportAdapterDependencies = Readonly<{
   runtime: VerifiedNativeArtifactRuntimeBinding;
   sourceObjects: BoundedImmutableObjectWritePort;
   snapshotObjects: BoundedImmutableObjectWritePort;
-  readFile?: typeof getFile;
+  readFiles?: typeof getFilesForSubject;
+  resolveFileAuthoritySubjectId?: typeof editableArtifactFileAuthoritySubjectId;
   prepareOffice?: typeof prepareArtifactOfficeImport;
 }>;
 
 /** Trusted import boundary from one ready workspace file into native sequence-zero state. */
 export class EditableArtifactOfficeImportAdapter implements EditableArtifactOfficeImportPort {
-  private readonly readFile: typeof getFile;
+  private readonly readFiles: typeof getFilesForSubject;
+  private readonly resolveFileAuthoritySubjectId: typeof editableArtifactFileAuthoritySubjectId;
 
   constructor(private readonly dependencies: EditableArtifactOfficeImportAdapterDependencies) {
-    this.readFile = dependencies.readFile ?? getFile;
+    this.readFiles = dependencies.readFiles ?? getFilesForSubject;
+    this.resolveFileAuthoritySubjectId =
+      dependencies.resolveFileAuthoritySubjectId ?? editableArtifactFileAuthoritySubjectId;
   }
 
   async prepare(
     input: Parameters<EditableArtifactOfficeImportPort["prepare"]>[0],
   ): ReturnType<EditableArtifactOfficeImportPort["prepare"]> {
     throwIfAborted(input.signal);
-    const file = await this.readFile(this.dependencies.db, input.scope.workspaceId, input.fileId);
+    const subjectId = await this.resolveFileAuthoritySubjectId(
+      this.dependencies.db,
+      input.scope,
+      input.actor,
+    );
+    const [file] = await this.readFiles(this.dependencies.db, {
+      accountId: input.scope.accountId,
+      workspaceId: input.scope.workspaceId,
+      subjectId,
+      fileIds: [input.fileId],
+    });
     if (!file || file.status !== "ready") {
       throw new EditableArtifactOfficeImportError("invalid_source");
     }
@@ -179,11 +197,23 @@ function officeFilenameMatches(filename: string, modality: EditableArtifactModal
 
 async function readVerifiedWorkspaceFile(
   storage: ObjectStorage,
-  file: NonNullable<Awaited<ReturnType<typeof getFile>>>,
+  file: NonNullable<Awaited<ReturnType<typeof getFilesForSubject>>>[number],
   signal?: AbortSignal,
 ): Promise<Uint8Array> {
   throwIfAborted(signal);
-  const before = await storage.headFile(file);
+  const before = await retryWhileMissing(async () => {
+    try {
+      return await storage.headFile(file);
+    } catch (error) {
+      if (typeof storage.fileExists === "function" && !(await storage.fileExists(file))) {
+        return null;
+      }
+      throw error;
+    }
+  });
+  if (!before) {
+    throw new EditableArtifactOfficeImportError("source_changed");
+  }
   if (
     before.ContentLength !== file.sizeBytes ||
     before.ContentType !== file.contentType ||
@@ -198,14 +228,26 @@ async function readVerifiedWorkspaceFile(
   for (let start = 0; start < file.sizeBytes; start += MAX_BOUNDED_OBJECT_CHUNK_BYTES) {
     throwIfAborted(signal);
     const end = Math.min(file.sizeBytes, start + MAX_BOUNDED_OBJECT_CHUNK_BYTES) - 1;
-    const chunk = await storage.getFileRange(file, { start, end });
+    const chunk = await retryWhileMissing(async () => storage.getFileRange(file, { start, end }));
     if (!chunk || chunk.byteLength !== end - start + 1) {
       throw new EditableArtifactOfficeImportError("source_changed");
     }
     bytes.set(chunk, start);
     digest.update(chunk);
   }
-  const after = await storage.headFile(file);
+  const after = await retryWhileMissing(async () => {
+    try {
+      return await storage.headFile(file);
+    } catch (error) {
+      if (typeof storage.fileExists === "function" && !(await storage.fileExists(file))) {
+        return null;
+      }
+      throw error;
+    }
+  });
+  if (!after) {
+    throw new EditableArtifactOfficeImportError("source_changed");
+  }
   const sha256 = digest.digest("hex");
   if (
     after.ContentLength !== before.ContentLength ||
@@ -219,6 +261,32 @@ async function readVerifiedWorkspaceFile(
   return bytes;
 }
 
+export async function editableArtifactFileAuthoritySubjectId(
+  db: Database,
+  scope: EditableArtifactScope,
+  actor: EditableArtifactActor,
+): Promise<string | null> {
+  if (actor.kind !== "agent") return actor.subjectId;
+  const authorization = await requireLiveAgentAttemptAuthorization(
+    db,
+    {
+      accountId: scope.accountId,
+      workspaceId: scope.workspaceId,
+      subjectId: actor.subjectId,
+      permissions: [],
+      principalKind: "agent_attempt",
+      metadata: {
+        sessionId: actor.sessionId,
+        turnId: actor.turnId,
+        attemptId: actor.attemptId,
+        executionGeneration: actor.generation,
+      },
+    },
+    actor.sessionId,
+  );
+  return authorization.initiatingHumanSubjectId;
+}
+
 async function* byteChunks(bytes: Uint8Array): AsyncIterable<Uint8Array> {
   for (let offset = 0; offset < bytes.byteLength; offset += MAX_BOUNDED_OBJECT_CHUNK_BYTES) {
     yield bytes.subarray(offset, offset + MAX_BOUNDED_OBJECT_CHUNK_BYTES);

package/src/editable-artifact-production.ts

@@ -6,6 +6,7 @@ import {
 import {
   EditableArtifactDurableExportService,
   EditableArtifactAgentApplication,
+  EDITABLE_ARTIFACT_EXPORT_FORMATS,
   EDITABLE_ARTIFACT_EXPORT_MAX_DOWNLOAD_BYTES,
   EditableArtifactCompactionPipeline,
   EditableArtifactGenesisPipeline,
@@ -30,7 +31,6 @@ import {
   type EditableArtifactMaterializationProfilePort,
 } from "@opengeni/core/editable-artifacts";
 import {
-  EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION,
   EditableArtifactApplication,
   EditableArtifactCompatibilityError,
   EditableArtifactLiveServer,
@@ -41,12 +41,14 @@ import {
   type EditableArtifactLiveAuthorizationInvalidationPort,
   type EditableArtifactLiveCompatibilityPort,
 } from "@opengeni/core/editable-artifact-live";
+import { currentEditableArtifactCompatibility } from "@opengeni/contracts/editable-artifacts";
 import {
   PostgresEditableArtifactLiveReadStore,
   PostgresEditableArtifactLiveTicketStore,
   PostgresEditableArtifactStore,
   listEditableArtifactIdsForSession,
   touchEditableArtifactSessionLink,
+  recordNativeDocumentInspection,
   dbSql,
   withRlsContext,
   type Database,
@@ -167,6 +169,11 @@ export async function createStandaloneEditableArtifactApplication(input: {
         await touchEditableArtifactSessionLink(input.db, scope, sessionId, artifactId),
     } satisfies EditableArtifactAgentAssociationPort),
     inspector: kernel,
+    recordInspection: async (inspection) => {
+      if (inspection.actor.kind !== "agent")
+        throw new Error("Inspection proof requires an agent attempt");
+      return recordNativeDocumentInspection(input.db, { ...inspection, actor: inspection.actor });
+    },
     officeImports,
     workspaceFiles: new EditableArtifactWorkspaceFileAdapter({
       db: input.db,
@@ -194,10 +201,14 @@ export async function createStandaloneEditableArtifactApplication(input: {
     assertCompatible(
       request: Parameters<EditableArtifactLiveCompatibilityPort["assertCompatible"]>[0],
     ) {
+      const current = currentEditableArtifactCompatibility(request.artifact.modality);
       if (
-        request.protocolVersion !== EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION ||
-        request.modelSchemaVersion !== 1 ||
-        request.kernelVersion !== runtime.buildIdentity
+        request.modality !== request.artifact.modality ||
+        request.liveProtocolVersion !== current.liveProtocolVersion ||
+        request.modelSchemaVersion !== current.modelSchemaVersion ||
+        request.snapshotVersion !== current.snapshotVersion ||
+        request.commandProtocolVersion !== current.commandProtocolVersion ||
+        request.committedTransactionProtocolVersion !== current.committedTransactionProtocolVersion
       ) {
         throw new EditableArtifactCompatibilityError();
       }
@@ -334,23 +345,28 @@ class RandomEditableArtifactDurableExportIds implements EditableArtifactDurableE
 function materializationProfiles(
   capabilities: EditableArtifactNativeMaterializerCapabilities,
 ): EditableArtifactMaterializationProfilePort {
+  const spreadsheetCompatibility = currentEditableArtifactCompatibility("spreadsheet");
   if (
     capabilities.protocol !== "OGAMC001" ||
     capabilities.runtimeKind !== "native" ||
     capabilities.maxOutputBytes !== EDITABLE_ARTIFACT_EXPORT_MAX_DOWNLOAD_BYTES ||
     capabilities.codecVersions["opengeni.xlsx"] === undefined ||
-    !capabilities.supportedModelSchemaVersions.includes(1) ||
-    !capabilities.supportedOperationProtocolVersions.includes(1) ||
-    !capabilities.supportedSnapshotProtocolVersions.includes(1)
+    capabilities.supportedModelSchemaVersions[0] !== spreadsheetCompatibility.modelSchemaVersion ||
+    capabilities.supportedOperationProtocolVersions[0] !==
+      spreadsheetCompatibility.committedTransactionProtocolVersion ||
+    capabilities.supportedSnapshotProtocolVersions[0] !== spreadsheetCompatibility.snapshotVersion
   ) {
     throw new Error("Verified artifact materializer profile is incompatible");
   }
   const codecVersion = capabilities.codecVersions["opengeni.xlsx"];
   return Object.freeze({
+    supportedFormats: EDITABLE_ARTIFACT_EXPORT_FORMATS,
     async resolve(input: Parameters<EditableArtifactMaterializationProfilePort["resolve"]>[0]) {
+      // EDITABLE_ARTIFACT_EXPORT_FORMATS is what agents are told exists.
       if (
         input.modality !== "spreadsheet" ||
         input.format !== "xlsx" ||
+        !EDITABLE_ARTIFACT_EXPORT_FORMATS[input.modality].includes(input.format) ||
         Object.keys(input.options).length !== 0
       ) {
         return null;