ignotum 0.0.10 → 0.0.12

package/src/cli/build/server.ts

@@ -3,7 +3,18 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 
 import * as Config from "effect/Config";
-import { Array, Effect, FileSystem, Path, Predicate, Schema, String } from "effect";
+import {
+  Array,
+  Crypto,
+  Effect,
+  Encoding,
+  FileSystem,
+  Path,
+  Predicate,
+  Schema,
+  Stream,
+  String,
+} from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { createServer, defaultServerConditions, normalizePath } from "vite";
 import type { Plugin, ViteDevServer } from "vite";
@@ -11,7 +22,10 @@ import type { Plugin, ViteDevServer } from "vite";
 import {
   ServerBuildManifest,
   SchemaSnapshot,
+  SchemaSnapshotField,
+  EnvironmentArtifact,
   schemaSnapshotPath,
+  serverEnvironmentPath,
   type ServerFunctionArtifact,
 } from "@ignotum/contracts/deployment";
 import { FunctionAddress } from "@ignotum/contracts/runtime/sync";
@@ -19,7 +33,9 @@ import type { FunctionKind } from "@ignotum/contracts/runtime/functions";
 import {
   descriptorContainsFile,
   descriptorFields,
+  emptyEnv,
   getValueDescriptor,
+  isDefinedEnv,
   isDefinedSchema,
   ValueDescriptor,
   type DefinedSchema,
@@ -34,6 +50,7 @@ import {
 } from "@ignotum/deployment";
 
 import { inspectRuntimeFunctionDefinition } from "../../internal/function-definition.js";
+import { loadEnvironment } from "../environment.js";
 import { moduleBoundariesPlugin, BuildBoundaryViolation } from "../module-boundaries.js";
 import {
   causeMessage,
@@ -69,6 +86,11 @@ interface DiscoveredServerFunction {
 }
 
 const ServerDiscoveryManifest = Schema.Struct({
+  environment: Schema.Struct({
+    fields: Schema.Array(SchemaSnapshotField),
+    hasDefinition: Schema.Boolean,
+    values: Schema.Record(Schema.String, Schema.String),
+  }),
   functions: Schema.Array(DiscoveredServerFunction),
   schema: SchemaSnapshot,
 });
@@ -77,6 +99,10 @@ const ServerDiscoveryManifestJson = Schema.fromJsonString(ServerDiscoveryManifes
 const ServerModuleNamesJson = Schema.fromJsonString(Schema.Array(Schema.String));
 
 export interface ServerBuildResult {
+  readonly environment: {
+    readonly bytes: Uint8Array;
+    readonly path: typeof serverEnvironmentPath;
+  };
   readonly functions: number;
   readonly manifestPath: string;
 }
@@ -268,6 +294,7 @@ const discoverServerFunctionsInProcess = Effect.fn("Deploy.discoverServerFunctio
   return yield* Effect.scoped(
     Effect.gen(function* () {
       const server = yield* acquireModuleRunner(appDirectory, conditions);
+      const fileSystem = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const schemaPath = path.join(appDirectory, "server", "schema.ts");
       const loadedSchemaModule = yield* Effect.tryPromise({
@@ -295,14 +322,59 @@ const discoverServerFunctionsInProcess = Effect.fn("Deploy.discoverServerFunctio
           message: "The default export from server/schema.ts is not an Ignotum schema.",
         });
       }
+      const environmentPath = path.join(appDirectory, "server", "env.ts");
+      const hasEnvironmentDefinition = yield* fileSystem.exists(environmentPath);
+      const environment = hasEnvironmentDefinition
+        ? yield* Effect.gen(function* () {
+            const loadedEnvironmentModule = yield* Effect.tryPromise({
+              try: () => server.ssrLoadModule(normalizePath(environmentPath)),
+              catch: (cause) =>
+                ServerFunctionDiscoveryFailed.make({
+                  cause,
+                  message: "Could not load the application environment declaration.",
+                  path: environmentPath,
+                }),
+            });
+            if (
+              !Predicate.isObject(loadedEnvironmentModule.default) ||
+              !isDefinedEnv(loadedEnvironmentModule.default)
+            ) {
+              return yield* InvalidBuildOutput.make({
+                message: "The default export from server/env.ts is not an Ignotum environment.",
+              });
+            }
+            const loaded = yield* loadEnvironment(
+              appDirectory,
+              loadedEnvironmentModule.default,
+              true,
+            );
+            return {
+              fields: loadedEnvironmentModule.default.descriptors,
+              hasDefinition: true,
+              values: loaded.raw,
+            } as const;
+          })
+        : yield* loadEnvironment(appDirectory, emptyEnv, false).pipe(
+            Effect.map((loaded) => ({
+              fields: [],
+              hasDefinition: false,
+              values: loaded.raw,
+            })),
+          );
       const modules = yield* Effect.forEach(moduleNames, (moduleName) =>
         discoverModuleFunctions(server, appDirectory, moduleName),
       );
       return {
         functions: Array.flatten(modules),
+        environment,
         schema: schemaCandidate,
       } satisfies {
         readonly functions: ReadonlyArray<DiscoveredServerFunction>;
+        readonly environment: {
+          readonly fields: ReadonlyArray<SchemaSnapshotField>;
+          readonly hasDefinition: boolean;
+          readonly values: Readonly<Record<string, string>>;
+        };
         readonly schema: DefinedSchema<Tables>;
       };
     }),
@@ -312,9 +384,7 @@ const discoverServerFunctionsInProcess = Effect.fn("Deploy.discoverServerFunctio
 export const runServerDiscoveryWorker = Effect.fn("Deploy.runServerDiscoveryWorker")(function* (
   appDirectory: string,
   moduleNamesJson: string,
-  outputPath: string,
 ) {
-  const fileSystem = yield* FileSystem.FileSystem;
   const moduleNames = yield* Schema.decodeEffect(ServerModuleNamesJson)(moduleNamesJson).pipe(
     Effect.orDie,
   );
@@ -327,11 +397,11 @@ export const runServerDiscoveryWorker = Effect.fn("Deploy.runServerDiscoveryWork
         message: "The application schema does not have canonical Ignotum descriptors.",
       }),
   });
-  const encoded = yield* Schema.encodeEffect(ServerDiscoveryManifestJson)({
+  return yield* Schema.encodeEffect(ServerDiscoveryManifestJson)({
+    environment: discovered.environment,
     functions: discovered.functions,
     schema,
   });
-  yield* fileSystem.writeFileString(outputPath, encoded);
 });
 
 const discoveryWorkerEntry = Effect.fn("Deploy.discoveryWorkerEntry")(function* () {
@@ -365,7 +435,6 @@ const discoverServerFunctions = Effect.fn("Deploy.discoverServerFunctionsIsolate
         (temporary) =>
           fileSystem.remove(temporary, { force: true, recursive: true }).pipe(Effect.orDie),
       );
-      const outputPath = path.join(directory, "discovery.json");
       const encodedModuleNames = yield* Schema.encodeEffect(ServerModuleNamesJson)(moduleNames);
       const packageRoot = path.resolve(path.dirname(workerEntry), "../..");
       const workspaceProbes: Array<string> = [];
@@ -387,23 +456,25 @@ const discoverServerFunctions = Effect.fn("Deploy.discoverServerFunctionsIsolate
       const readPermissions = [
         appDirectory,
         nodeModulesDirectory(),
+        path.dirname(nodeModulesDirectory()),
         packageRoot,
         path.join(packageRoot, "node_modules"),
+        path.resolve(packageRoot, "../..", "node_modules"),
         ...workspaceProbes,
       ].map((allowedPath) => `--allow-fs-read=${allowedPath}`);
-      const exitCode = yield* spawner.exitCode(
+      const handle = yield* spawner.spawn(
         ChildProcess.make(
           process.execPath,
           [
             "--permission",
             "--allow-addons",
+            "--conditions=@ignotum/source",
             ...readPermissions,
             `--allow-fs-write=${directory}`,
             workerEntry,
             "__ignotum_discover_server",
             appDirectory,
             encodedModuleNames,
-            outputPath,
           ],
           {
             cwd: appDirectory,
@@ -414,9 +485,14 @@ const discoverServerFunctions = Effect.fn("Deploy.discoverServerFunctionsIsolate
             },
             stderr: "inherit",
             stdout: "ignore",
+            additionalFds: { fd3: { type: "output" } },
           },
         ),
       );
+      const [encoded, exitCode] = yield* Effect.all(
+        [Stream.mkString(Stream.decodeText(handle.getOutputFd(3))), handle.exitCode],
+        { concurrency: "unbounded" },
+      );
       if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
         return yield* ServerFunctionDiscoveryFailed.make({
           cause: new Error(`Discovery worker exited with code ${exitCode}.`),
@@ -424,13 +500,12 @@ const discoverServerFunctions = Effect.fn("Deploy.discoverServerFunctionsIsolate
           path: appDirectory,
         });
       }
-      const encoded = yield* fileSystem.readFileString(outputPath);
       return yield* Schema.decodeEffect(ServerDiscoveryManifestJson)(encoded).pipe(
         Effect.mapError((cause) =>
           ServerFunctionDiscoveryFailed.make({
             cause,
             message: "The isolated build process returned invalid application metadata.",
-            path: outputPath,
+            path: appDirectory,
           }),
         ),
       );
@@ -445,8 +520,8 @@ const serverFunctionEntryPlugin = (definition: DiscoveredServerFunction): Plugin
 import { invoke } from "ignotum/internal/host"
 import { ${definition.exportName} as definition } from ${encodeJavaScriptString(normalizePath(definition.modulePath))}
 
-export default async function handler(encodedRequest) {
-  return invoke(definition, JSON.parse(encodedRequest), call)
+export default async function handler(encodedRequest, encodedEnvironment) {
+  return invoke(definition, JSON.parse(encodedRequest), call, JSON.parse(encodedEnvironment))
 }
 `;
 
@@ -573,6 +648,15 @@ export const buildServer = Effect.fn("Deploy.buildServer")(function* (
   const path = yield* Path.Path;
   const conditions = yield* serverConditions();
   const discovered = yield* discoverServerFunctions(appDirectory, functionModules);
+  const crypto = yield* Crypto.Crypto;
+  const environmentArtifact = {
+    formatVersion: 1,
+    nonce: Encoding.encodeBase64Url(yield* crypto.randomBytes(32)),
+    values: discovered.environment.values,
+  } satisfies EnvironmentArtifact;
+  const environmentBytes = utf8Bytes(
+    `${encodeCanonical(EnvironmentArtifact, environmentArtifact)}\n`,
+  );
 
   yield* fileSystem.makeDirectory(outputDirectory, { recursive: true });
   const encodedSnapshot = encodeSchemaSnapshot(discovered.schema);
@@ -584,7 +668,11 @@ export const buildServer = Effect.fn("Deploy.buildServer")(function* (
     { concurrency: 4 },
   );
   const manifest = {
-    formatVersion: 2,
+    formatVersion: 3,
+    environment: {
+      artifact: yield* artifactReference(serverEnvironmentPath, environmentBytes),
+      fields: discovered.environment.fields,
+    },
     schema: yield* artifactReference(schemaSnapshotPath, snapshotBytes),
     functions,
   } satisfies ServerBuildManifest;
@@ -598,6 +686,7 @@ export const buildServer = Effect.fn("Deploy.buildServer")(function* (
   );
 
   return {
+    environment: { bytes: environmentBytes, path: serverEnvironmentPath },
     functions: functions.length,
     manifestPath,
   } satisfies ServerBuildResult;

package/src/cli/codegen.ts

@@ -41,6 +41,7 @@ const isFunctionModuleFile = (fileName: string): boolean =>
   !fileName.endsWith(".test.ts") &&
   !fileName.endsWith(".spec.ts") &&
   fileName !== "index.ts" &&
+  fileName !== "env.ts" &&
   fileName !== "schema.ts" &&
   !fileName.startsWith("_");
 
@@ -57,13 +58,13 @@ const moduleNameFromFile = (filePath: string, fileName: string) => {
   );
 };
 
-const renderServerBindings = (): string => `${generatedHeader}
+const renderServerBindings = (hasEnvironment: boolean): string => `${generatedHeader}
 
 import { bindSchema } from "ignotum/internal/server";
 
-import schema from "../server/schema.js";
+${hasEnvironment ? 'import environment from "../server/env.js";\n' : ""}import schema from "../server/schema.js";
 
-export const { mutation, query, values } = bindSchema(schema);
+export const { mutation, query, values } = bindSchema(schema${hasEnvironment ? ", environment" : ""});
 `;
 
 const renderTypes = (): string => `${generatedHeader}
@@ -157,6 +158,7 @@ export const generate = Effect.fn("Codegen.generate")(function* (appDirectory: s
   const path = yield* Path.Path;
   const serverDirectory = path.join(appDirectory, "server");
   const schemaPath = path.join(serverDirectory, "schema.ts");
+  const environmentPath = path.join(serverDirectory, "env.ts");
   const schemaExists = yield* fileSystem.exists(schemaPath);
 
   if (!schemaExists) {
@@ -167,13 +169,14 @@ export const generate = Effect.fn("Codegen.generate")(function* (appDirectory: s
   }
 
   const entries = yield* fileSystem.readDirectory(serverDirectory);
+  const hasEnvironment = yield* fileSystem.exists(environmentPath);
   const functionFiles = Array.sort(String.Order)(Array.filter(entries, isFunctionModuleFile));
   const functionModules = yield* Effect.forEach(functionFiles, (fileName) =>
     moduleNameFromFile(path.join(serverDirectory, fileName), fileName),
   );
   const outputs: ReadonlyArray<GeneratedOutput> = [
     {
-      content: renderServerBindings(),
+      content: renderServerBindings(hasEnvironment),
       path: path.join(appDirectory, "_generated", "server.ts"),
     },
     {

package/src/cli/control-client.ts

@@ -102,11 +102,12 @@ export class ControlClientUnavailable extends Schema.TaggedError<ControlClientUn
 ) {}
 
 export interface DeploymentUploadFile {
+  readonly bytes?: Uint8Array;
   readonly contentType: string;
   readonly path: string;
   readonly sha256: string;
   readonly size: number;
-  readonly sourcePath: string;
+  readonly sourcePath?: string;
 }
 
 interface ControlClientService {
@@ -168,6 +169,7 @@ export const deploymentUploadFiles = Effect.fn("ControlClient.deploymentUploadFi
   inventorySha256: string,
   inventorySize: number,
   buildDirectory: string,
+  memoryFiles: ReadonlyMap<string, Uint8Array> = new Map(),
 ) {
   const path = yield* Path.Path;
   return [
@@ -178,7 +180,18 @@ export const deploymentUploadFiles = Effect.fn("ControlClient.deploymentUploadFi
       size: inventorySize,
       sourcePath: path.join(buildDirectory, deploymentInventoryPath),
     },
-    ...inventory.files.map((file) => uploadFile(file, path.join(buildDirectory, file.path))),
+    ...inventory.files.map((file) => {
+      const bytes = memoryFiles.get(file.path);
+      return bytes === undefined
+        ? uploadFile(file, path.join(buildDirectory, file.path))
+        : {
+            bytes,
+            contentType: file.contentType,
+            path: file.path,
+            sha256: file.sha256,
+            size: file.size,
+          };
+    }),
   ];
 });
 
@@ -304,17 +317,26 @@ export const controlClientLayer = Layer.effect(
       deploymentId: DeploymentId,
       file: DeploymentUploadFile,
     ) {
-      const request = yield* HttpClientRequest.put(
+      const baseRequest = HttpClientRequest.put(
         endpoint(config.apiUrl, controlDeploymentFilePath(appId, deploymentId, file.path)),
       ).pipe(
         HttpClientRequest.setHeader(controlUploadHeaderNames.contentLength, String(file.size)),
         HttpClientRequest.setHeader(controlUploadHeaderNames.sha256, file.sha256),
-        HttpClientRequest.bodyFile(file.sourcePath, { contentType: file.contentType }),
-        Effect.provideService(FileSystem.FileSystem, fileSystem),
-        Effect.mapError((cause) =>
-          unavailable(`Deployment file '${file.path}' could not be opened.`, cause),
-        ),
       );
+      const request = yield* file.bytes === undefined
+        ? file.sourcePath === undefined
+          ? Effect.fail(unavailable(`Deployment file '${file.path}' has no upload source.`, {}))
+          : HttpClientRequest.bodyFile(baseRequest, file.sourcePath, {
+              contentType: file.contentType,
+            }).pipe(
+              Effect.provideService(FileSystem.FileSystem, fileSystem),
+              Effect.mapError((cause) =>
+                unavailable(`Deployment file '${file.path}' could not be opened.`, cause),
+              ),
+            )
+        : Effect.succeed(
+            HttpClientRequest.bodyUint8Array(baseRequest, file.bytes, file.contentType),
+          );
       const response = yield* executeIdempotent(request, DeploymentFileUploadResponse);
       return response.status;
     });

package/src/cli/deploy.ts

@@ -22,6 +22,7 @@ export interface DeploymentBuildResult {
   readonly inventory: DeploymentInventory;
   readonly inventoryBytes: Uint8Array;
   readonly outputDirectory: string;
+  readonly memoryFiles?: ReadonlyMap<string, Uint8Array>;
   readonly serverFunctions: number;
 }
 
@@ -119,13 +120,15 @@ export const buildDeploymentArtifact = Effect.fn("Deploy.buildArtifact")(functio
       const serverOutput = path.join(stagingDirectory, "server");
       const client = yield* buildClient(appDirectory, clientOutput);
       const server = yield* buildServer(appDirectory, serverOutput, codegen.functionModules);
-      const payloadFiles = yield* readArtifactDirectory(stagingDirectory);
+      const diskPayloadFiles = yield* readArtifactDirectory(stagingDirectory);
+      const payloadFiles = [...diskPayloadFiles, server.environment];
       const inventory = yield* makeDeploymentInventory(payloadFiles);
       yield* fileSystem.writeFile(
         path.join(stagingDirectory, deploymentInventoryPath),
         inventory.bytes,
       );
-      const artifactFiles = yield* readArtifactDirectory(stagingDirectory);
+      const diskArtifactFiles = yield* readArtifactDirectory(stagingDirectory);
+      const artifactFiles = [...diskArtifactFiles, server.environment];
       yield* validateDeploymentArtifact(artifactFiles);
       yield* Effect.logInfo("Built deployment artifact").pipe(
         Effect.annotateLogs({
@@ -140,6 +143,7 @@ export const buildDeploymentArtifact = Effect.fn("Deploy.buildArtifact")(functio
         clientAssets: client.assets,
         inventory: inventory.inventory,
         inventoryBytes: inventory.bytes,
+        memoryFiles: new Map([[server.environment.path, server.environment.bytes]]),
         outputDirectory: buildDirectory,
         serverFunctions: server.functions,
       } satisfies DeploymentBuildResult;
@@ -158,6 +162,7 @@ export const uploadDeployment = Effect.fn("Deploy.upload")(function* (
     inventorySha256,
     build.inventoryBytes.byteLength,
     build.outputDirectory,
+    build.memoryFiles,
   );
   const deployment = yield* control.beginDeployment(configuration.appId, build.inventory);
 

package/src/cli/environment.ts

@@ -0,0 +1,133 @@
+import { Array, ConfigProvider, Effect, FileSystem, Path, Schema } from "effect";
+
+import {
+  decodeDefinedEnvironment,
+  emptyEnv,
+  type DefinedEnv,
+  type EnvironmentType,
+} from "@ignotum/contracts/schema";
+
+export class EnvironmentConfigurationInvalid extends Schema.TaggedError<EnvironmentConfigurationInvalid>()(
+  "EnvironmentConfigurationInvalid",
+  {
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+export interface LoadedEnvironment<Environment extends DefinedEnv = DefinedEnv> {
+  readonly definition: Environment;
+  readonly raw: Readonly<Record<string, string>>;
+  readonly value: Readonly<EnvironmentType<Environment>>;
+}
+
+export interface RawEnvironment {
+  readonly path: string;
+  readonly raw: Readonly<Record<string, string>>;
+}
+
+const collectKeys = Effect.fn("Environment.collectKeys")(function* (
+  provider: ConfigProvider.ConfigProvider,
+  providerPath: ConfigProvider.Path = [],
+  nameParts: ReadonlyArray<string> = [],
+): Effect.fn.Return<ReadonlyArray<string>, ConfigProvider.SourceError, never> {
+  const node = yield* provider.load(providerPath);
+  if (node === undefined) return [];
+  const own = node._tag === "Value" || node.value !== undefined ? [nameParts.join("_")] : [];
+  if (node._tag === "Value") return own;
+  if (node._tag === "Array") {
+    const children = yield* Effect.forEach(Array.range(0, node.length - 1), (index) =>
+      collectKeys(provider, [...providerPath, index], [...nameParts, index.toString()]),
+    );
+    return [...own, ...Array.flatten(children)];
+  }
+  const children = yield* Effect.forEach(Array.fromIterable(node.keys), (key) =>
+    collectKeys(provider, [...providerPath, key], [...nameParts, key]),
+  );
+  return [...own, ...Array.flatten(children)];
+});
+
+const nodeValue = (node: ConfigProvider.Node | undefined): string | undefined =>
+  node?._tag === "Value" ? node.value : node?.value;
+
+export const readEnvironmentRaw = Effect.fn("Environment.readRaw")(function* (
+  appDirectory: string,
+  hasDefinition: boolean,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const environmentPath = path.join(appDirectory, ".env.ignotum");
+  const exists = yield* fileSystem.exists(environmentPath);
+  if (!hasDefinition && exists) {
+    return yield* EnvironmentConfigurationInvalid.make({
+      message: ".env.ignotum exists but server/env.ts does not define its variables.",
+      path: environmentPath,
+    });
+  }
+  if (!hasDefinition) {
+    return { path: environmentPath, raw: {} } satisfies RawEnvironment;
+  }
+  if (!exists) {
+    return yield* EnvironmentConfigurationInvalid.make({
+      message: "server/env.ts requires a project-root .env.ignotum file.",
+      path: environmentPath,
+    });
+  }
+
+  const provider = yield* ConfigProvider.fromDotEnv({
+    path: environmentPath,
+    preserveEmptyStrings: true,
+  }).pipe(
+    Effect.mapError(() =>
+      EnvironmentConfigurationInvalid.make({
+        message: "Ignotum could not read the project environment file.",
+        path: environmentPath,
+      }),
+    ),
+  );
+  const keys = yield* collectKeys(provider).pipe(
+    Effect.mapError(() =>
+      EnvironmentConfigurationInvalid.make({
+        message: "Ignotum could not inspect the project environment file.",
+        path: environmentPath,
+      }),
+    ),
+  );
+  const entries = yield* Effect.forEach(keys, (key) =>
+    provider.load([key]).pipe(
+      Effect.map((node) => [key, nodeValue(node)] as const),
+      Effect.mapError(() =>
+        EnvironmentConfigurationInvalid.make({
+          message: `Ignotum could not read environment variable '${key}'.`,
+          path: environmentPath,
+        }),
+      ),
+    ),
+  );
+  const raw = Object.fromEntries(
+    entries.flatMap(([key, value]) => (value === undefined ? [] : [[key, value] as const])),
+  );
+  return { path: environmentPath, raw } satisfies RawEnvironment;
+});
+
+export const loadEnvironment = Effect.fn("Environment.load")(function* (
+  appDirectory: string,
+  definition: DefinedEnv,
+  hasDefinition: boolean,
+) {
+  const loaded = yield* readEnvironmentRaw(appDirectory, hasDefinition);
+  if (!hasDefinition) {
+    return {
+      definition: emptyEnv,
+      raw: {},
+      value: Object.freeze({}),
+    } satisfies LoadedEnvironment<typeof emptyEnv>;
+  }
+  const raw = loaded.raw;
+  const value = yield* decodeDefinedEnvironment(definition, raw).pipe(
+    Effect.mapError((error) =>
+      EnvironmentConfigurationInvalid.make({ message: error.message, path: loaded.path }),
+    ),
+  );
+  return { definition, raw, value } satisfies LoadedEnvironment;
+});

package/src/client/files.ts

@@ -12,7 +12,7 @@ import {
   type FileValue,
 } from "@ignotum/contracts/schema/file";
 import { IdGenerator } from "@ignotum/shared/id";
-import { Effect, Predicate } from "effect";
+import { Effect, Predicate, Schema } from "effect";
 
 export const Files = {
   url: (file: FileValue): string => {
@@ -27,13 +27,19 @@ export const Files = {
 const formatByMime: Partial<Record<string, FileFormat>> = {};
 for (const format of fileFormats) formatByMime[fileMimeTypes[format]] = format;
 
+const MutationObject = Schema.ObjectKeyword.check(
+  Schema.makeFilter((value) => Object.prototype.toString.call(value) === "[object Object]", {
+    message: "Mutation objects must contain ordinary fields; built-in collections are unsupported.",
+  }),
+);
+
 const collectNativeFiles = (
   // oxlint-disable-next-line anti-slop/no-unknown-parameters -- This is the recursive parser for generated mutation arguments and native File values.
   value: unknown,
-  files: Array<File>,
+  files: Set<File>,
 ): void => {
   if (value instanceof File) {
-    files.push(value);
+    files.add(value);
     return;
   }
   if (isFileValue(value) || Predicate.isDate(value)) return;
@@ -42,7 +48,9 @@ const collectNativeFiles = (
     return;
   }
   if (!Predicate.isObject(value)) return;
-  for (const child of Object.values(value)) collectNativeFiles(child, files);
+  for (const child of Object.values(Schema.decodeSync(MutationObject)(value))) {
+    collectNativeFiles(child, files);
+  }
 };
 
 const replaceNativeFiles = (
@@ -72,36 +80,42 @@ export const prepareMutationArguments = Effect.fn("SyncClient.prepareMutationArg
   input: unknown,
 ) {
   const ids = yield* IdGenerator;
-  const native: File[] = [];
-  collectNativeFiles(input, native);
-  const unique = new Set(native);
-  if (unique.size > fileLimits.filesPerMutation) {
-    throw new Error(`A mutation may upload at most ${fileLimits.filesPerMutation} files.`);
-  }
-  const totalBytes = [...unique].reduce((total, file) => total + file.size, 0);
-  if (totalBytes > fileLimits.mutationBytes) {
-    throw new Error(`Mutation uploads may total at most ${fileLimits.mutationBytes} bytes.`);
-  }
+  const unique = yield* Effect.try(() => {
+    const files = new Set<File>();
+    collectNativeFiles(input, files);
+    if (files.size > fileLimits.filesPerMutation) {
+      throw new Error(`A mutation may upload at most ${fileLimits.filesPerMutation} files.`);
+    }
+    const totalBytes = [...files].reduce((total, file) => total + file.size, 0);
+    if (totalBytes > fileLimits.mutationBytes) {
+      throw new Error(`Mutation uploads may total at most ${fileLimits.mutationBytes} bytes.`);
+    }
+    return files;
+  });
   const replacements = new Map<File, FileValue>();
   const nativeFiles = new Map<FileId, File>();
   for (const file of unique) {
-    const format = formatByMime[file.type.toLowerCase()];
-    if (format === undefined) {
-      throw new Error(
-        `File '${file.name}' has unsupported media type '${file.type || "unknown"}'.`,
-      );
-    }
-    if (file.size === 0 || file.size > fileLimits.fileBytes) {
-      throw new Error(`File '${file.name}' must be between 1 and ${fileLimits.fileBytes} bytes.`);
-    }
-    if (new TextEncoder().encode(file.name).byteLength > fileLimits.filenameBytes) {
-      throw new Error(`File '${file.name}' has a filename that is too long.`);
-    }
+    const format = yield* Effect.try(() => {
+      const format = formatByMime[file.type.toLowerCase()];
+      if (format === undefined) {
+        throw new Error(
+          `File '${file.name}' has unsupported media type '${file.type || "unknown"}'.`,
+        );
+      }
+      if (file.size === 0 || file.size > fileLimits.fileBytes) {
+        throw new Error(`File '${file.name}' must be between 1 and ${fileLimits.fileBytes} bytes.`);
+      }
+      if (new TextEncoder().encode(file.name).byteLength > fileLimits.filenameBytes) {
+        throw new Error(`File '${file.name}' has a filename that is too long.`);
+      }
+      return format;
+    });
     const id = yield* ids.generate(FileId);
     replacements.set(file, makeFileValue(id, { format, name: file.name, size: file.size }));
     nativeFiles.set(id, file);
   }
-  const value = replaceNativeFiles(input, replacements);
+  const value =
+    unique.size === 0 ? input : yield* Effect.try(() => replaceNativeFiles(input, replacements));
   return {
     value,
     nativeFiles,
@@ -121,6 +135,8 @@ export const applyFileGrants = (
   grants: ReadonlyArray<FileGrant>,
   // oxlint-disable-next-line anti-slop/no-unknown-returns -- The traversal preserves the decoded query result shape while attaching private symbols.
 ): unknown => {
+  if (grants.length === 0) return value;
+
   const byId = new Map<FileId, string>();
   for (const grant of grants) {
     if (byId.has(grant.id)) throw new Error("A query file grant ID is duplicated.");