@oddington/sdk 0.1.3 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 The importable client for Oddington apps, routines and response handlers.
 Node operations require Node.js 22.12.0 or later. The root import and hosted
-Data API work in browsers. Installing the package grants no authority.
+Data and Files APIs work in browsers. Installing the package grants no authority.
 
 ```sh
 npm install @oddington/sdk
@@ -29,6 +29,36 @@ session subscription. Workspace existence and member access are checked by the
 OS service. App modules use capability namespaces; routines and handlers receive
 runtime context without calling `os.init`.
 
+Create and recover a private immutable original through the same host context:
+
+```ts
+import { files } from '@oddington/sdk';
+
+const report = await files.create({
+  file: selectedFile, // Web File, path-backed Blob, Uint8Array or byte stream
+  name: 'September statement.csv',
+  path: 'HSC/2026/09',
+}, { requestKey: 'statement/2026/09' });
+const descriptor = await files.get(report.id);
+const response = await files.read(descriptor.id);
+await response.text(); // Also supports blob(), arrayBuffer() and body streaming.
+```
+
+Hosted Files retains remote originals only, with empty `enrichments`. It rejects
+`local`, `both` and explicit routine local preparation with `unsupported_context`.
+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;
+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,
+status and retryability without server details. Reads return the successful Web
+Response without consuming its body. Creation grants private creator access;
+workspace membership alone never grants another creator's File.
+
 Read a named repository through the authenticated host context:
 
 ```ts
@@ -62,13 +92,60 @@ Each graph selection sends one request and returns only selected canonical
 values, expanded forward links and exact opaque public versions. Cursors
 continue the exact retained artifact and collection selection, even after
 replacement; repeat its options and links while omitting unrelated collections.
-No automatic retry, separate version fetch, search, history or changes operation
-is included. Collection schemas omit Markdown storage hints.
+No automatic retry, separate version fetch, search or history operation is
+included. Collection schemas omit Markdown storage hints.
+
+`where` combines field conditions with AND. Alongside exact scalar/null equality
+and `$in`, declared one-valued `integer`, `number` and `date` fields accept
+`$gt`, `$gte`, `$lt` and `$lte`:
+
+```ts
+await general.records.select({ invoices: { $: { where: {
+  amount: { $gte: 10, $lte: 20 },
+  date: { $gte: '2026-10-01', $lt: '2026-11-01' },
+  month: { $gte: '2026-10', $lte: '2026-10' },
+}, count: true } } });
+```
+
+Supply one lower bound, one upper bound, or one of each. Bounds cannot combine
+`$gt` with `$gte`, `$lt` with `$lte`, or any bound with `$in`. Operands must be
+valid for the declared field, including numeric precision and real day/month
+dates; values are never coerced. Missing and null values never match bounds.
+A valid interval without matches returns an empty array and requested zero
+count. V0 types check expression structure; runtime schema validation owns field
+eligibility. Repeat the same bounds when continuing a cursor.
+
 `DataOperationError.code` distinguishes `context_unavailable`, `unauthenticated`,
 `access_denied`, `invalid_query`, `request_too_large`, `capacity` and `unavailable`.
-Only `capacity` and `unavailable` are retryable; an error never includes private
+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:
+
+```ts
+const changes = general.changes();
+changes.update(first.invoices[0], { amount: 30 });
+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: [] }`
+only after its exact index is ready. Later current reads discover that version.
+During `os routine run --local`, 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.
+
+`invalid_change` and known-unapplied `conflict` reject the batch.
+`publication_pending` is retryable and may report `uncertain` or `applied`;
+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.
+
 Bind a declared Airtable connection with `connections.airtable('project-management')`
 from the package root. Import and binding perform no network or credential work.
 The client exposes `tables.list()` and `records.list`, `get`, `create`, `update`

package/dist/index.js

@@ -691,8 +691,8 @@ function __awaiter(thisArg, _arguments, P, generator) {
         reject(e);
       }
     }
-    function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+    function step(result2) {
+      result2.done ? resolve(result2.value) : adopt(result2.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -1332,19 +1332,19 @@ var require_common = __commonJS((exports) => {
       }
     },
     flattenChunks: function(chunks) {
-      var i2, l, len, pos, chunk, result;
+      var i2, l, len, pos, chunk, result2;
       len = 0;
       for (i2 = 0, l = chunks.length;i2 < l; i2++) {
         len += chunks[i2].length;
       }
-      result = new Uint8Array(len);
+      result2 = new Uint8Array(len);
       pos = 0;
       for (i2 = 0, l = chunks.length;i2 < l; i2++) {
         chunk = chunks[i2];
-        result.set(chunk, pos);
+        result2.set(chunk, pos);
         pos += chunk.length;
       }
-      return result;
+      return result2;
     }
   };
   var fnUntyped = {
@@ -3130,11 +3130,11 @@ var require_strings = __commonJS((exports) => {
         return String.fromCharCode.apply(null, utils.shrinkBuf(buf, len));
       }
     }
-    var result = "";
+    var result2 = "";
     for (var i2 = 0;i2 < len; i2++) {
-      result += String.fromCharCode(buf[i2]);
+      result2 += String.fromCharCode(buf[i2]);
     }
-    return result;
+    return result2;
   }
   exports.buf2binstring = function(buf) {
     return buf2binstring(buf, buf.length);
@@ -7323,40 +7323,40 @@ var init_PDFContext = __esm(() => {
         types[_i - 1] = arguments[_i];
       }
       var preservePDFNull = types.includes(PDFNull_default);
-      var result = ref instanceof PDFRef_default ? this.indirectObjects.get(ref) : ref;
-      if (!result || result === PDFNull_default && !preservePDFNull)
+      var result2 = ref instanceof PDFRef_default ? this.indirectObjects.get(ref) : ref;
+      if (!result2 || result2 === PDFNull_default && !preservePDFNull)
         return;
       for (var idx3 = 0, len2 = types.length;idx3 < len2; idx3++) {
         var type = types[idx3];
         if (type === PDFNull_default) {
-          if (result === PDFNull_default)
-            return result;
+          if (result2 === PDFNull_default)
+            return result2;
         } else {
-          if (result instanceof type)
-            return result;
+          if (result2 instanceof type)
+            return result2;
         }
       }
-      throw new UnexpectedObjectTypeError(types, result);
+      throw new UnexpectedObjectTypeError(types, result2);
     };
     PDFContext2.prototype.lookup = function(ref) {
       var types = [];
       for (var _i = 1;_i < arguments.length; _i++) {
         types[_i - 1] = arguments[_i];
       }
-      var result = ref instanceof PDFRef_default ? this.indirectObjects.get(ref) : ref;
+      var result2 = ref instanceof PDFRef_default ? this.indirectObjects.get(ref) : ref;
       if (types.length === 0)
-        return result;
+        return result2;
       for (var idx3 = 0, len2 = types.length;idx3 < len2; idx3++) {
         var type = types[idx3];
         if (type === PDFNull_default) {
-          if (result === PDFNull_default)
-            return result;
+          if (result2 === PDFNull_default)
+            return result2;
         } else {
-          if (result instanceof type)
-            return result;
+          if (result2 instanceof type)
+            return result2;
         }
       }
-      throw new UnexpectedObjectTypeError(types, result);
+      throw new UnexpectedObjectTypeError(types, result2);
     };
     PDFContext2.prototype.getObjectRef = function(pdfObject) {
       var entries = Array.from(this.indirectObjects.entries());
@@ -15922,13 +15922,13 @@ var cx = 0, cy = 0, px = 0, py = 0, sx = 0, sy = 0, parameters, parse = function
     thArc -= 2 * Math.PI;
   }
   var segments = Math.ceil(Math.abs(thArc / (Math.PI * 0.5 + 0.001)));
-  var result = [];
+  var result2 = [];
   for (var i3 = 0;i3 < segments; i3++) {
     var th2 = th0 + i3 * thArc / segments;
     var th3 = th0 + (i3 + 1) * thArc / segments;
-    result[i3] = [xc, yc, th2, th3, rx, ry, sinTh, cosTh];
+    result2[i3] = [xc, yc, th2, th3, rx, ry, sinTh, cosTh];
   }
-  return result;
+  return result2;
 }, segmentToBezier = function(cx1, cy1, th0, th1, rx, ry, sinTh, cosTh) {
   var a00 = cosTh * rx;
   var a01 = -sinTh * ry;
@@ -15942,7 +15942,7 @@ var cx = 0, cy = 0, px = 0, py = 0, sx = 0, sy = 0, parameters, parse = function
   var y3 = cy1 + Math.sin(th1);
   var x2 = x3 + t * Math.sin(th1);
   var y2 = y3 - t * Math.cos(th1);
-  var result = [
+  var result2 = [
     a00 * x1 + a01 * y1,
     a10 * x1 + a11 * y1,
     a00 * x2 + a01 * y2,
@@ -15950,7 +15950,7 @@ var cx = 0, cy = 0, px = 0, py = 0, sx = 0, sy = 0, parameters, parse = function
     a00 * x3 + a01 * y3,
     a10 * x3 + a11 * y3
   ];
-  return result;
+  return result2;
 }, svgPathToOperators = function(path) {
   return apply(parse(path));
 };
@@ -21684,14 +21684,167 @@ var connections = createConnections(async (name, operation, input) => {
 class DataOperationError extends Error {
   code;
   retryable;
-  constructor(code, retryable = false) {
+  effect;
+  constructor(code, retryable = false, effect) {
     super(`Data operation failed: ${code}`);
     this.code = code;
     this.retryable = retryable;
+    this.effect = effect;
     this.name = "DataOperationError";
   }
 }
 
+// ../../shared/data-envelope.ts
+var DATA_REQUEST_LIMIT = 256 * 1024;
+var invalidChange = () => {
+  throw new DataOperationError("invalid_change", false, "unapplied");
+};
+function mapping(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    return invalidChange();
+  if (Reflect.ownKeys(value).some((key) => typeof key !== "string" || !Object.getOwnPropertyDescriptor(value, key)?.enumerable || !Object.hasOwn(Object.getOwnPropertyDescriptor(value, key), "value")))
+    return invalidChange();
+  return value;
+}
+function captureValue(value, ancestors = new Set, depth = 0) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (!value || typeof value !== "object" || ancestors.has(value) || depth > 32)
+    return invalidChange();
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > 1e5 || Object.keys(value).length !== value.length || Object.getOwnPropertySymbols(value).length)
+        return invalidChange();
+      return Array.from(value, (item) => captureValue(item, ancestors, depth + 1));
+    }
+    return Object.fromEntries(Object.entries(mapping(value)).map(([key, item]) => {
+      if (["__proto__", "constructor", "prototype"].includes(key))
+        return invalidChange();
+      return [key, captureValue(item, ancestors, depth + 1)];
+    }));
+  } finally {
+    ancestors.delete(value);
+  }
+}
+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)))
+    return invalidChange();
+  return { ref: identity.$ref, expectedVersion: identity.$version, set: captureValue(fields3) };
+}
+function captureDataUpdates(value) {
+  if (!Array.isArray(value) || !value.length || value.length > 1e4)
+    return invalidChange();
+  const updates = value.map((item) => {
+    const row = mapping(item);
+    if (Object.keys(row).sort().join(",") !== "expectedVersion,ref,set")
+      return invalidChange();
+    return captureDataUpdate({ $ref: row.ref, $version: row.expectedVersion }, row.set);
+  });
+  if (new Set(updates.map((update) => update.ref)).size !== updates.length)
+    return invalidChange();
+  return updates;
+}
+function checkDataRequestSize(input) {
+  if (new TextEncoder().encode(JSON.stringify(input)).byteLength > DATA_REQUEST_LIMIT)
+    throw new DataOperationError("request_too_large", false, "unapplied");
+}
+function dataTransportError(status, value) {
+  const failures = {
+    400: ["invalid_query", "invalid_change"],
+    401: ["unauthenticated"],
+    403: ["access_denied"],
+    409: ["conflict", "publication_pending"],
+    413: ["request_too_large"],
+    429: ["capacity"],
+    503: ["unavailable", "publication_pending"]
+  };
+  const error = value && typeof value === "object" && "error" in value ? value.error : undefined;
+  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);
+}
+
+// ../../shared/files-contract.ts
+class FileOperationError extends Error {
+  code;
+  status;
+  retryable;
+  constructor(code, status, retryable = false) {
+    super(code);
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+  }
+}
+var FILE_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function parseFileDescriptor(value) {
+  const invalid = () => {
+    throw new FileOperationError("unavailable", 503, true);
+  };
+  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))
+    return invalid();
+  const d = f.details;
+  if (d.kind === "other") {
+    if (Object.keys(d).length !== 1 || f.mediaType !== "application/octet-stream")
+      return invalid();
+  } else if (d.kind === "csv") {
+    if (Object.keys(d).sort().join(",") !== "dataRows,delimiter,encoding,headerRow,kind" || f.mediaType !== "text/csv" || !["utf-8", "windows-1252"].includes(d.encoding) || ![",", ";", "\t"].includes(d.delimiter) || !Number.isSafeInteger(d.headerRow) || d.headerRow < 1 || !Number.isSafeInteger(d.dataRows) || d.dataRows < 0)
+      return invalid();
+  } else
+    return invalid();
+  return f;
+}
+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);
+}
+function safeFilePath(value) {
+  return typeof value === "string" && value.length <= 1024 && value.split("/").every(safeFileName);
+}
+function parseFileCreateMetadata(value, maxBytes) {
+  const invalid = () => {
+    throw new FileOperationError("invalid_input", 400);
+  };
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return invalid();
+  const input = value;
+  if (Object.keys(input).some((key) => !["name", "path", "storage", "csv", "size", "requestKey"].includes(key)))
+    return invalid();
+  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")
+    return invalid();
+  if (!Number.isSafeInteger(input.size) || input.size < 0)
+    return invalid();
+  if (input.size > maxBytes)
+    throw new FileOperationError("request_too_large", 413);
+  if (typeof input.requestKey !== "string" || input.requestKey.length < 1 || input.requestKey.length > 256 || input.requestKey !== input.requestKey.trim() || /[\u0000-\u001f\u007f]/.test(input.requestKey))
+    return invalid();
+  let csv;
+  if (input.csv !== undefined) {
+    if (!input.csv || typeof input.csv !== "object" || Array.isArray(input.csv))
+      return invalid();
+    const hints = input.csv;
+    if (Object.keys(hints).some((key) => !["encoding", "delimiter", "headerRow"].includes(key)))
+      return invalid();
+    const encoding = hints.encoding === undefined ? "utf-8" : hints.encoding;
+    const delimiter = hints.delimiter === undefined ? "," : hints.delimiter;
+    const headerRow = hints.headerRow === undefined ? 1 : hints.headerRow;
+    if (encoding !== "utf-8" && encoding !== "windows-1252" || ![",", ";", "\t"].includes(delimiter) || !Number.isSafeInteger(headerRow) || headerRow < 1 || headerRow > 1e5)
+      return invalid();
+    csv = { encoding, delimiter, headerRow };
+  }
+  return { name: input.name, path, storage: "remote", ...csv ? { csv } : {}, size: input.size, requestKey: input.requestKey };
+}
+
 // ../../shared/os-origin.ts
 var DEFAULT_ORIGIN = "https://auth.oddington.ai";
 function oddingtonOrigin(environment = process.env) {
@@ -21703,14 +21856,6 @@ function oddingtonOrigin(environment = process.env) {
 }
 
 // src/routine-local-transport.ts
-var dataFailures = {
-  400: ["invalid_query"],
-  401: ["unauthenticated"],
-  403: ["access_denied"],
-  413: ["request_too_large"],
-  429: ["capacity"],
-  503: ["unavailable"]
-};
 function localRoutineRequest(environment = typeof process === "undefined" ? {} : process.env) {
   const {
     ODDINGTON_ROUTINE_LOCAL: mode,
@@ -21751,9 +21896,7 @@ function localRoutineRequest(environment = typeof process === "undefined" ? {} :
             const result = JSON.parse(Buffer.concat(chunks).toString());
             if (response.statusCode !== 200) {
               if (operation === "data/query") {
-                const received = result.error && typeof result.error === "object" && "code" in result.error ? result.error.code : undefined;
-                const code = dataFailures[response.statusCode ?? 0]?.find((allowed) => allowed === received) ?? "unavailable";
-                throw new DataOperationError(code, code === "capacity" || code === "unavailable");
+                throw dataTransportError(response.statusCode ?? 0, result);
               }
               throw new Error(typeof result.error === "string" ? result.error : "Local preparation failed");
             }
@@ -21799,6 +21942,34 @@ async function resolveDataContext() {
     throw new DataOperationError("context_unavailable");
   }
 }
+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 host = memberContext;
+    if (host) {
+      const context = await host();
+      if (!Number.isFinite(context.expiresAt) || context.expiresAt <= Date.now() || typeof context.accessToken !== "string" || !/^[^\s]{1,8192}$/.test(context.accessToken))
+        throw new Error;
+      return {
+        ...filesContext(context.workspace, context.endpoint, { authorization: `Bearer ${context.accessToken}` }),
+        isCurrent: context.isCurrent
+      };
+    }
+    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 });
+  } catch {
+    throw new FileOperationError("unsupported_context", 400);
+  }
+}
+function filesContext(workspace, endpoint, headers) {
+  if (!workspace || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(workspace) || workspace.length > 63 || ["auth", "www", "api", "os"].includes(workspace) || endpoint !== `https://${workspace}.oddington.ai`)
+    throw new Error;
+  return { url: `${endpoint}/api/files`, headers: { ...headers, "x-oddington-workspace": workspace }, isCurrent: () => true };
+}
 function checked(workspace, endpoint, headers) {
   if (!workspace || !/^[a-z0-9][a-z0-9-]{0,127}$/.test(workspace))
     throw new Error;
@@ -21809,19 +21980,12 @@ function checked(workspace, endpoint, headers) {
 }
 
 // src/data.ts
-var failures = {
-  400: ["invalid_query"],
-  401: ["unauthenticated"],
-  403: ["access_denied"],
-  413: ["request_too_large"],
-  429: ["capacity"],
-  503: ["unavailable"]
-};
 var data = {
   repository(repository) {
     async function send(input) {
       const context = await resolveDataContext();
       try {
+        checkDataRequestSize({ repository, ...input });
         if ("local" in context)
           return await context.local("data/query", { repository, ...input });
         const response = await fetch(context.url, {
@@ -21833,12 +21997,7 @@ var data = {
         });
         const result = await response.json();
         if (!response.ok) {
-          const error = result && typeof result === "object" && "error" in result ? result.error : undefined;
-          const received = error && typeof error === "object" && "code" in error ? error.code : undefined;
-          const code = failures[response.status]?.find((allowed) => allowed === received);
-          if (code)
-            throw new DataOperationError(code, code === "capacity" || code === "unavailable");
-          throw new DataOperationError("unavailable", true);
+          throw dataTransportError(response.status, result);
         }
         return result;
       } catch (error) {
@@ -21852,10 +22011,249 @@ var data = {
         list: () => send({ operation: "collections.list" }),
         schema: (name) => send({ operation: "collections.schema", name })
       },
-      records: { select: (query) => send({ operation: "records.select", query }) }
+      records: { select: (query) => send({ operation: "records.select", query }) },
+      changes() {
+        let updates = [], publicationId;
+        let pending, confirmed;
+        const snapshot = () => {
+          const captured = captureDataUpdates(updates);
+          checkDataRequestSize({
+            repository,
+            operation: "changes.publish",
+            updates: captured,
+            publicationId: publicationId ?? "00000000-0000-4000-8000-000000000000"
+          });
+          return captured;
+        };
+        return {
+          update(record2, set) {
+            if (publicationId)
+              throw new DataOperationError("invalid_change", false, "unapplied");
+            const next = [...updates, captureDataUpdate(record2, set)];
+            captureDataUpdates(next);
+            checkDataRequestSize({
+              repository,
+              operation: "changes.publish",
+              updates: next,
+              publicationId: "00000000-0000-4000-8000-000000000000"
+            });
+            updates = next;
+          },
+          async validate() {
+            await send({ operation: "changes.validate", updates: snapshot() });
+          },
+          publish() {
+            if (confirmed)
+              return Promise.resolve(structuredClone(confirmed));
+            if (!pending) {
+              let captured;
+              try {
+                captured = snapshot();
+              } catch (error) {
+                return Promise.reject(error);
+              }
+              publicationId ??= crypto.randomUUID();
+              pending = send({ operation: "changes.publish", updates: 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("unavailable", true, "uncertain");
+              }).finally(() => {
+                pending = undefined;
+              });
+            }
+            return pending.then((result) => structuredClone(result));
+          }
+        };
+      }
     };
   }
 };
+// src/files.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+var METADATA_BYTES = 4096;
+var RESULT_BYTES = 16 * 1024;
+var TIMEOUT_MS = 30000;
+var MAX_ACTIVE = 4;
+var ATTEMPTS = 2;
+var active = 0;
+var invalid = () => new FileOperationError("invalid_input", 400);
+var unavailable = () => new FileOperationError("unavailable", 503, true);
+var failures = {
+  400: ["invalid_input", "unsupported_context"],
+  401: ["unauthenticated"],
+  403: ["access_denied"],
+  405: ["method_not_allowed"],
+  409: ["conflict"],
+  413: ["request_too_large"],
+  429: ["capacity"],
+  503: ["integrity", "unavailable"]
+};
+async function boundedBytes(stream, limit) {
+  if (!stream)
+    return new Uint8Array;
+  const reader = stream.getReader();
+  const bytes = new Uint8Array(limit);
+  let size = 0;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      if (!(value instanceof Uint8Array))
+        throw invalid();
+      size += value.byteLength;
+      if (size > limit)
+        throw new FileOperationError("request_too_large", 413);
+      bytes.set(value, size - value.byteLength);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return bytes.slice(0, size);
+}
+async function timed(work, parent) {
+  const controller = new AbortController;
+  let timer;
+  let abort;
+  const expiry = new Promise((_, reject) => {
+    abort = () => {
+      controller.abort();
+      reject(unavailable());
+    };
+    timer = setTimeout(abort, TIMEOUT_MS);
+    parent?.addEventListener("abort", abort, { once: true });
+    if (parent?.aborted)
+      abort();
+  });
+  try {
+    return await Promise.race([work(controller.signal), expiry]);
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener("abort", abort);
+  }
+}
+async function result(response) {
+  try {
+    const bytes = await boundedBytes(response.body, RESULT_BYTES);
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw unavailable();
+  }
+}
+async function send(suffix, init, descriptor, initial, parent) {
+  const original = initial ?? await resolveFilesContext();
+  const checkCurrent = () => {
+    if (parent?.aborted)
+      throw unavailable();
+    if (!original.isCurrent())
+      throw new FileOperationError("unsupported_context", 400);
+  };
+  for (let attempt = 0;attempt < ATTEMPTS; attempt++) {
+    checkCurrent();
+    const context = attempt === 0 && !initial ? original : 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}`, {
+          ...init,
+          signal,
+          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 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)
+          throw unavailable();
+        checkCurrent();
+        if (!descriptor)
+          return response;
+        const file = parseFileDescriptor(await result(response));
+        if (file.size > MAX_BYTES)
+          throw unavailable();
+        checkCurrent();
+        return file;
+      }, parent);
+    } catch (error) {
+      const failure = error instanceof FileOperationError ? error : unavailable();
+      if (!failure.retryable || attempt + 1 === ATTEMPTS)
+        throw failure;
+    }
+  }
+  throw unavailable();
+}
+function idPath(id2) {
+  if (typeof id2 !== "string" || !FILE_ID_PATTERN.test(id2))
+    throw invalid();
+  return `/${id2}`;
+}
+var files = {
+  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")))
+      throw invalid();
+    const blob = input.file instanceof Blob;
+    const array2 = input.file instanceof Uint8Array;
+    const stream = input.file instanceof ReadableStream;
+    if (!blob && !array2 && !stream)
+      throw invalid();
+    const intrinsic = blob ? input.file.size : array2 ? input.file.byteLength : undefined;
+    if (intrinsic !== undefined && input.size !== undefined && input.size !== intrinsic)
+      throw invalid();
+    let name = input.name;
+    if (name === undefined && blob && "name" in input.file && typeof input.file.name === "string") {
+      name = typeof globalThis.File !== "undefined" && input.file instanceof globalThis.File ? input.file.name : input.file.name.split(/[\\/]/).at(-1);
+    }
+    const metadata = parseFileCreateMetadata({
+      name,
+      size: intrinsic ?? input.size,
+      path: input.path,
+      storage: input.storage,
+      csv: input.csv,
+      requestKey: options?.requestKey === undefined ? crypto.randomUUID() : options.requestKey
+    }, MAX_BYTES);
+    const header = encodeURIComponent(JSON.stringify(metadata));
+    if (new TextEncoder().encode(header).byteLength > METADATA_BYTES)
+      throw invalid();
+    if (active >= MAX_ACTIVE)
+      throw new FileOperationError("capacity", 429, true);
+    active++;
+    return timed(async (signal) => {
+      try {
+        const bytes = array2 ? input.file.slice() : await boundedBytes(blob ? input.file.stream() : input.file, metadata.size);
+        if (bytes.byteLength !== metadata.size)
+          throw invalid();
+        if (signal.aborted)
+          throw unavailable();
+        return await send("", {
+          method: "POST",
+          headers: { "content-type": "application/octet-stream", "x-oddington-file": header },
+          body: bytes.buffer
+        }, true, context, signal);
+      } finally {
+        active--;
+      }
+    }).catch((error) => {
+      throw error instanceof FileOperationError ? error : unavailable();
+    });
+  },
+  async get(id2) {
+    return send(idPath(id2), { method: "GET" }, true);
+  },
+  async read(id2) {
+    return send(`${idPath(id2)}/content`, { method: "GET" }, false);
+  }
+};
 // src/os.ts
 var installedDispose;
 function init({ auth }) {
@@ -21870,7 +22268,7 @@ function init({ auth }) {
       workspace = slug;
     }
   } catch {}
-  let active = true;
+  let active2 = true;
   let revision = 0;
   let person;
   const { data: { subscription } } = auth.onAuthStateChange((event, session) => {
@@ -21880,11 +22278,11 @@ function init({ auth }) {
     person = next;
   });
   const resolve = async () => {
-    if (!active || !endpoint || !workspace)
+    if (!active2 || !endpoint || !workspace)
       throw new Error("Hosted Data context unavailable.");
     const started = revision;
     const { data: { session }, error } = await auth.getSession();
-    if (!active || started !== revision || error || !session || person !== undefined && person !== session.user.id) {
+    if (!active2 || started !== revision || error || !session || person !== undefined && person !== session.user.id) {
       throw new Error("Hosted Data context unavailable.");
     }
     const expiresAt = (session.expires_at ?? 0) * 1000;
@@ -21892,13 +22290,19 @@ function init({ auth }) {
       throw new Error("Hosted Data context unavailable.");
     }
     person = session.user.id;
-    return { workspace, endpoint, accessToken: session.access_token, expiresAt };
+    return {
+      workspace,
+      endpoint,
+      accessToken: session.access_token,
+      expiresAt,
+      isCurrent: () => active2 && revision === started && person === session.user.id
+    };
   };
   const uninstall = installMemberContext(resolve);
   const dispose = () => {
-    if (!active)
+    if (!active2)
       return;
-    active = false;
+    active2 = false;
     revision++;
     subscription.unsubscribe();
     uninstall();
@@ -21932,7 +22336,7 @@ function routinePublicationClient(options = {}) {
   } : async () => {
     throw new Error("Member publication requires a host-supplied request");
   });
-  async function send(operation, body) {
+  async function send2(operation, body) {
     if (local)
       return await local(operation, body);
     const response = await request(`/api/cli/workspaces/${workspace}/inbox/${operation}`, {
@@ -21940,23 +22344,23 @@ function routinePublicationClient(options = {}) {
       headers: { "content-type": "application/json", ...headers },
       body: JSON.stringify(body)
     });
-    const result = await response.json();
+    const result2 = await response.json();
     if (!response.ok && operation === "records/update")
-      throw new RoutineRecordWriteError(result.error ?? "Could not confirm routine preparation", result.effect ?? "uncertain");
+      throw new RoutineRecordWriteError(result2.error ?? "Could not confirm routine preparation", result2.effect ?? "uncertain");
     if (!response.ok)
-      throw new Error(result.error ?? "Could not confirm routine publication");
-    return result;
+      throw new Error(result2.error ?? "Could not confirm routine publication");
+    return result2;
   }
   const transport = {
     async publish(body) {
-      return await send("publish", body);
+      return await send2("publish", body);
     },
     async resolve(body) {
-      await send("resolve", body);
+      await send2("resolve", body);
     }
   };
   async function readRecords(input) {
-    return await send("records/read", validateRecordRead(input));
+    return await send2("records/read", validateRecordRead(input));
   }
   return {
     ...createInboxPublisher(transport),
@@ -21966,17 +22370,17 @@ function routinePublicationClient(options = {}) {
       async writeRecords(input, options2) {
         if (!capability)
           throw new Error("A trusted routine launch is required");
-        return await send("records/update", validateRoutineRecordWrite({ input, requestKey: options2?.requestKey }));
+        return await send2("records/update", validateRoutineRecordWrite({ input, requestKey: options2?.requestKey }));
       },
       async updateRecords(input, options2) {
         if (!capability)
           throw new Error("A trusted routine launch is required");
-        return await send("records/update", validateRoutineRecordWrite({ input: validateRecordUpdate(input), requestKey: options2?.requestKey }));
+        return await send2("records/update", validateRoutineRecordWrite({ input: validateRecordUpdate(input), requestKey: options2?.requestKey }));
       },
       async deleteRecords(input, options2) {
         if (!capability)
           throw new Error("A trusted routine launch is required");
-        return await send("records/update", validateRoutineRecordWrite({ input: validateRecordDelete(input), requestKey: options2?.requestKey }));
+        return await send2("records/update", validateRoutineRecordWrite({ input: validateRecordDelete(input), requestKey: options2?.requestKey }));
       }
     },
     files: {
@@ -21998,14 +22402,14 @@ function routinePublicationClient(options = {}) {
           },
           body: Uint8Array.from(bytes).buffer
         });
-        const result = await response.json();
+        const result2 = await response.json();
         if (!response.ok)
-          throw new Error(result.error ?? "Could not retain file");
-        return await verifyInboxFile(bytes, validateInboxFile(result));
+          throw new Error(result2.error ?? "Could not retain file");
+        return await verifyInboxFile(bytes, validateInboxFile(result2));
       }
     },
     async check(body) {
-      await send("check", { requestKey: body.requestKey, item: validatePublication(body.item) });
+      await send2("check", { requestKey: body.requestKey, item: validatePublication(body.item) });
     }
   };
 }
@@ -22019,6 +22423,7 @@ export {
   recordBlock,
   question,
   os,
+  files,
   fileBlock,
   defineHandler,
   data,
@@ -22027,6 +22432,7 @@ export {
   asksBlock,
   RoutineRecordWriteError,
   InboxContractError,
+  FileOperationError,
   DataOperationError,
   AirtableOperationError
 };

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

@@ -13,10 +13,17 @@ 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 } 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 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 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>;
+    read(id: string): Promise<Response>;
+};
 /** The host's existing refreshing session source; supplies identity, never membership. */
 export type HostedSessionSource = {
     getSession(): Promise<{

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

@@ -44,10 +44,38 @@ export type CollectionSchema = CollectionSummary & {
     fields: PublicField[];
 };
 export type QueryScalar = string | number | boolean | null;
+type LowerBound = {
+    $gt: number | string;
+    $gte?: never;
+} | {
+    $gte: number | string;
+    $gt?: never;
+};
+type UpperBound = {
+    $lt: number | string;
+    $lte?: never;
+} | {
+    $lte: number | string;
+    $lt?: never;
+};
+export type RangeCondition = ((LowerBound & {
+    $lt?: never;
+    $lte?: never;
+}) | (UpperBound & {
+    $gt?: never;
+    $gte?: never;
+}) | (LowerBound & UpperBound)) & {
+    $in?: never;
+};
+export type QueryCondition = QueryScalar | RangeCondition | {
+    $in: QueryScalar[];
+    $gt?: never;
+    $gte?: never;
+    $lt?: never;
+    $lte?: never;
+};
 export type SelectionOptions = {
-    where?: Record<string, QueryScalar | {
-        $in: QueryScalar[];
-    }>;
+    where?: Record<string, QueryCondition>;
     fields?: string[];
     order?: Record<string, 'asc' | 'desc'>;
     limit?: number;
@@ -78,6 +106,19 @@ export type RecordsResult = {
     $meta: SelectionMetadata;
     [collection: string]: SelectedRecord[] | SelectionMetadata;
 };
+export type RecordIdentity = Pick<SelectedRecord, '$ref' | '$version'>;
+export type RecordUpdateSet = Record<string, DataValue>;
+export type DataPublication = {
+    version: string;
+    created: [];
+    updated: RecordIdentity[];
+    deleted: [];
+};
+export interface DataChangeSet {
+    update(record: RecordIdentity, set: RecordUpdateSet): void;
+    validate(): Promise<void>;
+    publish(): Promise<DataPublication>;
+}
 export interface DataRepository {
     collections: {
         list(): Promise<CollectionSummary[]>;
@@ -86,10 +127,14 @@ export interface DataRepository {
     records: {
         select(query: RecordsQuery): Promise<RecordsResult>;
     };
+    changes(): DataChangeSet;
 }
-export type DataErrorCode = 'context_unavailable' | 'unauthenticated' | 'access_denied' | 'invalid_query' | 'request_too_large' | 'capacity' | 'unavailable';
+export type DataErrorCode = 'context_unavailable' | 'unauthenticated' | 'access_denied' | 'invalid_query' | 'request_too_large' | 'capacity' | 'unavailable' | 'invalid_change' | 'conflict' | 'publication_pending';
+export type DataEffect = 'unapplied' | 'uncertain' | 'applied';
 export declare class DataOperationError extends Error {
     readonly code: DataErrorCode;
     readonly retryable: boolean;
-    constructor(code: DataErrorCode, retryable?: boolean);
+    readonly effect?: DataEffect | undefined;
+    constructor(code: DataErrorCode, retryable?: boolean, effect?: DataEffect | undefined);
 }
+export {};

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

@@ -0,0 +1,66 @@
+/** Provider-neutral authored contract. Registries and object locations stay server-side. */
+export type FileStorage = 'local' | 'remote' | 'both';
+export type FileInput = Blob | Uint8Array | ReadableStream<Uint8Array>;
+export type FileCsvHints = {
+    encoding?: 'utf-8' | 'windows-1252';
+    delimiter?: ',' | ';' | '\t';
+    headerRow?: number;
+};
+export type FileCreateInput = {
+    file: FileInput;
+    size?: number;
+    path?: string;
+    name?: string;
+    storage?: FileStorage;
+    csv?: FileCsvHints;
+};
+export type FileCreateOptions = {
+    requestKey?: string;
+};
+export type File = {
+    id: string;
+    name: string;
+    path: string;
+    mediaType: string;
+    size: number;
+    sha256: string;
+    enrichments: Record<string, {
+        mediaType: string;
+        size: number;
+        sha256: string;
+    }>;
+    details: {
+        kind: 'csv';
+        encoding: 'utf-8' | 'windows-1252';
+        delimiter: ',' | ';' | '\t';
+        headerRow: number;
+        dataRows: number;
+    } | {
+        kind: 'pdf';
+        pages?: number;
+    } | {
+        kind: 'other';
+    };
+};
+export type FileErrorCode = 'invalid_input' | 'unsupported_context' | 'unauthenticated' | 'access_denied' | 'request_too_large' | 'conflict' | 'integrity' | 'unavailable' | 'capacity' | 'method_not_allowed';
+export declare class FileOperationError extends Error {
+    readonly code: FileErrorCode;
+    readonly status: number;
+    readonly retryable: boolean;
+    constructor(code: FileErrorCode, status: number, retryable?: boolean);
+}
+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 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';
+    csv?: Required<FileCsvHints>;
+    size: number;
+    requestKey: string;
+};
+export declare function parseFileCreateMetadata(value: unknown, maxBytes: number): FileCreateMetadata;

package/package.json

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