@opengeni/core 0.28.0 → 1.0.0

package/src/domain/editable-artifacts/durable-export.ts

@@ -33,6 +33,63 @@ export type EditableArtifactMaterializationFormat =
   | "png"
   | "webp";
 
+/**
+ * Stock production export formats. Custom deployments advertise their own
+ * capabilities on the profile port; this list never overrides their resolver.
+ * Extend the stock list only together with a real deployed codec.
+ */
+export const EDITABLE_ARTIFACT_EXPORT_FORMATS: Readonly<
+  Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+> = Object.freeze({
+  spreadsheet: Object.freeze(["xlsx"] as const),
+  document: Object.freeze([] as const),
+  presentation: Object.freeze([] as const),
+});
+
+/** Human/agent-readable summary of {@link EDITABLE_ARTIFACT_EXPORT_FORMATS}. */
+export function describeEditableArtifactExportFormats(): string {
+  return describeConfiguredExportFormats(EDITABLE_ARTIFACT_EXPORT_FORMATS);
+}
+
+export function describeConfiguredExportFormats(
+  configuredFormats: Readonly<
+    Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+  >,
+): string {
+  const entries = Object.entries(configuredFormats) as Array<
+    [EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]]
+  >;
+  const supported = entries
+    .filter(([, formats]) => formats.length > 0)
+    .map(([modality, formats]) => `${modality} → ${formats.join(", ")}`);
+  const none = entries.filter(([, formats]) => formats.length === 0).map(([modality]) => modality);
+  return [
+    supported.length > 0
+      ? `Supported exports: ${supported.join("; ")}.`
+      : "No exports are available.",
+    none.length > 0
+      ? `${none.join(" and ")} artifacts cannot be exported yet (no PDF, DOCX, PPTX, or image export); share the live artifact with its artifactReference link instead.`
+      : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+}
+
+/** Typed refusal that tells the caller which formats do exist. */
+export function unsupportedEditableArtifactExport(
+  modality: EditableArtifactModality,
+  format: string,
+  formats = EDITABLE_ARTIFACT_EXPORT_FORMATS,
+): EditableArtifactDurableExportError {
+  const listed = (formats[modality] as readonly string[]).includes(format);
+  return new EditableArtifactDurableExportError(
+    "unsupported_format",
+    listed
+      ? `unsupported_format: this deployment does not serve a ${format} export of a ${modality} artifact with these options; retry with options omitted. ${describeConfiguredExportFormats(formats)}`
+      : `unsupported_format: a ${modality} artifact cannot be exported as ${format}. ${describeConfiguredExportFormats(formats)}`,
+  );
+}
+
 export type EditableArtifactMaterializationMimeType =
   | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
   | "application/vnd.openxmlformats-officedocument.presentationml.presentation"
@@ -98,6 +155,11 @@ export type EditableArtifactMaterializationProfile = Readonly<{
 
 /** Server-owned profile lookup. Clients never supply executable identity facts. */
 export interface EditableArtifactMaterializationProfilePort {
+  /** Deployment-owned discovery; resolve remains the authority for exact options.
+   * Optional for existing custom adapters, whose support is resolved dynamically. */
+  supportedFormats?: Readonly<
+    Record<EditableArtifactModality, readonly EditableArtifactMaterializationFormat[]>
+  >;
   resolve(
     input: Readonly<{
       modality: EditableArtifactModality;
@@ -223,8 +285,11 @@ export type EditableArtifactDurableExportErrorCode =
   | "unavailable";
 
 export class EditableArtifactDurableExportError extends Error {
-  constructor(readonly code: EditableArtifactDurableExportErrorCode) {
-    super(code);
+  constructor(
+    readonly code: EditableArtifactDurableExportErrorCode,
+    message?: string,
+  ) {
+    super(message ?? code);
     this.name = "EditableArtifactDurableExportError";
   }
 }
@@ -247,6 +312,38 @@ const PROFILE_TEXT = /^[\x21-\x7e]+$/u;
 export class EditableArtifactDurableExportService {
   constructor(private readonly dependencies: EditableArtifactDurableExportServiceDependencies) {}
 
+  describeFormats(): string {
+    const formats = this.dependencies.profiles.supportedFormats;
+    return formats
+      ? describeConfiguredExportFormats(formats)
+      : "Export formats are determined by this deployment's configured exporter; unsupported format/options combinations are refused before pinning.";
+  }
+
+  /** Read-only exact preflight: no snapshot, ID allocation, or store write. */
+  async preflight(input: {
+    modality: EditableArtifactModality;
+    format: EditableArtifactMaterializationFormat;
+    options?: Readonly<Record<string, unknown>>;
+  }): Promise<EditableArtifactMaterializationProfile> {
+    const format = materializationFormat(input.format);
+    const options = exactOptions(input.options ?? Object.freeze({}));
+    const profile = await this.dependencies.profiles.resolve({
+      modality: input.modality,
+      format,
+      options,
+    });
+    if (!profile) {
+      const formats = this.dependencies.profiles.supportedFormats;
+      if (formats) throw unsupportedEditableArtifactExport(input.modality, format, formats);
+      throw new EditableArtifactDurableExportError(
+        "unsupported_format",
+        `unsupported_format: this deployment does not serve ${input.modality} → ${format} with these options. ${this.describeFormats()}`,
+      );
+    }
+    validateProfile(profile, input.modality, format);
+    return profile;
+  }
+
   async pinVersion(
     input: DurableExportContext & {
       idempotencyKey: string;
@@ -307,13 +404,11 @@ export class EditableArtifactDurableExportService {
     const format = materializationFormat(input.format);
     const options = exactOptions(input.options ?? Object.freeze({}));
     const version = await this.getVersion(context, versionId);
-    const profile = await this.dependencies.profiles.resolve({
+    const profile = await this.preflight({
       modality: version.modality,
       format,
       options,
     });
-    if (!profile) throw new EditableArtifactDurableExportError("unsupported_format");
-    validateProfile(profile, version.modality, format);
     const requestHash = hashPublicRequest("materialize", [
       idempotencyKey,
       versionId,

package/src/domain/editable-artifacts/in-memory.ts

@@ -429,6 +429,9 @@ export class InMemoryEditableArtifactStore
     artifactId: EditableArtifactId,
     request: ReadEditableArtifactTransactionBasisRequest,
   ): Promise<EditableArtifactTransactionBasis> {
+    if (request.authorizeCommit) {
+      throw new TypeError("Transactional artifact authority requires a PostgreSQL store");
+    }
     const normalizedScope = editableArtifactScope(scope);
     const normalizedArtifactId = editableArtifactId(artifactId);
     const key = aggregateKey(normalizedScope, normalizedArtifactId);
@@ -496,6 +499,9 @@ export class InMemoryEditableArtifactStore
   async tryCommitAppliedTransaction(
     request: TryCommitAppliedEditableArtifactTransactionRequest,
   ): Promise<TryCommitAppliedEditableArtifactTransactionResult> {
+    if (request.authorizeCommit) {
+      throw new TypeError("Transactional artifact authority requires a PostgreSQL store");
+    }
     const scope = editableArtifactScope(request.scope);
     const artifactId = editableArtifactId(request.artifactId);
     const key = aggregateKey(scope, artifactId);

package/src/domain/editable-artifacts/ports.ts

@@ -1,3 +1,4 @@
+import type { Database } from "@opengeni/db";
 import type {
   EditableArtifact,
   EditableArtifactActor,
@@ -288,6 +289,8 @@ export type ReadEditableArtifactTransactionBasisRequest = Readonly<{
   clientTransactionId: EditableArtifactReceipt["clientTransactionId"];
   previousLocalTransactionId: EditableArtifactReceipt["previousLocalTransactionId"];
   selectiveUndoOperationIds: readonly EditableArtifactOperationId[];
+  /** Backend-only live authority; checked transactionally even on receipt replay. */
+  authorizeCommit?: EditableArtifactCommitAuthorizer;
 }>;
 
 export type EditableArtifactTransactionUndoBasis = Readonly<{
@@ -324,6 +327,13 @@ export type ExpectedEditableArtifactPredecessor = Readonly<{
   replicaCounter: number;
 }>;
 
+/**
+ * Receives the actual persistence transaction, never a separate pool handle.
+ * May run repeatedly for replay, lock admission and final persistence; must not
+ * perform external mutations. Stores without this transaction capability deny.
+ */
+export type EditableArtifactCommitAuthorizer = (tx: Database) => Promise<void>;
+
 export type TryCommitAppliedEditableArtifactTransactionRequest =
   CommitAppliedEditableArtifactTransaction &
     Readonly<{
@@ -333,6 +343,7 @@ export type TryCommitAppliedEditableArtifactTransactionRequest =
       expectedAuthorizationRevision: number;
       /** Rechecked by durable production stores in the commit transaction. */
       authorizationActor: EditableArtifactActor;
+      authorizeCommit?: EditableArtifactCommitAuthorizer;
       actorKey: string;
       clientTransactionId: EditableArtifactReceipt["clientTransactionId"];
       requestHash: EditableArtifactReceipt["requestHash"];

package/src/domain/editable-artifacts/service.ts

@@ -13,6 +13,7 @@ import {
   EditableArtifactUndoTargetError,
 } from "./errors";
 import type {
+  EditableArtifactCommitAuthorizer,
   AuthoritativeEditableArtifactKernelPort,
   EditableArtifactAuthorizationPort,
   EditableArtifactClockPort,
@@ -28,9 +29,11 @@ import { hashEditableArtifactCreateRequest, hashEditableArtifactImportRequest }
 import {
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES,
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
   EDITABLE_ARTIFACT_INTENT_MAX_UNDO_TARGETS,
   EDITABLE_ARTIFACT_INTENT_VERSION,
   EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES,
+  EDITABLE_ARTIFACT_CODEC_REGISTRY,
 } from "@opengeni/contracts/editable-artifacts";
 import {
   COMMITTED_TRANSACTION_PROTOCOL_VERSION,
@@ -111,7 +114,6 @@ export const EDITABLE_ARTIFACT_MAX_COMMAND_BYTES_PER_TRANSACTION =
   EDITABLE_ARTIFACT_COMMAND_MAX_BYTES;
 export const EDITABLE_ARTIFACT_MAX_INTENT_BYTES_PER_TRANSACTION =
   EDITABLE_ARTIFACT_INTENT_MAX_BYTES;
-export const EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION = 1;
 export const EDITABLE_ARTIFACT_MAX_OPERATION_BYTES_PER_TRANSACTION =
   MAX_COMMITTED_TRANSACTION_BYTES;
 /** Canonical OGACO envelope bound. Kept as an alias for existing consumers. */
@@ -546,6 +548,8 @@ export class EditableArtifactService {
     artifactId: EditableArtifact["id"];
     actor: EditableArtifactActor;
     request: ApplyEditableArtifactTransactionRequest;
+    /** Authenticated backend authority, not part of the client mutation envelope. */
+    authorizeCommit?: EditableArtifactCommitAuthorizer;
   }): Promise<ApplyEditableArtifactTransactionResult> {
     const context = normalizeBoundaryContext(input);
     const request = normalizeTransactionEnvelope(input.request);
@@ -569,6 +573,19 @@ export class EditableArtifactService {
     }
     const intentBytes = request.intentBytes.slice();
     const actorKey = editableArtifactActorKey(context.actor);
+    // A source-bound caller must prove its own authority on commit/replay.
+    // Sharing another caller's in-flight result would skip that proof.
+    if (input.authorizeCommit) {
+      return await this.applyTransactionOptimistically({
+        context,
+        actorKey,
+        request,
+        intent,
+        intentBytes,
+        authorizationRevision,
+        authorizeCommit: input.authorizeCommit,
+      });
+    }
     const inFlightKey = transactionInFlightKey(
       context.scope,
       context.artifactId,
@@ -630,6 +647,7 @@ export class EditableArtifactService {
     intent: ValidatedEditableArtifactMutationIntent;
     intentBytes: Uint8Array;
     authorizationRevision: number;
+    authorizeCommit?: EditableArtifactCommitAuthorizer;
   }): Promise<ApplyEditableArtifactTransactionResult> {
     const { context, actorKey, request, intent, intentBytes } = input;
     let authorizationRevision = input.authorizationRevision;
@@ -642,6 +660,7 @@ export class EditableArtifactService {
           clientTransactionId: intent.clientTransactionId,
           previousLocalTransactionId: intent.previousLocalTransactionId,
           selectiveUndoOperationIds: intent.selectiveUndoOperationIds,
+          ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
         },
       );
       if (basisRead.kind === "existing") {
@@ -796,6 +815,7 @@ export class EditableArtifactService {
           expectedLifecycle: "active",
           expectedAuthorizationRevision: authorizationRevision,
           authorizationActor: context.actor,
+          ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
           expectedHeadSequence: artifact.headSequence,
           actorKey,
           clientTransactionId: intent.clientTransactionId,
@@ -1036,6 +1056,7 @@ export class EditableArtifactService {
         expectedLifecycle: "active",
         expectedAuthorizationRevision: authorizationRevision,
         authorizationActor: context.actor,
+        ...(input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}),
         expectedHeadSequence: artifact.headSequence,
         actorKey,
         clientTransactionId: intent.clientTransactionId,
@@ -2266,6 +2287,10 @@ function validateSnapshotRequest(
   assertNonnegativeSafeInteger(rawCoveredHeadSequence, "snapshot covered head sequence");
   const stateHash = editableArtifactStateHash(rawStateHash);
   assertPositiveSafeInteger(rawModelSchemaVersion, "snapshot model schema version");
+  const currentCodec = EDITABLE_ARTIFACT_CODEC_REGISTRY[rawModality];
+  if (rawModelSchemaVersion !== currentCodec.modelSchemaVersion) {
+    throw new TypeError("Snapshot model schema version is unsupported");
+  }
   assertBoundedKernelVersion(rawKernelVersion);
   assertIsoTimestamp(rawVerifiedAt, "snapshot verified timestamp");
   const common = {
@@ -2294,6 +2319,12 @@ function validateSnapshotRequest(
     }
     assertPositiveSafeInteger(rawOperationProtocolVersion, "snapshot operation protocol version");
     assertPositiveSafeInteger(rawCrdtStateVersion, "snapshot CRDT state version");
+    if (
+      rawOperationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
+      rawCrdtStateVersion !== currentCodec.snapshotVersion
+    ) {
+      throw new TypeError("Spreadsheet snapshot version is unsupported");
+    }
     return Object.freeze({
       ...common,
       modality: "spreadsheet",

package/src/domain/editable-artifacts/snapshot-compaction.ts

@@ -1,4 +1,6 @@
 import { type BoundedImmutableObjectWritePort, BoundedObjectWriteError } from "@opengeni/storage";
+import { EDITABLE_ARTIFACT_CODEC_REGISTRY } from "@opengeni/contracts/editable-artifacts";
+import { COMMITTED_TRANSACTION_PROTOCOL_VERSION } from "@opengeni/contracts/editable-artifact-committed-transaction";
 
 import type { EditableArtifactCompactionPort, EditableArtifactKernelState } from "./ports";
 import {
@@ -177,6 +179,7 @@ function validateGenerated(
   scope: EditableArtifactScope,
   artifactId: EditableArtifactId,
 ): void {
+  const currentCodec = EDITABLE_ARTIFACT_CODEC_REGISTRY[value.modality];
   if (
     value.scope.accountId !== scope.accountId ||
     value.scope.workspaceId !== scope.workspaceId ||
@@ -207,11 +210,12 @@ function validateGenerated(
     throw new EditableArtifactSnapshotVerificationError("limit_exceeded");
   }
   editableArtifactContentHash(value.canonicalContentHash);
-  const versions =
-    value.modality === "spreadsheet"
-      ? [value.modelSchemaVersion, value.operationProtocolVersion, value.crdtStateVersion]
-      : [value.modelSchemaVersion];
-  if (versions.some((version) => !Number.isSafeInteger(version) || version <= 0)) {
+  if (
+    value.modelSchemaVersion !== currentCodec.modelSchemaVersion ||
+    (value.modality === "spreadsheet" &&
+      (value.operationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
+        value.crdtStateVersion !== currentCodec.snapshotVersion))
+  ) {
     throw new EditableArtifactSnapshotVerificationError("version_mismatch");
   }
   try {

package/src/domain/editable-artifacts/snapshot-verifier-genesis.ts

@@ -1,4 +1,6 @@
 import { type BoundedImmutableObjectWritePort, BoundedObjectWriteError } from "@opengeni/storage";
+import { EDITABLE_ARTIFACT_CODEC_REGISTRY } from "@opengeni/contracts/editable-artifacts";
+import { COMMITTED_TRANSACTION_PROTOCOL_VERSION } from "@opengeni/contracts/editable-artifact-committed-transaction";
 import type { EditableArtifactGenesisPort } from "./ports";
 import {
   MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES,
@@ -173,6 +175,7 @@ function validateGeneratedGenesis(
   artifactId: EditableArtifactId,
   modality: EditableArtifactModality,
 ): void {
+  const currentCodec = EDITABLE_ARTIFACT_CODEC_REGISTRY[value.modality];
   if (
     value.scope.accountId !== scope.accountId ||
     value.scope.workspaceId !== scope.workspaceId ||
@@ -198,14 +201,13 @@ function validateGeneratedGenesis(
   }
   editableArtifactContentHash(value.canonicalContentHash);
   editableArtifactStateHash(value.stateHash);
-  const versions =
-    value.modality === "spreadsheet"
-      ? [value.modelSchemaVersion, value.operationProtocolVersion, value.crdtStateVersion]
-      : [value.modelSchemaVersion];
-  for (const version of versions) {
-    if (!Number.isSafeInteger(version) || version <= 0) {
-      throw new EditableArtifactSnapshotVerificationError("version_mismatch");
-    }
+  if (
+    value.modelSchemaVersion !== currentCodec.modelSchemaVersion ||
+    (value.modality === "spreadsheet" &&
+      (value.operationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
+        value.crdtStateVersion !== currentCodec.snapshotVersion))
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("version_mismatch");
   }
   try {
     assertBoundedKernelVersion(value.kernelVersion);

package/src/domain/editable-artifacts/snapshot-verifier.ts

@@ -7,7 +7,11 @@ import {
 } from "@opengeni/storage";
 import type { EditableArtifactSnapshotVerifierPort } from "./ports";
 import { decodeEditableArtifactSerializedCommit } from "@opengeni/contracts/editable-artifact-serialized-commit";
-import { EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES } from "@opengeni/contracts/editable-artifacts";
+import {
+  EDITABLE_ARTIFACT_CODEC_REGISTRY,
+  EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
+} from "@opengeni/contracts/editable-artifacts";
+import { COMMITTED_TRANSACTION_PROTOCOL_VERSION } from "@opengeni/contracts/editable-artifact-committed-transaction";
 import {
   causalFrontiersEqual,
   editableArtifactCausalFrontier,
@@ -520,6 +524,7 @@ function validateKernelResult(
       >
     | undefined,
 ): void {
+  const currentCodec = EDITABLE_ARTIFACT_CODEC_REGISTRY[snapshot.modality];
   if (
     result.canonicalReencodeVerified !== true ||
     result.modality !== snapshot.modality ||
@@ -542,8 +547,8 @@ function validateKernelResult(
     throw new EditableArtifactSnapshotVerificationError("state_hash_mismatch");
   }
   if (
-    result.modelSchemaVersion !== snapshot.modelSchemaVersion ||
-    result.kernelVersion !== snapshot.kernelVersion
+    snapshot.modelSchemaVersion !== currentCodec.modelSchemaVersion ||
+    result.modelSchemaVersion !== snapshot.modelSchemaVersion
   ) {
     throw new EditableArtifactSnapshotVerificationError("version_mismatch");
   }
@@ -559,6 +564,8 @@ function validateKernelResult(
       throw new EditableArtifactSnapshotVerificationError("frontier_mismatch");
     }
     if (
+      snapshot.operationProtocolVersion !== COMMITTED_TRANSACTION_PROTOCOL_VERSION ||
+      snapshot.crdtStateVersion !== currentCodec.snapshotVersion ||
       result.operationProtocolVersion !== snapshot.operationProtocolVersion ||
       result.crdtStateVersion !== snapshot.crdtStateVersion
     ) {

package/src/domain/environments.ts

@@ -1,5 +1,9 @@
 import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
-import type { AccessGrant, VariableSet } from "@opengeni/contracts";
+import {
+  variableSetVariableNameReservation,
+  type AccessGrant,
+  type VariableSet,
+} from "@opengeni/contracts";
 import { getVariableSet, recordAuditEvent, type Database } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
 import { requirePermission } from "../access";
@@ -11,40 +15,8 @@ export const MAX_VARIABLES_PER_ENVIRONMENT = 100;
 // collectGitIdentityEnvironment) plus loader/startup-injection vectors. These
 // can never be set as variable set variables, so the run-scoped
 // git auth block and git identity always win without silent collisions.
-const reservedExactNames = new Set([
-  "HOME",
-  "PATH",
-  "SHELL",
-  "USER",
-  "LOGNAME",
-  "TMPDIR",
-  "IFS",
-  "ENV",
-  "BASH_ENV",
-  "NODE_OPTIONS",
-  "PYTHONPATH",
-  "PYTHONSTARTUP",
-  "PERL5OPT",
-  "PERL5LIB",
-  "GH_TOKEN",
-  "GITHUB_TOKEN",
-  "GITLAB_TOKEN",
-  "AZURE_DEVOPS_EXT_PAT",
-  "GIT_ASKPASS",
-  "GIT_TERMINAL_PROMPT",
-]);
-
-const reservedPrefixes = [
-  "OPENGENI_",
-  "GIT_CONFIG_",
-  "GIT_AUTHOR_",
-  "GIT_COMMITTER_",
-  "LD_",
-  "DYLD_",
-];
-
 export function assertAllowedVariableSetVariableName(name: string): void {
-  if (reservedExactNames.has(name) || reservedPrefixes.some((prefix) => name.startsWith(prefix))) {
+  if (variableSetVariableNameReservation(name)) {
     throw new HTTPException(422, {
       message: `reserved variable set variable name / reserved environment variable name: ${name}`,
     });
@@ -69,10 +41,18 @@ export const requireEnvironmentEncryption = requireVariableSetEncryption;
 
 export async function requireVariableSetForApi(
   db: Database,
-  workspaceId: string,
+  grant: AccessGrant,
   variableSetId: string,
 ): Promise<VariableSet> {
-  const variableSet = await getVariableSet(db, workspaceId, variableSetId);
+  const variableSet = await getVariableSet(
+    db,
+    {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      subjectId: grant.subjectId,
+    },
+    variableSetId,
+  );
   if (!variableSet) {
     throw new HTTPException(404, { message: "variableSet not found" });
   }
@@ -80,10 +60,8 @@ export async function requireVariableSetForApi(
 }
 
 /**
- * Validates an variableSet attachment supplied in a request payload (session
- * create, scheduled task create/update, pack enable). Requires the
- * `variable-sets:use` permission unless the attachment was already authorized
- * (pack-installation-inherited attachments), and maps a missing or
+ * Validates a Variable Set attachment supplied in a session or task request.
+ * Requires attach and use permissions, and maps a missing or
  * cross-variable set to 422 because the id is payload, not the route
  * target. RLS plus the workspace_id clause make cross-workspace ids
  * indistinguishable from missing ones.
@@ -93,13 +71,15 @@ export async function validateVariableSetAttachment(
   grant: AccessGrant,
   workspaceId: string,
   variableSetId: string,
-  options: { preauthorized?: boolean } = {},
 ): Promise<VariableSet> {
   requireVariableSetEncryption(deps.settings);
-  if (!options.preauthorized) {
-    requirePermission(grant, "variable-sets:use");
-  }
-  const variableSet = await getVariableSet(deps.db, workspaceId, variableSetId);
+  requirePermission(grant, "variable-sets:attach");
+  requirePermission(grant, "variable-sets:use");
+  const variableSet = await getVariableSet(
+    deps.db,
+    { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
+    variableSetId,
+  );
   if (!variableSet) {
     throw new HTTPException(422, { message: "unknown variableSetId" });
   }

package/src/domain/external-creation-attribution.ts

@@ -0,0 +1,22 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+import { externalAttributionForAuthorization, type AccessGrantAuthorization } from "../access";
+
+export const EXTERNAL_CREATION_ATTRIBUTION_KEY = "opengeniExternalCreationAttribution";
+
+/** Retained alongside session.created metadata; this is not a live permission
+ * snapshot and must never authorize a follow-up, child, or scheduled turn. */
+export function externalCreationMetadata(
+  metadata: Record<string, unknown> | undefined,
+  authorization: AccessGrantAuthorization | undefined,
+  grant: AccessGrant,
+): Record<string, unknown> | undefined {
+  if (metadata && Object.hasOwn(metadata, EXTERNAL_CREATION_ATTRIBUTION_KEY)) {
+    throw new HTTPException(422, {
+      message: `${EXTERNAL_CREATION_ATTRIBUTION_KEY} is server-owned`,
+    });
+  }
+  const attribution = externalAttributionForAuthorization(authorization, grant);
+  if (!attribution) return metadata;
+  return { ...metadata, [EXTERNAL_CREATION_ATTRIBUTION_KEY]: attribution };
+}

package/src/domain/file-owner.ts

@@ -0,0 +1,67 @@
+import { requireLiveAgentAttemptAuthorization } from "../session-authorization";
+import {
+  freezeAgentLearningPolicy,
+  getSessionAuthorityProjection,
+  type SessionRlsActorContext,
+} from "@opengeni/db";
+import type { AccessGrant, Permission } from "@opengeni/contracts";
+import { requirePermission, type AccessGrantAuthorization } from "../access";
+import type { ApiRouteDeps } from "../dependencies";
+import { knowledgeContextForAccess } from "./knowledge";
+
+/** Personal original-file access follows verified ownership, never a subject-shaped bearer. */
+export async function fileOwnerContextForAccess(
+  deps: Pick<ApiRouteDeps, "db">,
+  access: AccessGrantAuthorization,
+  permission: Permission,
+): Promise<SessionRlsActorContext> {
+  if (access.grant.principalKind === "agent_attempt")
+    return fileOwnerContextForAgent(deps, access.grant, permission);
+  const context = await knowledgeContextForAccess(deps, access, permission);
+  if (context.actor.kind === "human")
+    return {
+      subjectId: context.actor.subjectId,
+      privateFileOwnerSubjectId: context.actor.subjectId,
+    };
+  return { subjectId: access.grant.subjectId, privateFileOwnerSubjectId: null };
+}
+
+/** Internal MCP/core callers can prove an agent attempt without inventing a human authorization. */
+export async function fileOwnerContextForAgent(
+  deps: Pick<ApiRouteDeps, "db">,
+  grant: AccessGrant,
+  permission: Permission,
+): Promise<SessionRlsActorContext> {
+  requirePermission(grant, permission);
+  const sessionId = grant.metadata?.sessionId;
+  if (grant.principalKind !== "agent_attempt" || typeof sessionId !== "string")
+    throw new Error("File access requires an exact agent attempt");
+  const attempt = await requireLiveAgentAttemptAuthorization(deps.db, grant, sessionId);
+  const snapshot = await freezeAgentLearningPolicy(deps.db, {
+    accountId: grant.accountId,
+    workspaceId: grant.workspaceId,
+    actor: {
+      kind: "agent",
+      sessionId,
+      turnId: attempt.turnId,
+      attemptId: attempt.attemptId,
+      executionGeneration: attempt.executionGeneration,
+    },
+  });
+  const sessionAuthority = await getSessionAuthorityProjection(
+    deps.db,
+    grant.workspaceId,
+    sessionId,
+  );
+  if (!sessionAuthority) throw new Error("File session authority unavailable");
+  return {
+    sessionAttachmentReadAccess: {
+      sessionId,
+      authorityEpoch: sessionAuthority.authorityEpoch,
+      actor: attempt,
+    },
+    subjectId: grant.subjectId,
+    initiatingHumanSubjectId: attempt.initiatingHumanSubjectId,
+    privateFileOwnerSubjectId: snapshot.defaultScope === "personal" ? snapshot.subjectId : null,
+  };
+}