@oddington/sdk 0.1.38 → 0.1.40

package/README.md

@@ -4,6 +4,12 @@ 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`. Request-key recovery and captured
@@ -88,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.
@@ -96,6 +102,29 @@ 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,
@@ -107,11 +136,13 @@ 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.
@@ -345,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.
@@ -365,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.
@@ -424,6 +461,7 @@ Blob and byte-array declarations must match their intrinsic size. Originals are
 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.
@@ -473,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:
@@ -490,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:
@@ -508,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.
@@ -613,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.
@@ -730,38 +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 a local Run, `changes.publish()` validates the complete set once before
-writing 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. No later Run publication is required.
+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.