@oddington/sdk 0.1.36 → 0.1.38

package/README.md

@@ -6,11 +6,12 @@ Data and Files APIs work in browsers. Installing the package grants no authority
 
 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 +66,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`
@@ -79,6 +80,12 @@ declared `review` handler crosses the Inbox publication seam as `review`; Inbox
 retains the canonical `invoice-import` routine identity separately, without
 deploying or executing that handler.
 
+Microsoft Connection configuration has a separate, optional `access` description.
+It preserves supplied strings, including existing `read` and `read-write` labels,
+and does not grant or restrict Microsoft permissions. Management results omit
+this metadata when absent. Setup and safe inspection are documented in the
+[CLI Connections guide](../../apps/cli/README.md#connections).
+
 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`
@@ -95,8 +102,10 @@ 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.
@@ -246,7 +255,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:
 
@@ -262,19 +271,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
@@ -396,33 +403,28 @@ 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;
+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
@@ -435,24 +437,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
@@ -504,6 +492,44 @@ 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.
 
+Microsoft helpers are also exported at the package root, with the corresponding
+`OutlookSourceLocation` and `SharePointSourceLocation` types:
+
+```ts
+const messageLocation = source.location.outlook({
+  connection: 'outlook/invoices', message: message.id, url: message.webLink,
+  // attachment: attachment.id, // Include for attachment bytes; omit for message MIME.
+});
+const itemLocation = source.location.sharepoint({
+  connection: 'sharepoint/operations', site: siteId, drive: driveId, item: item.id,
+  version: version.id, path: lastKnownPath, url: item.webUrl,
+});
+```
+
+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
+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.
+Omit `attachment` for an exact message MIME File; supply it for an attachment File.
+
+For SharePoint, use the saved Graph site ID, the document library's drive ID and
+the file's driveItem ID. Optional `version` is an actual driveItemVersion ID
+established for those bytes, never an eTag or a guessed version. Omit it when no
+such version is established. Names, paths and URLs do not establish identity.
+Optional `path` is last-known context; `url` is the ordinary HTTPS message web
+link or SharePoint webUrl. Never retain temporary download, upload-session or
+copy-monitor URLs, authorization or credentials in Locations.
+
+Outlook merge identity is connection/message/attachment, with whole messages
+distinct from attachments. SharePoint identity is connection/site/drive/item/
+version, with absent versions distinct from present ones. Matching observations
+replace path/link context, including removing omitted context; distinct IDs,
+versions and copies remain separate. Incomplete coordinates gain no inferred
+identity. The retained OS File and hash own exact content; external edits do
+not change an existing Source's bytes. These helpers perform no provider I/O.
+
 Read a named repository through the authenticated host context:
 
 ```ts
@@ -526,12 +552,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
@@ -662,15 +687,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
@@ -727,9 +748,10 @@ 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.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.
 
 `invalid_change` and known-unapplied `conflict` reject the batch.
 `publication_pending` is retryable and may report `uncertain` or `applied`;
@@ -772,42 +794,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`.