@oddington/sdk 0.1.4 → 0.1.6

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
@@ -92,8 +140,41 @@ 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 or history operation is
-included. Collection schemas omit Markdown storage hints.
+There is no automatic retry or separate version fetch. History is not included.
+Collection schemas omit Markdown storage hints.
+
+Use bounded plain-text lookup to find full Records and guards:
+
+```ts
+const found = await general.records.search('acme overdue', {
+  collections: ['invoices'], limit: 20,
+});
+const searchedVersion = found.$meta.version;
+for (const { collection, record } of found.matches) {
+  console.log(collection, record.$ref, record.$version);
+}
+```
+
+Search sends one request. The trimmed query has 1–256 Unicode code points;
+case-insensitive whitespace-separated terms match stable refs and structured
+scalar values, including link refs and array values. Every term must match;
+field names and Markdown bodies are excluded. Omitted options search all
+accessible collections with a limit of 20. Supplied collections contain 1–16
+distinct accessible names; the integer limit is 1–100. Invalid queries or
+unsupported options fail with `invalid_query`. There is no cursor, count,
+projection, highlighting, embedding or historical version option.
+
+Matches have deterministic order and complete canonical Records. Empty matches
+succeed with the exact searched version. Members search latest published data;
+routines search their captured version, advancing only through their own
+publication. Immediate `os routine run` uses hosted search. During
+`os routine prepare`, search uses the same committed local Index as select,
+ignores dirty/untracked files and advances only to that run's exact proposed
+version after its own Changes publication. Validation does not advance reads;
+another publisher does not move the captured view. Search Records can supply
+guards for subsequent Changes. Missing or incomplete search data, including
+retained versions without it, fails retryably with `unavailable` without an
+alternate read path.
 
 `where` combines field conditions with AND. Alongside exact scalar/null equality
 and `$in`, declared one-valued `integer`, `number` and `date` fields accept
@@ -120,21 +201,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 +240,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 +281,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