@oddington/sdk 0.1.4 → 0.1.5

package/README.md

@@ -42,23 +42,71 @@ const report = await files.create({
 const descriptor = await files.get(report.id);
 const response = await files.read(descriptor.id);
 await response.text(); // Also supports blob(), arrayBuffer() and body streaming.
+const reading = await files.enrich({ file: report.id, name: 'read.md', content: readingMarkdown });
+await files.enrich({ file: report.id, name: 'extracted.json', content: JSON.stringify(extractedValue) });
+const current = await files.get(report.id); // Discover retained enrichment descriptors.
+const context = await files.read(current.id, ['read.md', 'extracted.json']);
+await context['read.md'].text();
+await context['extracted.json'].json(); // Each body is independently consumed.
+await files.enrich({ file: report.id, name: 'read.md', content: revisedMarkdown, replace: reading.sha256 });
+await files.upload(report.id); // Move a local File and every retained enrichment to remote storage.
 ```
 
-Hosted Files retains remote originals only, with empty `enrichments`. It rejects
-`local`, `both` and explicit routine local preparation with `unsupported_context`.
+Hosted Files retains remote originals and caller-produced named enrichments;
+`storage: 'local'` requires a managed CLI parent. Configure that parent with
+`ODDINGTON_FILES_ROOT` pointing to an empty or already OS-managed dedicated
+directory outside tracked Git content. `ODDINGTON_FILES_DEFAULT=local|remote`
+selects its default; without it, remote remains the default. Per-File `storage`
+overrides it. The root stays private to the parent. Local creation without a
+configured root fails with `unsupported_context`. Files have one durable home;
+`both` is invalid. Local retention establishes no hosted registration.
+Fresh runs recover the same creator's File by its request key, and verify
+retained bytes before returning a descriptor or content. A dead parent fails
+closed. `os routine prepare` seals checked local File references and defers
+new remote Files, their enrichments and explicit uploads until `os routine publish`; legacy Inbox
+file preparation remains additive. Existing hosted Files are read-only during
+preparation.
+`upload(id)` preserves the File descriptor, creator access and existing Source
+references. Local bytes remain authoritative until all remote objects verify;
+retrying a completed upload returns the same File. Later reads and enrichments
+follow remote storage; any remaining managed local bytes are disposable cache.
+An unreferenced local File is disclosed remotely only when explicitly uploaded
+or successfully published as a Source. An authorized hosted caller receives
+non-retryable `local_only` (409) until upload succeeds; unrelated callers receive
+`access_denied`.
 Unnamed inputs require a safe `name`; streams also require declared `size`.
 Blob and byte-array declarations must match their intrinsic size. Originals are
-bounded to 16 MiB, metadata to 4 KiB, and descriptor/error bodies to 16 KiB.
-Creates allow four concurrent buffered operations and a 30-second deadline;
+bounded to 16 MiB per object, metadata to 4 KiB, and descriptor/error bodies to 16 KiB.
+Operations share four concurrent slots and a 30-second deadline;
 transport retries at most once with the same prepared bytes and request key.
 Omitting a key generates one for that invocation. Supply a stable key to recover
 across processes or fresh routine runs. Caller inputs remain owned by the caller.
-Each request resolves current authority; routine Files calls go directly to the
-selected workspace's HTTPS OS host. `FileOperationError` exposes a bounded code,
+Each request resolves current authority; hosted routine Files calls use the
+selected workspace's HTTPS OS host, and managed calls use the authenticated
+private parent transport. `FileOperationError` exposes a bounded code,
 status and retryability without server details. Reads return the successful Web
-Response without consuming its body. Creation grants private creator access;
+Response without consuming its body. Local transfer is bounded and buffered
+before constructing that Response. Creation grants private creator access;
 workspace membership alone never grants another creator's File.
 
+`enrich` accepts a string encoded as UTF-8 or exact `Uint8Array` bytes, a safe
+flat filename, and an optional MIME hint. OS verifies text/Markdown/JSON or
+reduces the content to generic binary metadata; it performs no extraction or
+model work. The first enrichment atomically promotes the storage bundle while
+preserving original bytes, File identity, name, path and access. An identical
+retry returns the retained descriptor. Different content conflicts unless
+`replace` matches the current enrichment hash; repeating a completed replacement
+still succeeds with its preceding hash. There is no enrichment request key.
+
+`read(id)` returns the original; `read(id, name)` returns one enrichment.
+`read(id, names)` validates at most 16 distinct safe names, deduplicates repeats,
+and returns an object of unconsumed Responses after all reads succeed. An empty
+list returns an empty object in a valid runtime context. Missing authorized names
+return `invalid_input`; a failed keyed request cancels obtained bodies. Each name
+is read independently with fresh authority; there is no cross-name revision snapshot.
+Names cannot contain separators or use the reserved `original` basename with
+or without an extension. Enrichments share their parent File's access and retention.
+
 Read a named repository through the authenticated host context:
 
 ```ts
@@ -81,7 +129,7 @@ Binding is inert. Each operation resolves current workspace, endpoint and
 short-lived authority from the trusted app host or managed routine context.
 Customer calls cannot configure those values. Missing or expired context
 rejects; a named handle does not expand repository access. During explicit
-`os routine run --local`, the same calls use the matched checkout's committed
+`os routine prepare`, the same calls use the matched checkout's committed
 version through a private parent transport. Dirty files are ignored. An OS
 cache outside the checkout reuses derived data; reads require no remote access
 or preparation storage. Later accepted record effects advance the run's view
@@ -120,21 +168,37 @@ eligibility. Repeat the same bounds when continuing a cursor.
 For reads, only `capacity` and `unavailable` are retryable; an error never includes private
 server details. Server boundaries own query bounds and authorization.
 
-Guarded updates use the same handle in hosted and explicitly local routines:
+Schema-driven creates, guarded updates and guarded deletions use the same handle
+in immediate and prepared routines:
 
 ```ts
 const changes = general.changes();
+changes.create({
+  $ref: 'invoices/INV-124', $filing: { year: '2026' },
+  type: 'invoice', number: 'INV-124', status: 'draft', amount: 1200,
+});
 changes.update(first.invoices[0], { amount: 30 });
+changes.delete(first.invoices[1]);
 await changes.validate();
 const publication = await changes.publish();
 ```
 
-Preparation captures only the Record's `$ref`, `$version` and explicit set,
-without I/O. Validation checks the complete committed result without effects;
-publication repeats guarded validation and applies the whole update batch.
-Success returns `{ version, created: [], updated: [{ $ref, $version }], deleted: [] }`
+Creation captures a complete Record and stable `$ref`, without I/O or a caller
+path. OS resolves exactly one collection and its schema-declared filing path.
+Optional `$filing` supplies only unresolved named safe components and is never
+stored or returned as Record data; missing components reject by name. Updates
+capture only `$ref`, `$version` and explicit fields. Deletion captures only the
+selected `$ref` and `$version`. Links within the deletion set are allowed;
+schema-declared links from any committed Record outside it refuse the whole group,
+even if a proposed update removes that link. Validation checks the complete
+candidate graph without effects; publication repeats authoritative validation
+and applies every create/update/delete in one commit.
+Success returns `{ version, created: [{ $ref, $version }], updated: [{ $ref, $version }], deleted: [{ $ref, $version }] }`
 only after its exact index is ready. Later current reads discover that version.
-During `os routine run --local`, publication retains the exact proposal and
+Deleted identities keep their captured versions; deletion creates no new Record
+version or tombstone. A Source deletion removes only that guarded Record, retaining
+its File, enrichments and existing durable uses.
+During `os routine prepare`, publication retains the exact proposal and
 advances only run-local reads. `os routine publish` later applies and indexes
 that immutable proposal; unrelated staged and unstaged work is preserved.
 
@@ -143,8 +207,10 @@ that immutable proposal; unrelated staged and unstaged work is preserved.
 retry the same change set to reconcile its retained identity. A transport failure
 also keeps that identity. Concurrent publication calls coalesce, confirmed calls
 replay the result, and changed intent requires a new change set. Updates are
-bounded to 10,000 Records and the 256 KiB Data request limit. Create, delete,
-`$filing`, search and history are outside this supported Changes slice.
+bounded with creates and deletions to 10,000 total operations and the 256 KiB Data
+request limit, with one operation per ref. Search and history are outside this
+Changes slice. Source Records use ordinary schema rules; Data also validates OS
+File identity/access and registers durable uses from its exact ready artifact.
 
 Bind a declared Airtable connection with `connections.airtable('project-management')`
 from the package root. Import and binding perform no network or credential work.
@@ -182,8 +248,14 @@ The defaults read `ODDINGTON_ROUTINE_WORKSPACE`, `ODDINGTON_ROUTINE_RUN` and
 `ODDINGTON_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
 existing `workspace`, `capability` and `workingRoot` options. Runtime context
 provides authority; callers cannot select repository remotes or expand grants.
-The same calls prepare locally when launched with `os routine run --local`, and
-the CLI owns explicit publication and recovery of that prepared run.
+`os routine run` publishes as capabilities are called. The same calls prepare
+work when launched with `os routine prepare`, and `os routine publish` owns
+explicit publication and recovery of that prepared run. Preparation may contact
+OS for authentication and reads, and declared connections may contact their
+providers; it does not promise offline execution. Execution location and File
+storage are independent of the publication lifecycle. `os routine run --local`
+remains a deprecated compatibility alias for `os routine prepare` and prints
+the replacement command.
 
 Retain evidence with `inbox.files.add({ path: 'evidence.txt' })`. Paths stay within
 the invocation's working root and uploaded bytes are verified against the retained

package/dist/index.js

@@ -5985,9 +5985,9 @@ var init_errors = __esm(() => {
   }(Error);
   CorruptPageTreeError = function(_super) {
     __extends(CorruptPageTreeError2, _super);
-    function CorruptPageTreeError2(targetIndex, operation) {
+    function CorruptPageTreeError2(targetIndex, operation2) {
       var _this = this;
-      var msg = "Failed to " + operation + " at targetIndex=" + targetIndex + " due to corrupt page tree: It is likely that one or more 'Count' entries are invalid";
+      var msg = "Failed to " + operation2 + " at targetIndex=" + targetIndex + " due to corrupt page tree: It is likely that one or more 'Count' entries are invalid";
       _this = _super.call(this, msg) || this;
       return _this;
     }
@@ -21329,9 +21329,22 @@ function validateRecordDelete(value) {
 }
 function validateRecordChange(value) {
   const input = serializable(value);
-  if (Array.isArray(input?.records) && input.records.length && input.records.every((record) => !!record && typeof record === "object" && !Array.isArray(record) && !("set" in record) && !("fields" in record)))
-    return validateRecordDelete(input);
-  return validateRecordWrite(input);
+  if (!input || Array.isArray(input) || typeof input !== "object" || Object.keys(input).sort().join(",") !== "records,repository" || !validRepositoryAlias(input.repository) || !Array.isArray(input.records) || !input.records.length || input.records.length > 1e4 || new Set(input.records.map((record) => record?.ref)).size !== input.records.length || new TextEncoder().encode(JSON.stringify(input)).byteLength > RECORD_WRITE_INPUT_LIMIT)
+    throw new InboxContractError("Invalid record change batch");
+  const writes = [], deletes = [];
+  for (const record of input.records) {
+    if (!record || typeof record !== "object" || Array.isArray(record))
+      throw new InboxContractError("Invalid record change");
+    if ("set" in record || "fields" in record)
+      writes.push(record);
+    else
+      deletes.push(record);
+  }
+  if (writes.length)
+    validateRecordWrite({ repository: input.repository, records: writes });
+  if (deletes.length)
+    validateRecordDelete({ repository: input.repository, records: deletes });
+  return structuredClone(input);
 }
 function validateRoutineRecordWrite(value) {
   const body = serializable(value);
@@ -21685,11 +21698,13 @@ class DataOperationError extends Error {
   code;
   retryable;
   effect;
-  constructor(code, retryable = false, effect) {
+  component;
+  constructor(code, retryable = false, effect, component) {
     super(`Data operation failed: ${code}`);
     this.code = code;
     this.retryable = retryable;
     this.effect = effect;
+    this.component = component;
     this.name = "DataOperationError";
   }
 }
@@ -21727,14 +21742,20 @@ function captureValue(value, ancestors = new Set, depth = 0) {
     ancestors.delete(value);
   }
 }
+function captureDataDelete(record2) {
+  const identity = mapping(record2);
+  if (!validRecordRef(identity.$ref) || typeof identity.$version !== "string" || !identity.$version.length || identity.$version.length > 512)
+    return invalidChange();
+  return { ref: identity.$ref, expectedVersion: identity.$version };
+}
 function captureDataUpdate(record2, set) {
-  const identity = mapping(record2), fields3 = mapping(set);
-  if (!validRecordRef(identity.$ref) || typeof identity.$version !== "string" || !identity.$version.length || identity.$version.length > 512 || !Object.keys(fields3).length || Object.keys(fields3).some((key) => key.startsWith("$") || ["id", "type"].includes(key)))
+  const identity = captureDataDelete(record2), fields3 = mapping(set);
+  if (!Object.keys(fields3).length || Object.keys(fields3).some((key) => key.startsWith("$") || ["id", "type"].includes(key)))
     return invalidChange();
-  return { ref: identity.$ref, expectedVersion: identity.$version, set: captureValue(fields3) };
+  return { ...identity, set: captureValue(fields3) };
 }
-function captureDataUpdates(value) {
-  if (!Array.isArray(value) || !value.length || value.length > 1e4)
+function captureDataUpdates(value, allowEmpty = false) {
+  if (!Array.isArray(value) || !allowEmpty && !value.length || value.length > 1e4)
     return invalidChange();
   const updates = value.map((item) => {
     const row = mapping(item);
@@ -21746,6 +21767,46 @@ function captureDataUpdates(value) {
     return invalidChange();
   return updates;
 }
+function captureDataCreate(value) {
+  const row = mapping(value);
+  if (!validRecordRef(row.$ref) || Object.keys(row).some((key) => key.startsWith("$") && !["$ref", "$filing"].includes(key)))
+    return invalidChange();
+  const { $ref: ref, $filing, ...fields3 } = row;
+  let filing;
+  if ($filing !== undefined) {
+    const components = mapping($filing);
+    if (Object.entries(components).some(([name, value2]) => !/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name) || ["constructor", "prototype"].includes(name) || typeof value2 !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value2)))
+      return invalidChange();
+    filing = { ...components };
+  }
+  return { ref, fields: captureValue(fields3), ...filing ? { filing } : {} };
+}
+function captureDataChanges(updatesValue, createsValue = [], deletesValue = []) {
+  const updates = captureDataUpdates(updatesValue, true);
+  if (!Array.isArray(createsValue) || createsValue.length > 1e4)
+    return invalidChange();
+  const creates = createsValue.map((item) => {
+    const row = mapping(item);
+    if (Object.keys(row).some((key) => !["ref", "fields", "filing"].includes(key)) || !Object.hasOwn(row, "ref") || !Object.hasOwn(row, "fields"))
+      return invalidChange();
+    const fields3 = mapping(row.fields);
+    if (Object.keys(fields3).some((key) => key.startsWith("$")))
+      return invalidChange();
+    return captureDataCreate({ ...fields3, $ref: row.ref, ...Object.hasOwn(row, "filing") ? { $filing: row.filing } : {} });
+  });
+  if (!Array.isArray(deletesValue) || deletesValue.length > 1e4)
+    return invalidChange();
+  const deletes = deletesValue.map((item) => {
+    const row = mapping(item);
+    if (Object.keys(row).sort().join(",") !== "expectedVersion,ref")
+      return invalidChange();
+    return captureDataDelete({ $ref: row.ref, $version: row.expectedVersion });
+  });
+  const refs = [...updates, ...creates, ...deletes].map((item) => item.ref);
+  if (!refs.length || refs.length > 1e4 || new Set(refs).size !== refs.length)
+    return invalidChange();
+  return { updates, creates, deletes };
+}
 function checkDataRequestSize(input) {
   if (new TextEncoder().encode(JSON.stringify(input)).byteLength > DATA_REQUEST_LIMIT)
     throw new DataOperationError("request_too_large", false, "unapplied");
@@ -21764,7 +21825,7 @@ function dataTransportError(status, value) {
   const row = error && typeof error === "object" ? error : undefined;
   const code = failures[status]?.find((allowed) => allowed === row?.code) ?? "unavailable";
   const effect = ["unapplied", "uncertain", "applied"].includes(String(row?.effect)) ? row.effect : undefined;
-  return new DataOperationError(code, ["capacity", "unavailable", "publication_pending"].includes(code), code === "conflict" ? "unapplied" : effect);
+  return new DataOperationError(code, ["capacity", "unavailable", "publication_pending"].includes(code), code === "conflict" ? "unapplied" : effect, code === "invalid_change" && typeof row?.component === "string" && /^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(row.component) ? row.component : undefined);
 }
 
 // ../../shared/files-contract.ts
@@ -21787,7 +21848,7 @@ function parseFileDescriptor(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return invalid();
   const f = value;
-  if (Object.keys(f).sort().join(",") !== "details,enrichments,id,mediaType,name,path,sha256,size" || typeof f.id !== "string" || !FILE_ID_PATTERN.test(f.id) || !safeFileName(f.name) || !safeFilePath(f.path) || !Number.isSafeInteger(f.size) || f.size < 0 || typeof f.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(f.sha256) || !f.enrichments || typeof f.enrichments !== "object" || Array.isArray(f.enrichments) || Object.keys(f.enrichments).length !== 0 || !f.details || typeof f.details !== "object" || Array.isArray(f.details))
+  if (Object.keys(f).sort().join(",") !== "details,enrichments,id,mediaType,name,path,sha256,size" || typeof f.id !== "string" || !FILE_ID_PATTERN.test(f.id) || !safeFileName(f.name) || !safeFilePath(f.path) || !Number.isSafeInteger(f.size) || f.size < 0 || f.size > 16 * 1024 * 1024 || typeof f.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(f.sha256) || !f.enrichments || typeof f.enrichments !== "object" || Array.isArray(f.enrichments) || !f.details || typeof f.details !== "object" || Array.isArray(f.details))
     return invalid();
   const d = f.details;
   if (d.kind === "other") {
@@ -21798,8 +21859,42 @@ function parseFileDescriptor(value) {
       return invalid();
   } else
     return invalid();
+  for (const [name, descriptor] of Object.entries(f.enrichments)) {
+    if (!safeEnrichmentName(name))
+      return invalid();
+    parseEnrichmentDescriptor(descriptor);
+  }
+  if (new TextEncoder().encode(JSON.stringify(f)).byteLength > 16 * 1024)
+    return invalid();
   return f;
 }
+function parseEnrichmentDescriptor(value) {
+  const invalid = () => {
+    throw new FileOperationError("unavailable", 503, true);
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return invalid();
+  const d = value;
+  if (Object.keys(d).sort().join(",") !== "mediaType,sha256,size" || !["application/octet-stream", "text/plain", "text/markdown", "application/json"].includes(d.mediaType) || !Number.isSafeInteger(d.size) || d.size < 0 || d.size > 16 * 1024 * 1024 || typeof d.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(d.sha256))
+    return invalid();
+  return d;
+}
+function safeEnrichmentName(value) {
+  return safeFileName(value) && !/^original(?:\.|$)/i.test(value);
+}
+function parseFileEnrichMetadata(value, maxBytes) {
+  const invalid = () => {
+    throw new FileOperationError("invalid_input", 400);
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return invalid();
+  const d = value;
+  if (Object.keys(d).some((key) => !["name", "size", "mediaType", "replace"].includes(key)) || !safeEnrichmentName(d.name) || !Number.isSafeInteger(d.size) || d.size < 0 || d.mediaType !== undefined && (typeof d.mediaType !== "string" || d.mediaType.length > 255 || /[\u0000-\u001f\u007f]/.test(d.mediaType)) || d.replace !== undefined && (typeof d.replace !== "string" || !/^[0-9a-f]{64}$/.test(d.replace)))
+    return invalid();
+  if (d.size > maxBytes)
+    throw new FileOperationError("request_too_large", 413);
+  return d;
+}
 function safeFileName(value) {
   return typeof value === "string" && value.length > 0 && value.length <= 255 && value === value.trim() && value !== "." && value !== ".." && !/[\u0000-\u001f\u007f-\u009f/\\:*?"<>|]/u.test(value) && !/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/.test(value) && !/[. ]$/.test(value) && !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(value);
 }
@@ -21818,9 +21913,7 @@ function parseFileCreateMetadata(value, maxBytes) {
   const path = input.path === undefined ? "Files" : input.path;
   if (!safeFileName(input.name) || !safeFilePath(path))
     return invalid();
-  if (input.storage === "local" || input.storage === "both")
-    throw new FileOperationError("unsupported_context", 400);
-  if (input.storage !== undefined && input.storage !== "remote")
+  if (input.storage !== undefined && input.storage !== "remote" && input.storage !== "local")
     return invalid();
   if (!Number.isSafeInteger(input.size) || input.size < 0)
     return invalid();
@@ -21842,7 +21935,14 @@ function parseFileCreateMetadata(value, maxBytes) {
       return invalid();
     csv = { encoding, delimiter, headerRow };
   }
-  return { name: input.name, path, storage: "remote", ...csv ? { csv } : {}, size: input.size, requestKey: input.requestKey };
+  return {
+    name: input.name,
+    path,
+    ...input.storage ? { storage: input.storage } : {},
+    ...csv ? { csv } : {},
+    size: input.size,
+    requestKey: input.requestKey
+  };
 }
 
 // ../../shared/os-origin.ts
@@ -21856,6 +21956,21 @@ function oddingtonOrigin(environment = process.env) {
 }
 
 // src/routine-local-transport.ts
+function privateRoutineRequest(environment = typeof process === "undefined" ? {} : process.env) {
+  const prepared = ["ODDINGTON_ROUTINE_LOCAL", "ODDINGTON_ROUTINE_LOCAL_SOCKET", "ODDINGTON_ROUTINE_LOCAL_TOKEN"].some((key) => environment[key] !== undefined);
+  const managed = ["ODDINGTON_FILES_SOCKET", "ODDINGTON_FILES_TOKEN"].some((key) => environment[key] !== undefined);
+  if (!prepared && !managed)
+    return;
+  const socket = prepared ? environment.ODDINGTON_ROUTINE_LOCAL_SOCKET : environment.ODDINGTON_FILES_SOCKET;
+  const token = prepared ? environment.ODDINGTON_ROUTINE_LOCAL_TOKEN : environment.ODDINGTON_FILES_TOKEN;
+  const request = localRoutineRequest(prepared ? environment : {
+    ODDINGTON_ROUTINE_LOCAL: "1",
+    ODDINGTON_ROUTINE_LOCAL_SOCKET: socket,
+    ODDINGTON_ROUTINE_LOCAL_TOKEN: token
+  });
+  const isCurrent = () => prepared ? environment.ODDINGTON_ROUTINE_LOCAL === "1" && environment.ODDINGTON_ROUTINE_LOCAL_SOCKET === socket && environment.ODDINGTON_ROUTINE_LOCAL_TOKEN === token : environment.ODDINGTON_FILES_SOCKET === socket && environment.ODDINGTON_FILES_TOKEN === token;
+  return { request, isCurrent, identity: `private:${socket}` };
+}
 function localRoutineRequest(environment = typeof process === "undefined" ? {} : process.env) {
   const {
     ODDINGTON_ROUTINE_LOCAL: mode,
@@ -21865,11 +21980,11 @@ function localRoutineRequest(environment = typeof process === "undefined" ? {} :
   if (mode === undefined && socket === undefined && token === undefined)
     return;
   if (mode !== "1" || !socket || !token || !/^[0-9a-f]{64}$/.test(token))
-    throw new Error("Local preparation transport unavailable; nothing can publish");
+    throw new Error("Preparation transport unavailable; nothing can publish");
   const tcp = /^tcp:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(socket);
   const endpoint = tcp && tcp[0] === socket && Number(tcp[1]) <= 65535 ? { hostname: "127.0.0.1", port: Number(tcp[1]) } : socket.startsWith("/") && !socket.startsWith("//") && !socket.includes("\x00") ? { socketPath: socket } : undefined;
   if (!endpoint)
-    throw new Error("Local preparation transport unavailable; nothing can publish");
+    throw new Error("Preparation transport unavailable; nothing can publish");
   return async (operation, input) => {
     const { request } = await import("node:http");
     return await new Promise((resolve, reject) => {
@@ -21880,7 +21995,7 @@ function localRoutineRequest(environment = typeof process === "undefined" ? {} :
         headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
         timeout: 120000
       }, (response) => {
-        const chunks = [];
+        const bytes = Buffer.alloc(33554432);
         let size = 0;
         response.on("data", (chunk) => {
           size += chunk.length;
@@ -21888,17 +22003,37 @@ function localRoutineRequest(environment = typeof process === "undefined" ? {} :
             response.destroy();
             reject(new Error("Local result exceeds supported size"));
           } else
-            chunks.push(chunk);
+            bytes.set(chunk, size - chunk.length);
         });
         response.on("error", reject);
         response.on("end", () => {
           try {
-            const result = JSON.parse(Buffer.concat(chunks).toString());
+            const result = JSON.parse(bytes.subarray(0, size).toString());
             if (response.statusCode !== 200) {
+              if (operation === "files/request") {
+                const error = result.error;
+                const status = response.statusCode ?? 503;
+                const codes = [
+                  "invalid_input",
+                  "unsupported_context",
+                  "unauthenticated",
+                  "access_denied",
+                  "request_too_large",
+                  "conflict",
+                  "local_only",
+                  "integrity",
+                  "unavailable",
+                  "capacity",
+                  "method_not_allowed"
+                ];
+                if (error?.code && codes.includes(error.code))
+                  throw new FileOperationError(error.code, status, error.code === "capacity" || error.code === "unavailable");
+                throw new FileOperationError("unavailable", 503, true);
+              }
               if (operation === "data/query") {
                 throw dataTransportError(response.statusCode ?? 0, result);
               }
-              throw new Error(typeof result.error === "string" ? result.error : "Local preparation failed");
+              throw new Error(typeof result.error === "string" ? result.error : "Preparation failed");
             }
             resolve(result);
           } catch (error) {
@@ -21906,8 +22041,8 @@ function localRoutineRequest(environment = typeof process === "undefined" ? {} :
           }
         });
       });
-      call.on("error", () => reject(new Error("Local preparation transport unavailable; nothing was published")));
-      call.on("timeout", () => call.destroy(new Error("Local preparation timed out")));
+      call.on("error", () => reject(new Error("Preparation transport unavailable; nothing was published")));
+      call.on("timeout", () => call.destroy(new Error("Preparation timed out")));
       call.end(JSON.stringify(input));
     });
   };
@@ -21927,6 +22062,9 @@ async function resolveDataContext() {
     const local = localRoutineRequest();
     if (local)
       return { local };
+    const managed = privateRoutineRequest();
+    if (managed)
+      return { local: managed.request };
     const host = memberContext;
     if (host !== undefined) {
       const context = await host();
@@ -21945,8 +22083,14 @@ async function resolveDataContext() {
 async function resolveFilesContext() {
   try {
     const environment = typeof process === "undefined" ? {} : process.env;
-    if (["ODDINGTON_ROUTINE_LOCAL", "ODDINGTON_ROUTINE_LOCAL_SOCKET", "ODDINGTON_ROUTINE_LOCAL_TOKEN"].some((key) => environment[key] !== undefined))
-      throw new Error;
+    const local = privateRoutineRequest(environment);
+    if (local)
+      return {
+        url: local.identity,
+        headers: {},
+        isCurrent: local.isCurrent,
+        local: local.request
+      };
     const host = memberContext;
     if (host) {
       const context = await host();
@@ -21954,13 +22098,14 @@ async function resolveFilesContext() {
         throw new Error;
       return {
         ...filesContext(context.workspace, context.endpoint, { authorization: `Bearer ${context.accessToken}` }),
-        isCurrent: context.isCurrent
+        isCurrent: context.isCurrent,
+        local: undefined
       };
     }
     if (!/^[0-9a-f]{64}$/.test(environment.ODDINGTON_ROUTINE_RUN ?? ""))
       throw new Error;
     const workspace = environment.ODDINGTON_ROUTINE_WORKSPACE;
-    return filesContext(workspace, `https://${workspace}.oddington.ai`, { "x-oddington-run": environment.ODDINGTON_ROUTINE_RUN });
+    return { ...filesContext(workspace, `https://${workspace}.oddington.ai`, { "x-oddington-run": environment.ODDINGTON_ROUTINE_RUN }), local: undefined };
   } catch {
     throw new FileOperationError("unsupported_context", 400);
   }
@@ -22013,34 +22158,71 @@ var data = {
       },
       records: { select: (query) => send({ operation: "records.select", query }) },
       changes() {
-        let updates = [], publicationId;
+        let updates = [], creates = [], deletes = [], publicationId;
         let pending, confirmed;
         const snapshot = () => {
-          const captured = captureDataUpdates(updates);
+          const captured = captureDataChanges(updates, creates, deletes);
+          const input = {
+            updates: captured.updates,
+            ...captured.creates.length ? { creates: captured.creates } : {},
+            ...captured.deletes.length ? { deletes: captured.deletes } : {}
+          };
           checkDataRequestSize({
             repository,
             operation: "changes.publish",
-            updates: captured,
+            ...input,
             publicationId: publicationId ?? "00000000-0000-4000-8000-000000000000"
           });
-          return captured;
+          return input;
         };
         return {
+          create(record2) {
+            if (publicationId)
+              throw new DataOperationError("invalid_change", false, "unapplied");
+            const next = [...creates, captureDataCreate(record2)];
+            captureDataChanges(updates, next, deletes);
+            checkDataRequestSize({
+              repository,
+              operation: "changes.publish",
+              updates,
+              creates: next,
+              ...deletes.length ? { deletes } : {},
+              publicationId: "00000000-0000-4000-8000-000000000000"
+            });
+            creates = next;
+          },
           update(record2, set) {
             if (publicationId)
               throw new DataOperationError("invalid_change", false, "unapplied");
             const next = [...updates, captureDataUpdate(record2, set)];
-            captureDataUpdates(next);
+            captureDataChanges(next, creates, deletes);
             checkDataRequestSize({
               repository,
               operation: "changes.publish",
               updates: next,
+              ...creates.length ? { creates } : {},
+              ...deletes.length ? { deletes } : {},
               publicationId: "00000000-0000-4000-8000-000000000000"
             });
             updates = next;
           },
+          delete(record2) {
+            if (publicationId)
+              throw new DataOperationError("invalid_change", false, "unapplied");
+            const next = [...deletes, captureDataDelete(record2)];
+            captureDataChanges(updates, creates, next);
+            checkDataRequestSize({
+              repository,
+              operation: "changes.publish",
+              updates,
+              deletes: next,
+              ...creates.length ? { creates } : {},
+              publicationId: "00000000-0000-4000-8000-000000000000"
+            });
+            deletes = next;
+          },
           async validate() {
-            await send({ operation: "changes.validate", updates: snapshot() });
+            await send({ operation: "changes.validate", ...snapshot() });
           },
           publish() {
             if (confirmed)
@@ -22053,12 +22235,12 @@ var data = {
                 return Promise.reject(error);
               }
               publicationId ??= crypto.randomUUID();
-              pending = send({ operation: "changes.publish", updates: captured, publicationId }).then((result) => {
+              pending = send({ operation: "changes.publish", ...captured, publicationId }).then((result) => {
                 confirmed = structuredClone(result);
                 return result;
               }).catch((error) => {
                 if (error instanceof DataOperationError)
-                  throw new DataOperationError(error.code, error.retryable, error.effect ?? (["unavailable", "publication_pending"].includes(error.code) ? "uncertain" : "unapplied"));
+                  throw new DataOperationError(error.code, error.retryable, error.effect ?? (["unavailable", "publication_pending"].includes(error.code) ? "uncertain" : "unapplied"), error.component);
                 throw new DataOperationError("unavailable", true, "uncertain");
               }).finally(() => {
                 pending = undefined;
@@ -22086,7 +22268,7 @@ var failures = {
   401: ["unauthenticated"],
   403: ["access_denied"],
   405: ["method_not_allowed"],
-  409: ["conflict"],
+  409: ["conflict", "local_only"],
   413: ["request_too_large"],
   429: ["capacity"],
   503: ["integrity", "unavailable"]
@@ -22144,7 +22326,7 @@ async function result(response) {
   }
 }
 async function send(suffix, init, descriptor, initial, parent) {
-  const original = initial ?? await resolveFilesContext();
+  const original = initial;
   const checkCurrent = () => {
     if (parent?.aborted)
       throw unavailable();
@@ -22153,37 +22335,71 @@ async function send(suffix, init, descriptor, initial, parent) {
   };
   for (let attempt = 0;attempt < ATTEMPTS; attempt++) {
     checkCurrent();
-    const context = attempt === 0 && !initial ? original : await resolveFilesContext();
+    const context = await resolveFilesContext();
     checkCurrent();
     if (context.url !== original.url)
       throw new FileOperationError("unsupported_context", 400);
     try {
-      return await timed(async (signal) => {
-        const response = await fetch(`${context.url}${suffix}`, {
+      return await (async () => {
+        const response = context.local ? await (async () => {
+          const body = init.body instanceof ArrayBuffer ? new Uint8Array(init.body) : undefined;
+          let binary = "";
+          if (body)
+            for (let offset = 0;offset < body.length; offset += 8192)
+              binary += String.fromCharCode(...body.subarray(offset, offset + 8192));
+          const value2 = await context.local("files/request", {
+            suffix,
+            method: init.method,
+            headers: Object.fromEntries(new Headers(init.headers)),
+            ...body ? { bytes: btoa(binary) } : {}
+          });
+          if (value2.bytes !== undefined) {
+            if (value2.bytes.length > Math.ceil(MAX_BYTES / 3) * 4)
+              throw unavailable();
+            const data2 = atob(value2.bytes);
+            return new Response(Uint8Array.from(data2, (c) => c.charCodeAt(0)), { status: value2.status, headers: value2.headers });
+          }
+          return Response.json(value2.json, { status: value2.status, headers: value2.headers });
+        })() : await fetch(`${context.url}${suffix}`, {
           ...init,
-          signal,
+          signal: parent,
           headers: { ...context.headers, ...init.headers },
           redirect: "error",
           cache: "no-store"
         });
         if (!response.ok) {
-          const value = await result(response);
-          const error = value && typeof value === "object" && "error" in value ? value.error : undefined;
+          const value2 = await result(response);
+          const error = value2 && typeof value2 === "object" && "error" in value2 ? value2.error : undefined;
           const received = error && typeof error === "object" && "code" in error ? error.code : undefined;
           const code = failures[response.status]?.find((code2) => code2 === received);
           throw code ? new FileOperationError(code, response.status, code === "capacity" || code === "unavailable") : unavailable();
         }
-        if (response.status !== 200)
+        if (response.status !== 200) {
+          response.body?.cancel().catch(() => {});
           throw unavailable();
-        checkCurrent();
+        }
+        try {
+          checkCurrent();
+        } catch (error) {
+          response.body?.cancel().catch(() => {});
+          throw error;
+        }
         if (!descriptor)
           return response;
-        const file = parseFileDescriptor(await result(response));
-        if (file.size > MAX_BYTES)
-          throw unavailable();
+        const value = await result(response);
+        let parsed;
+        if (descriptor === "enrichment") {
+          if (!value || typeof value !== "object" || Array.isArray(value))
+            throw unavailable();
+          const { name, ...metadata } = value;
+          if (!safeEnrichmentName(name))
+            throw unavailable();
+          parsed = { name, ...parseEnrichmentDescriptor(metadata) };
+        } else
+          parsed = parseFileDescriptor(value);
         checkCurrent();
-        return file;
-      }, parent);
+        return parsed;
+      })();
     } catch (error) {
       const failure = error instanceof FileOperationError ? error : unavailable();
       if (!failure.retryable || attempt + 1 === ATTEMPTS)
@@ -22197,7 +22413,77 @@ function idPath(id2) {
     throw invalid();
   return `/${id2}`;
 }
+async function operation(work, initial, parent) {
+  const context = initial ?? await resolveFilesContext();
+  if (active >= MAX_ACTIVE)
+    throw new FileOperationError("capacity", 429, true);
+  active++;
+  return timed(async (signal) => {
+    try {
+      return await work(context, signal);
+    } finally {
+      active--;
+    }
+  }, parent).catch((error) => {
+    throw error instanceof FileOperationError ? error : unavailable();
+  });
+}
+function contentPath(id2, name) {
+  const path = idPath(id2);
+  if (name === undefined)
+    return `${path}/content`;
+  if (!safeEnrichmentName(name))
+    throw invalid();
+  return `${path}/enrichments/${encodeURIComponent(name)}/content`;
+}
+async function read(id2, names) {
+  const context = await resolveFilesContext();
+  idPath(id2);
+  if (names === undefined || typeof names === "string") {
+    const path = contentPath(id2, names);
+    return operation((context2, signal) => send(path, { method: "GET" }, false, context2, signal), context);
+  }
+  if (!Array.isArray(names))
+    throw invalid();
+  const distinct = [];
+  const seen = new Set;
+  for (const name of names) {
+    if (typeof name !== "string" || !safeEnrichmentName(name))
+      throw invalid();
+    if (seen.has(name))
+      continue;
+    if (seen.size === 16)
+      throw invalid();
+    seen.add(name);
+    distinct.push(name);
+  }
+  const paths = distinct.map((name) => contentPath(id2, name));
+  return timed(async (parent) => {
+    const responses = {};
+    try {
+      for (let i = 0;i < paths.length; i++) {
+        const response = await operation((context2, signal) => send(paths[i], { method: "GET" }, false, context2, signal), context, parent);
+        Object.defineProperty(responses, distinct[i], { value: response, enumerable: true });
+      }
+      if (!context.isCurrent())
+        throw new FileOperationError("unsupported_context", 400);
+      return responses;
+    } catch (error) {
+      for (const response of Object.values(responses))
+        response.body?.cancel().catch(() => {});
+      throw error;
+    }
+  });
+}
 var files = {
+  async upload(id2) {
+    return operation(async (context, signal) => {
+      const file = await send(`${idPath(id2)}/upload`, { method: "POST" }, true, context, signal);
+      if (file.id !== id2)
+        throw unavailable();
+      return file;
+    });
+  },
   async create(input, options) {
     const context = await resolveFilesContext();
     if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["file", "size", "path", "name", "storage", "csv"].includes(key)) || options !== undefined && (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some((key) => key !== "requestKey")))
@@ -22222,6 +22508,8 @@ var files = {
       csv: input.csv,
       requestKey: options?.requestKey === undefined ? crypto.randomUUID() : options.requestKey
     }, MAX_BYTES);
+    if (!context.local && metadata.storage === "local")
+      throw new FileOperationError("unsupported_context", 400);
     const header = encodeURIComponent(JSON.stringify(metadata));
     if (new TextEncoder().encode(header).byteLength > METADATA_BYTES)
       throw invalid();
@@ -22247,12 +22535,45 @@ var files = {
       throw error instanceof FileOperationError ? error : unavailable();
     });
   },
+  async enrich(input) {
+    const context = await resolveFilesContext();
+    if (!input || typeof input !== "object" || Array.isArray(input) || Object.keys(input).some((key) => !["file", "name", "content", "mediaType", "replace"].includes(key)) || typeof input.content !== "string" && !(input.content instanceof Uint8Array))
+      throw invalid();
+    const path = `${idPath(input.file)}/enrichments`;
+    if (typeof input.content === "string" ? input.content.length > MAX_BYTES : input.content.byteLength > MAX_BYTES)
+      throw new FileOperationError("request_too_large", 413);
+    return operation(async (context2, signal) => {
+      let bytes;
+      if (typeof input.content === "string") {
+        const buffer = new Uint8Array(Math.min(MAX_BYTES, input.content.length * 3));
+        const encoded = new TextEncoder().encodeInto(input.content, buffer);
+        if (encoded.read !== input.content.length)
+          throw new FileOperationError("request_too_large", 413);
+        bytes = buffer.slice(0, encoded.written);
+      } else
+        bytes = input.content.slice();
+      const metadata = parseFileEnrichMetadata({
+        name: input.name,
+        size: bytes.byteLength,
+        ...input.mediaType === undefined ? {} : { mediaType: input.mediaType },
+        ...input.replace === undefined ? {} : { replace: input.replace }
+      }, MAX_BYTES);
+      const header = encodeURIComponent(JSON.stringify(metadata));
+      if (new TextEncoder().encode(header).byteLength > METADATA_BYTES)
+        throw invalid();
+      const result2 = await send(path, { method: "POST", headers: {
+        "content-type": "application/octet-stream",
+        "x-oddington-enrichment": header
+      }, body: bytes.buffer }, "enrichment", context2, signal);
+      if (result2.name !== metadata.name)
+        throw unavailable();
+      return result2;
+    }, context);
+  },
   async get(id2) {
-    return send(idPath(id2), { method: "GET" }, true);
+    return operation((context, signal) => send(idPath(id2), { method: "GET" }, true, context, signal));
   },
-  async read(id2) {
-    return send(`${idPath(id2)}/content`, { method: "GET" }, false);
-  }
+  read
 };
 // src/os.ts
 var installedDispose;
@@ -22336,16 +22657,16 @@ function routinePublicationClient(options = {}) {
   } : async () => {
     throw new Error("Member publication requires a host-supplied request");
   });
-  async function send2(operation, body) {
+  async function send2(operation2, body) {
     if (local)
-      return await local(operation, body);
-    const response = await request(`/api/cli/workspaces/${workspace}/inbox/${operation}`, {
+      return await local(operation2, body);
+    const response = await request(`/api/cli/workspaces/${workspace}/inbox/${operation2}`, {
       method: "POST",
       headers: { "content-type": "application/json", ...headers },
       body: JSON.stringify(body)
     });
     const result2 = await response.json();
-    if (!response.ok && operation === "records/update")
+    if (!response.ok && operation2 === "records/update")
       throw new RoutineRecordWriteError(result2.error ?? "Could not confirm routine preparation", result2.effect ?? "uncertain");
     if (!response.ok)
       throw new Error(result2.error ?? "Could not confirm routine publication");

package/dist/types/packages/sdk/src/public.d.ts

@@ -13,16 +13,22 @@ export { AirtableOperationError } from '../../../shared/airtable-contract.js';
 export type { AirtableField, AirtableTable, AirtableRecord, AirtableListInput, AirtableGetInput, AirtableCreateInput, AirtableUpdateInput, AirtableDeleteInput, AirtableReceipt, AirtableWriteResult, AirtableClient, Connections } from '../../../shared/airtable-contract.js';
 export declare const connections: import('../../../shared/airtable-contract.js').Connections;
 export { DataOperationError } from '../../../shared/data-contract.js';
-export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordIdentity, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
+export type { DataRepository, DataErrorCode, PublicValueDefinition, PublicField, CollectionSummary, CollectionSchema, QueryScalar, SelectionOptions, RecordSelection, RecordsQuery, DataValue, SelectedRecord, SelectionMetadata, RecordsResult, RecordIdentity, RecordCreation, RecordUpdateSet, DataPublication, DataChangeSet, DataEffect } from '../../../shared/data-contract.js';
 export declare const data: {
     repository(name: string): import('../../../shared/data-contract.js').DataRepository;
 };
 export { FileOperationError } from '../../../shared/files-contract.js';
-export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions, FileErrorCode } from '../../../shared/files-contract.js';
+export type { File, FileInput, FileStorage, FileCreateInput, FileCreateOptions, FileEnrichment, FileEnrichOptions, FileEnrichResult, FileErrorCode } from '../../../shared/files-contract.js';
 export declare const files: {
     create(input: import('../../../shared/files-contract.js').FileCreateInput, options?: import('../../../shared/files-contract.js').FileCreateOptions): Promise<import('../../../shared/files-contract.js').File>;
     get(id: string): Promise<import('../../../shared/files-contract.js').File>;
+    upload(id: string): Promise<import('../../../shared/files-contract.js').File>;
+    enrich(input: import('../../../shared/files-contract.js').FileEnrichOptions): Promise<import('../../../shared/files-contract.js').FileEnrichResult>;
     read(id: string): Promise<Response>;
+    read(id: string, name: string): Promise<Response>;
+    read<const Names extends readonly string[]>(id: string, names: Names): Promise<{
+        [Name in Names[number]]: Response;
+    }>;
 };
 /** The host's existing refreshing session source; supplies identity, never membership. */
 export type HostedSessionSource = {

package/dist/types/shared/data-contract.d.ts

@@ -108,14 +108,23 @@ export type RecordsResult = {
 };
 export type RecordIdentity = Pick<SelectedRecord, '$ref' | '$version'>;
 export type RecordUpdateSet = Record<string, DataValue>;
+export type RecordCreation = {
+    $ref: string;
+    $filing?: Record<string, string>;
+    $version?: never;
+    $path?: never;
+    [field: string]: DataValue | undefined;
+};
 export type DataPublication = {
     version: string;
-    created: [];
+    created: RecordIdentity[];
     updated: RecordIdentity[];
-    deleted: [];
+    deleted: RecordIdentity[];
 };
 export interface DataChangeSet {
+    create(record: RecordCreation): void;
     update(record: RecordIdentity, set: RecordUpdateSet): void;
+    delete(record: RecordIdentity): void;
     validate(): Promise<void>;
     publish(): Promise<DataPublication>;
 }
@@ -135,6 +144,7 @@ export declare class DataOperationError extends Error {
     readonly code: DataErrorCode;
     readonly retryable: boolean;
     readonly effect?: DataEffect | undefined;
-    constructor(code: DataErrorCode, retryable?: boolean, effect?: DataEffect | undefined);
+    readonly component?: string | undefined;
+    constructor(code: DataErrorCode, retryable?: boolean, effect?: DataEffect | undefined, component?: string | undefined);
 }
 export {};

package/dist/types/shared/files-contract.d.ts

@@ -1,5 +1,5 @@
 /** Provider-neutral authored contract. Registries and object locations stay server-side. */
-export type FileStorage = 'local' | 'remote' | 'both';
+export type FileStorage = 'local' | 'remote';
 export type FileInput = Blob | Uint8Array | ReadableStream<Uint8Array>;
 export type FileCsvHints = {
     encoding?: 'utf-8' | 'windows-1252';
@@ -17,6 +17,21 @@ export type FileCreateInput = {
 export type FileCreateOptions = {
     requestKey?: string;
 };
+export type FileEnrichment = {
+    mediaType: string;
+    size: number;
+    sha256: string;
+};
+export type FileEnrichOptions = {
+    file: string;
+    name: string;
+    content: string | Uint8Array;
+    mediaType?: string;
+    replace?: string;
+};
+export type FileEnrichResult = FileEnrichment & {
+    name: string;
+};
 export type File = {
     id: string;
     name: string;
@@ -24,11 +39,7 @@ export type File = {
     mediaType: string;
     size: number;
     sha256: string;
-    enrichments: Record<string, {
-        mediaType: string;
-        size: number;
-        sha256: string;
-    }>;
+    enrichments: Record<string, FileEnrichment>;
     details: {
         kind: 'csv';
         encoding: 'utf-8' | 'windows-1252';
@@ -42,7 +53,7 @@ export type File = {
         kind: 'other';
     };
 };
-export type FileErrorCode = 'invalid_input' | 'unsupported_context' | 'unauthenticated' | 'access_denied' | 'request_too_large' | 'conflict' | 'integrity' | 'unavailable' | 'capacity' | 'method_not_allowed';
+export type FileErrorCode = 'invalid_input' | 'unsupported_context' | 'unauthenticated' | 'access_denied' | 'request_too_large' | 'conflict' | 'local_only' | 'integrity' | 'unavailable' | 'capacity' | 'method_not_allowed';
 export declare class FileOperationError extends Error {
     readonly code: FileErrorCode;
     readonly status: number;
@@ -52,13 +63,22 @@ export declare class FileOperationError extends Error {
 export declare const FILE_ID_PATTERN: RegExp;
 /** Treat descriptor transport as untrusted; no provider fields escape the boundary. */
 export declare function parseFileDescriptor(value: unknown): File;
+export declare function parseEnrichmentDescriptor(value: unknown): FileEnrichment;
+export declare function safeEnrichmentName(value: unknown): value is string;
+export type FileEnrichMetadata = {
+    name: string;
+    size: number;
+    mediaType?: string;
+    replace?: string;
+};
+export declare function parseFileEnrichMetadata(value: unknown, maxBytes: number): FileEnrichMetadata;
 export declare function safeFileName(value: unknown): value is string;
 export declare function safeFilePath(value: unknown): value is string;
 /** Private transport metadata: normalized material options exclude the request key and size declaration. */
 export type FileCreateMetadata = {
     name: string;
     path: string;
-    storage: 'remote';
+    storage?: FileStorage;
     csv?: Required<FileCsvHints>;
     size: number;
     requestKey: string;

package/dist/types/shared/record-write.d.ts

@@ -12,7 +12,11 @@ export type RecordDeleteRequest = {
     repository: string;
     records: RecordDelete[];
 };
-export type RecordChangeRequest = RecordWriteRequest | RecordDeleteRequest;
+export type RecordChange = RecordWrite | RecordDelete;
+export type RecordChangeRequest = {
+    repository: string;
+    records: RecordChange[];
+};
 export type RoutineRecordWriteRequest = {
     input: RecordChangeRequest;
     requestKey: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddington/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Oddington routine and response-handler SDK",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",