@oddington/sdk 0.1.37 → 0.1.39

package/README.md

@@ -4,13 +4,20 @@ The importable client for OS apps, routines and response handlers.
 Node operations require Node.js 22.12.0 or later. The root import and hosted
 Data and Files APIs work in browsers. Installing the package grants no authority.
 
+When developing OS alongside a customer repository, use the repository's
+[`dev:customer` helper](../../README.md) to run Bun tests and TypeScript checks
+against the built local SDK without changing the customer's released pin,
+lockfile or installed package. Build the SDK and CLI together first; the same
+helper can execute that built CLI from the customer checkout.
+
 Hosted Data and shared Files reach OS directly through `/api/data` and `/api/files`.
 Inbox owns workspace-hosted `/api/inbox/check`, `/api/inbox/publish`,
-`/api/inbox/resolve` and `/api/inbox/files`. Request-key recovery and captured
+`/api/inbox/resolve`. Request-key recovery and captured
 publication validation are internal behavior of these operations. Retrying the
 same key and content returns the original result; changed content conflicts.
-Existing Inbox-retained files remain separate from shared Files, with their
-original identities, bytes and audience. The SDK exposes no raw-credential API.
+Inbox File previews and downloads use package-root `files.read(fileId)` with
+current workspace access. Item visibility does not grant File access. The SDK
+exposes no raw-credential API.
 
 Hosted apps use `inbox.questions.list({ routines })` for `AnswerableQuestion[]`.
 Derive `routines` from the existing app declaration with
@@ -65,7 +72,7 @@ Each step runs at most once and returns `{ summary, data }`. Unknown or repeated
 steps fail the Run even if routine code catches the error; unreached steps are
 skipped. Omitted input normalizes to `{}`. A top-level schema can supply a validated
 immutable default with `.default(value)`, such as
-`schema.object({ files: schema.array(file(), { maxItems: 32 }) }).default({ files: [] })`.
+`schema.object({ files: schema.array(file()) }).default({ files: [] })`.
 Nested defaults are unsupported and rejected. Omitted steps permit no step call;
 omitted result permits no returned value. `file()` declares a complete OS File descriptor.
 Its optional `storage` selects local or remote placement and its optional `path`
@@ -87,7 +94,7 @@ this metadata when absent. Setup and safe inspection are documented in the
 
 With `access: { ai: true }`, `os.ai.generateText` returns non-empty `{ text }`.
 `os.ai.generateObject` returns `{ object }` validated against the requested
-`schema`, with its inferred type. An invalid answer throws `RoutineAIError`
+`schema`, with its inferred type. An invalid answer throws `AIError`
 with code `invalid_output`, a clear bounded `detail`, and the original final
 answer as optional `text` for routine-owned recovery. The text is bounded at
 256 KiB and excluded from the error message and ordinary JSON serialization.
@@ -95,20 +102,47 @@ The routine can inspect it explicitly, apply its own recovery rules, report
 an item failure and continue; it must not cast a rejected answer to the promised
 type. OS does not coerce, drop fields, repair or retry automatically.
 
+`generateObject` also accepts one exact outer Markdown code fence (empty or
+`json` language tag), then applies the same strict schema checks. It does not
+extract JSON from explanatory prose or repair the answer. `RoutineAIError`
+remains a compatibility alias of `AIError`, so existing `instanceof` checks work.
+
+Preserve safe AI error facts when reporting a per-document failure. Keep the
+original answer (`error.text`) out of step data, business records and logs:
+
+```ts
+import { AIError } from '@oddington/sdk';
+
+try {
+  const { object } = await os.ai.generateObject({ input, instructions, schema });
+  // Apply the routine's business validation before using the result.
+} catch (error) {
+  if (!(error instanceof AIError)) throw error;
+  return { status: 'unavailable', error: {
+    code: error.code, message: error.message,
+    ...(error.detail ? { detail: error.detail } : {}),
+  } };
+}
+```
+
 An AI call failure can be caught and handled without automatically failing the
 Run. Uncaught routine or step exceptions still fail execution, and outstanding
 AI calls drain before completion. The host retains authority, isolation,
 cancellation and byte limits. Local and remote Runs use the same API.
 
 The bounded grammar supports closed objects with required properties, arrays with
-an explicit `maxItems` from 1 to 64, booleans, strings (at most 4096 code points),
+an optional positive safe-integer `maxItems` business bound, booleans, strings (at most 4096 code points),
 finite numbers and safe integers with optional inclusive bounds, and Files.
+Omitting `maxItems` imposes no item-count ceiling; the complete serialized input
+still shares the Run's byte bound, including every File descriptor and other field.
 Definitions allow at most 64 steps, 64 total object properties across their schemas,
-and eight schema levels. Input, each step input, each summary, each detail value,
-and the result accept at most 256 KiB of UTF-8 serialized JSON, without truncation.
+and eight schema levels. Run input, each summary, each detail value, and the result
+accept at most 256 KiB of UTF-8 serialized JSON, without truncation. Step inputs
+remain closed, immutable JSON but have no separate byte ceiling because they are
+transient in-process values rather than transported or retained Run evidence.
 Across 64 steps, retained summary plus detail is at most 32 MiB, plus 512 KiB for
-Run input and result; step inputs are transient and individually bounded. Schema
-defaults share the input bound. Titles contain at most 256 UTF-16 code units;
+Run input and result. Schema defaults share the input bound. Titles contain at
+most 256 UTF-16 code units;
 access dimensions and response handlers each have at most 64 entries. Functions,
 accessors, sparse arrays, cycles and non-JSON values reject. The canonical routine
 ID is a bounded lowercase alphanumeric/hyphen name, independent of its directory.
@@ -252,7 +286,7 @@ Local Data selects from the Host's exact published index; a warm selection
 neither initiates nor waits for renewal or synchronous hosted authority checks.
 Local Files returns `unsupported_context` after checking context. Neither path
 falls back to hosted services. Local app routines use the same local execution
-and explicit publication lifecycle as the CLI.
+and live capability calls as the CLI.
 
 Apps can assess a declared routine without starting it:
 
@@ -268,19 +302,17 @@ const detail = await run.step('read'); // Inferred summary and data for this new
 const recent = await app.routines.receipts.runs.list();
 const saved = await app.routines.receipts.runs.get(recent[0].id);
 console.log(await saved.current());
-// await saved.publish(); // Only in response to an explicit publication action.
 ```
 
 The fixed build generates types from each routine definition; no app-authored
 contract map is needed. Descriptions combine safe structure with live readiness
 and connection availability. Starts validate the current definition and input;
-retained reads and publication recheck complete saved member/source/capability
-scope. No installation is needed. Bindings accept no endpoint, credential,
+retained local reads check the established session and saved Run ownership. No installation is needed. Bindings accept no endpoint, credential,
 command, path or configuration selector. A local app uses its live Local Host;
 a hosted app uses its existing member session and workspace context to reach
 the current remote Run owner through the same bindings. Operations reject with
 `AppRoutineError.reason`: `authority_unavailable`, `execution_unavailable`, or
-`invalid_input`. Starts and publications are not automatically retried. A
+`invalid_input`. Starts are not automatically retried. A
 disconnected watch ends and requires `current()`. History returns at most 20
 summaries without deleting older Runs. Each JSON value is bounded to 256 KiB.
 Transport envelopes allow 17 MiB per summary, 514 KiB per detail and 20 summaries
@@ -344,13 +376,18 @@ both shipped SDK inputs and every emitted helper, rejects unexpected inputs and
 imports, and retains the full credential/server/customer leak scan. Node retains
 the complete package-root exports; provider classes are never public.
 
-Current auth measurement is **171,346 minified bytes**, including **6,322 fixture
-bytes** and **165,024 SDK bytes**, with **45,466 total gzip bytes**. Current
-Data/Files fixture measures **47,254 total / 5,893 fixture / 41,361 SDK
-bytes**, with **14,906 total gzip bytes**. The shipped runtime now also carries
-the local Questions transport and transparent Local Host renewal.
-Both fit their explicitly reviewed ceilings: **42,000 SDK bytes** for the pinned
-Data/Files fixture and **166,000 SDK bytes** for the separately pinned auth fixture.
+Current auth measurement is **186,220 minified bytes**, including **8,189 fixture
+bytes** and **178,031 SDK bytes**, with **50,478 total gzip bytes**. Current
+Data/Files fixture measures **58,294 total / 7,204 fixture / 51,090 SDK
+bytes**, with **18,751 total gzip bytes**. The shipped runtime also carries
+the local Questions transport, transparent Local Host renewal, and bounded
+Data validation details and guidance.
+Both fit their explicitly reviewed ceilings: **64,000 SDK bytes** for the pinned
+Data/Files fixture and **256,000 SDK bytes** for the separately pinned auth fixture.
+The combined runtime includes validation guidance and local Data recovery
+without another dependency. These allowances leave room for ordinary feature growth while
+catching substantial size regressions. Dependency, compatibility and private-code
+audits remain separate checks.
 Those ceilings are fixed review decisions, not values regenerated from later
 measurements. The installed auth realm/host-handoff proof passes alongside the
 Node exports, declarations, tarball leak scan and browser compatibility audits.
@@ -364,17 +401,18 @@ bytes; generated helpers count toward the SDK. Gzip is diagnostic only.
 
 | Same named-import fixture | Legacy diagnostic | Current strict proof |
 | --- | ---: | ---: |
-| Total minified JavaScript bytes | 488,539 | 47,254 |
-| Fixture-attributed bytes | 5,954 | 5,893 |
-| SDK bytes | 482,585 | 41,361 |
-| Total gzip bytes | 198,612 | 14,906 |
+| Total minified JavaScript bytes | 488,539 | 58,294 |
+| Fixture-attributed bytes | 5,954 | 7,204 |
+| SDK bytes | 482,585 | 51,090 |
+| Total gzip bytes | 198,612 | 18,751 |
 
 The legacy diagnostic externalized three unresolved Node built-ins and failed
 browser compatibility. The current strict proof has no imports, shims or warnings
-and reduces SDK bytes by 91.4%. Its literal ceiling is **42,000 SDK bytes**:
-639 bytes of deliberately limited headroom. The reviewed measurement includes
+and reduces SDK bytes by 89.4%. Its literal ceiling is **64,000 SDK bytes**.
+The measurement includes
 the Local Host bootstrap, local Questions transport, transparent renewal and
-opaque browser-auth handoff that `os.init` must select at runtime. The verifier pins the fixture
+opaque browser-auth handoff that `os.init` must select at runtime, and bounded
+Data validation errors. The verifier pins the fixture
 hash and bundler version; changing either requires a reviewed measurement
 comparison. Future ceiling increases require explicit review of added browser
 capability and must never be automatically regenerated from an oversized output.
@@ -402,33 +440,29 @@ await files.enrich({ file: report.id, name: 'read.md', content: revisedMarkdown,
 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
-`OS_FILES_ROOT` pointing to an empty or already OS-managed dedicated
-directory outside tracked Git content. `OS_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 run <name>` stages newly created Files locally for that Run,
-including local-placement Files, and defers promotion, enrichments and explicit
-uploads until `os routine publish <run>`. Legacy Inbox file capture remains
-additive. Existing hosted Files are read-only during local execution.
-`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`.
+Hosted Files retains remote originals and caller-produced named enrichments.
+A managed local CLI parent stores local Files beneath the signed-in active
+workspace's `~/.os/<workspace>/files` root; callers cannot configure another
+root. Local Runs default new Files to local storage, hosted Runs to remote.
+An existing local or remote File keeps its placement. Every completed File has
+one workspace registry row, including local Files whose bytes stay on this
+device. Request-key replay and reusable enrichments preserve the same identity
+across member calls, Runs and restarts.
+
+Explicit remote creation, upload and enrichment complete during their calls.
+`upload(id)` verifies the original and every enrichment before changing the same
+File's placement; retrying a completed upload returns that File. Later reads
+and enrichments follow its pinned remote store. A Source reference leaves a
+local File local. Inbox publication uploads that same File before exposing the
+Ask or Digest. Completed effects survive later Run failure. A runtime without
+the local bytes reports `local_only` (409).
 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.
+bounded to 5 GiB per original and 16 MiB per enrichment. Large originals stream
+through bounded multipart transfers; local writes and reads use bounded disk
+buffers. Operations share four concurrent slots and idle/request deadlines;
+later calls wait in invocation order without reading caller content, and
+transport retries preserve the same 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
@@ -441,24 +475,10 @@ versus received size. Streaming rejection marks partial received counts with
 failure evidence without raw names, keys, file content or provider text. Older
 errors without `detail` remain valid. 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.
-
-`await files.delete(fileId)` removes an unreferenced File's original and all
-retained enrichments under its current member or installed-routine creator.
-It returns `void` only after physical cleanup and durable completion; a completed
-retry succeeds. Independent retention returns `conflict` without changing the
-File. `access_denied` and `integrity` remain terminal; `unavailable` and
-`capacity` are retryable. Pending deletion denies reads, writes, new uses and
-creation-key replay while the same current creator retries cleanup. Deletion
-uses the authenticated parent for managed local Files and uploaded caches.
-R2 cleanup verifies the registered immutable key and native revision, removes
-only that object and confirms absence. Each physical writer owns a distinct
-candidate key, so a delayed writer cannot recreate the deleted representation.
-Pending admission is never success.
-When a completion reply is lost, retry `files.delete` with the same File ID and
-current creator authority. Keep stable creation keys separate from deletion
-recovery: a completed deleted key is denied and cannot recreate the File.
+before constructing that Response. Current workspace members can use every File in that workspace. A
+routine's `files: "read"` permits get/read; `files: "read-write"` also permits
+create/enrich/upload. References in Sources, Runs and Inbox items grant no
+additional access. Files has no public delete operation.
 
 `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
@@ -491,7 +511,7 @@ const changes = data.repository('general').changes();
 changes.create({ ...statement, added: '2026-10-20' });
 changes.create({ $ref: 'transactions/one',
   sources: [source.csv.row(statement.$ref, parsedTransaction.recordPosition)] });
-await changes.publish();
+await changes.apply();
 ```
 
 The caller's CSV parser supplies `recordPosition` from the retained statement:
@@ -508,7 +528,12 @@ guarded Data update. Known objects match by OS File ID, Gmail connection/message
 attachment, or Dropbox connection/File ID; newer Locations replace old path,
 revision and URL facts. Distinct objects and custom provider values remain.
 Helpers need no initialization and perform no I/O, choose no ref, and add no
-changes. File retention and Data validation/publication remain explicit.
+changes. File retention and Data validation/application remain explicit.
+
+File Sources use the OS-defined fields `filename`, `media_type`, `size_bytes`,
+and `sha256`. Keep the customer repository's Source schema aligned with this
+definition when updating it. `mime_type` is not an alias for `media_type`;
+do not rename a field produced by `source.file()` to fit an incompatible schema.
 
 Microsoft helpers are also exported at the package root, with the corresponding
 `OutlookSourceLocation` and `SharePointSourceLocation` types:
@@ -526,7 +551,7 @@ const itemLocation = source.location.sharepoint({
 
 Construct these only after successful provider reads establish the coordinates
 for the retained bytes, and save them alongside `source.location.os(file)` using
-ordinary Data publication. Request `Prefer: IdType="ImmutableId"` consistently
+an ordinary Data apply. Request `Prefer: IdType="ImmutableId"` consistently
 when obtaining Outlook message and attachment IDs. These IDs are case-sensitive
 and survive folder moves within the same mailbox, but not archive-mailbox moves
 or export/reimport. Subjects, filenames and `internetMessageId` are not substitutes.
@@ -570,12 +595,11 @@ 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
-`os routine run <name>`, 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
-to their exact proposed version. Login, installed grants and provider authority
-retain their normal checks. A dead local parent fails without hosted fallback.
+`os routine run <name>`, the same calls read current schema-governed Markdown
+in the trusted checkout, including staged, modified and untracked Records. Each
+operation reads the files as it begins. Later calls see completed writes and
+external edits. Current local Data acquires no hosted binding or index. A dead
+local parent fails without hosted fallback.
 
 Each graph selection sends one request and returns only selected canonical
 values, expanded forward links and exact opaque public versions. Cursors
@@ -632,7 +656,9 @@ use `select` for a manual `after` cursor or explicit historical selection.
 `all` consumes the same iterator and returns only after successful exhaustion.
 Its required positive safe-integer `maxRecords` caps top-level Record occurrences
 across all collections; expanded links do not count toward that ceiling. Overflow
-rejects with nonretryable `capacity`, without a partial or truncated result.
+names the queried collections and ceiling, tells the author to narrow the query
+or increase `maxRecords`, and rejects with nonretryable `capacity` without a
+partial or truncated result.
 Invalid helper arguments use `invalid_query`; malformed pages, cursor cycles,
 snapshot changes or inconsistent requested counts use nonretryable `unavailable`.
 Selection and authority failures propagate unchanged, with no retry or restart.
@@ -706,15 +732,11 @@ 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. Hosted and app children publish immediately. During
-`os routine run <name>`, 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.
+hosted routines search their admitted hosted version. Local routines search the
+schema-governed Markdown currently in the checkout, including staged, modified
+and untracked Records. Each call refreshes its operation-local view; a later call
+sees completed Changes writes and external edits. Search Records supply captured
+versions for subsequent Changes. Explicit History keeps its hosted contract.
 
 `where` combines field conditions with AND. Alongside exact scalar/null equality
 and `$in`, declared one-valued `integer`, `number` and `date` fields accept
@@ -753,37 +775,106 @@ changes.create({
 changes.update(first.invoices[0], { amount: 30 });
 changes.delete(first.invoices[1]);
 await changes.validate();
-const publication = await changes.publish();
+const applied = await changes.apply();
 ```
 
+Use reserved `$body` to author a Record's Markdown content independently of its
+schema fields, in the same guarded change:
+
+```ts
+changes.create({ $ref: 'emails/email-123', type: 'email', subject: 'Invoice',
+  $body: 'Hello,\n\nPlease find our invoice attached.\n' });
+changes.update(existingEmail, { $body: revisedMarkdown }); // body-only change
+const emails = await general.records.read(emailRefs, { body: true });
+```
+
+Omitted `$body` on create means empty; omitted on update preserves the existing
+body exactly. A string deliberately replaces it, `''` clears it, and `null` is
+invalid. Body-only edits preserve front matter, field-only edits preserve the
+body, and both share the Record's exact-byte version guard. Bodies round-trip
+without Markdown interpretation, formatting, trimming, or fence semantics.
+Ordinary reads, selections and search stay body-free; explicitly requested
+bodies use the same ordered batch/null-slot shape. Local change batches support
+32 MiB of serialized JSON; hosted requests retain their separate 256 KiB limit.
+Body-enabled read responses are bounded to 8 MiB, with an explicit error
+instead of truncation. Hosted body reads use a protected immutable v3 index;
+older indexes without body coverage are unavailable rather than falsely empty.
+
+The customer routine owns content and authoring policy. For imported emails,
+create with the prepared body, omit `$body` on ordinary reruns, and backfill
+only bodies explicitly read as exactly empty. Existing notes and fenced blocks
+remain ordinary authored content. A fresh version alone does not authorize
+overwriting an existing nonempty body.
+
 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.
+selected `$ref` and `$version`. For hosted Data, 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. Hosted validation
+checks the complete candidate graph without effects, and `apply()` repeats
+authoritative validation before writing every create/update/delete together.
 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 run <name>`, publication retains the exact proposal and
-advances only run-local reads. `os routine publish <run>` later applies and indexes
-that immutable proposal; unrelated staged and unstaged work is preserved.
+During a local Run, `changes.apply()` validates the touched Records, paths,
+authored links and captured versions without auditing unrelated Record
+contents, then writes individual complete files atomically. Completed paths
+remain after a later filesystem failure. `validate()` grants no later
+permission to write; subsequent operations read the current checkout. There is
+no later Run publication, promotion or prepared repository state.
 
 `invalid_change` and known-unapplied `conflict` reject the batch.
-`publication_pending` is retryable and may report `uncertain` or `applied`;
+Unknown, missing, or invalid field failures include the Record ref and
+field name in the SDK error's `message`, with guidance to check the collection
+schema and its relative file location when known. Use
+`repository.collections.schema(name)` to inspect that schema.
+The error code and effect remain available for programmatic handling; the
+message does not include rejected field values.
+
+Known field failures also expose optional `error.detail`, exported as
+`DataValidationDetail`. It contains `record`, `field`, `reason`, and, when
+known, `schemaFile` and `expected`. Reasons are `unknown_field`, `missing_field`,
+`invalid_value`, and `source_schema_mismatch`. `expected` contains the field
+`type`, `many`, and `nullable`, with `decimalPlaces` for a bounded number or
+`format: 'month'` for a month date. Enum/constant values and rejected values
+are excluded. Older errors without detail remain valid.
+Other Data errors use this same optional `detail` field for local read/write
+recovery or record-limit facts. Check `'reason' in error.detail` before reading
+field-validation properties.
+
+When handling a failure, preserve the SDK error's message. For example, a
+routine that catches Data errors and reports them in its own result can keep
+the explanation alongside the stable code:
+
+```ts
+import { DataOperationError } from '@oddington/sdk';
+
+try {
+  await changes.validate();
+} catch (error) {
+  if (!(error instanceof DataOperationError)) throw error;
+  return { code: error.code, message: error.message,
+    ...(error.detail ? { detail: error.detail } : {}) };
+}
+```
+
+When the routine cannot continue, rethrow the original error to preserve its
+type and guidance. A new generic `Error` loses the SDK's bounded failure facts.
+
+`apply_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
+also keeps that identity. Concurrent `apply()` 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.
+bounded with creates and deletions to 10,000 total operations, with one operation
+per ref. The complete serialized change request is limited to 32 MiB for local
+file changes and 256 KiB for hosted writes. Search and history are outside this
+Changes slice. Source Records use ordinary schema rules. Files checks access
+when a consumer reads the referenced content.
 
 Bind a declared Airtable connection with `connections.airtable('project-management')`
 from the package root. Import and binding perform no network or credential work.
@@ -816,42 +907,41 @@ records separately. `AirtableOperationError` reports `unapplied`, `partial` or
 work; never repeat the whole change blindly. Credentials must never be retained
 in files, publication, logs, handler input, errors or receipts.
 
-Managed routine launches supply workspace, scoped capability and working root.
-The defaults read `OS_ROUTINE_WORKSPACE`, `OS_ROUTINE_RUN` and
-`OS_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
-existing `workspace`, `capability` and `workingRoot` options. Runtime context
+Managed routine launches supply workspace and scoped capability.
+The defaults read `OS_ROUTINE_WORKSPACE` and `OS_ROUTINE_RUN`. Hosts may supply
+`workspace`, `capability` and `request` options. Runtime context
 provides authority; callers cannot select repository remotes or expand grants.
 `os routine run <name> [--input <file|->]` executes the conventional inert
-definition with declared JSON input and captures OS-owned changes.
-`os routine publish <run>` sends those exact changes and recovers confirmed
-receipts without invoking business code again. Filesystem, model and installed
-connection effects occur immediately, including before a later failure.
-No-change success retains Run evidence without requiring publish. `--json`
-returns typed Run state/counts/result, or confirmed publish receipts/links.
+definition with declared JSON input. Data writes and hosted capability calls
+complete live; successful earlier work remains after a later failure. The Run
+retains exact local paths, safe hosted effects and Git provenance. `--json`
+returns typed Run state, result/failure and retained local activity.
 The former `prepare`, `run --local`, command/argv and authority-selection
 flags are rejected. `os routine deploy <canonical-id>` explicitly delivers the
 complete definition, including its response handlers; `--yes` provides automation
 consent. `os routine run <canonical-id> --remote` runs the current successful
 deployment with the same input/defaults, ordered steps and result validation.
 Remote handles expose `current()`, `watch()` and `step(id)`; `runs.list()` and
-`runs.get(id)` read retained bounded history. Remote summaries omit publication.
-Checkout-backed app children retain immediate publication.
-
-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
-file. Use `data.repository(name)` for Record reads and `changes()` for guarded
-creates, updates and deletions. Local Runs read their own successive proposals
-and leave ordinary uncommitted files for review. `os routine publish` sends the
-retained logical changes explicitly. Inbox publication has no Record methods;
+`runs.get(id)` read retained bounded history. Remote summaries omit local activity.
+App-started local routines use the same current-checkout and live-effects owner.
+
+Retain evidence with shared `files.create({ file: bytes, name: 'evidence.txt' })`
+and put the returned File into `fileBlock({ label, files })`. Inbox has no byte
+intake API. Local publication uploads that same File before exposing the item. Use `data.repository(name)` for Record reads and `changes()` for guarded
+creates, updates and deletions. Local Runs read current checkout files and leave
+completed Data writes as ordinary uncommitted files for review, even after later
+failure. Inbox publication has no Record methods;
 managed Response handlers retain their separately injected repository capability.
 
 Hosts publishing as a member supply the existing `request` option:
 
 ```ts
-const inbox = routinePublicationClient({ workspace, workingRoot, request });
+const inbox = routinePublicationClient({ workspace, request });
 ```
 
-Here `request` is the host's authorized member transport. A member can publish an
+Here `request` is the host's authorized member transport and takes precedence
+over ambient Run routing. The CLI uses its active workspace and shared Files to
+upload referenced local Files before sending publication. A member can publish an
 initial handlerless Ask or Digest where allowed; a member login supplies no
 routine repository-write authority. Login, session storage and refresh belong
 to `@oddington/cli`.