@oddington/sdk 0.1.3 → 0.1.5

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,84 @@ 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.
+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 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 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; 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. 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
@@ -51,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
@@ -62,13 +140,78 @@ 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.
 
+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();
+```
+
+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.
+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.
+
+`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 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.
 The client exposes `tables.list()` and `records.list`, `get`, `create`, `update`
@@ -105,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