@oddington/sdk 0.1.19 → 0.1.21

package/README.md

@@ -12,9 +12,16 @@ 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.
 
-Focused apps use `inbox.questions.list()` for `AnswerableQuestion[]`, with relevance
-bound by the trusted host to the canonical routines in the app declaration.
-The same list, answer and Record-search methods work in hosted and local apps.
+Hosted apps use `inbox.questions.list({ routines })` for `AnswerableQuestion[]`.
+Derive `routines` from the existing app declaration with
+`[...new Set(Object.values(appDeclaration.routines).map(binding => binding.routine))]`.
+These inner canonical names narrow relevance only; they grant no answer or
+Record-search authority. The ordinary authenticated Inbox context needs no app
+identity or declaration provisioning. The filter is required; `[]` returns no
+Questions after authentication. The SDK validates and privately snapshots the
+filter across pagination. Local apps use `inbox.questions.list()` instead, bound
+to their trusted host's declaration; any supplied filter is invalid locally.
+Both use the same answer and Record-search methods, without a filter or prior list.
 `InboxItem` remains the complete first-party Inbox value. Record refs are placement
 hints only: match them against independently authorized Data, and omit ambiguous
 detail placement. Keep drafts on failed or uncertain acceptance, prevent duplicate
@@ -26,39 +33,71 @@ interaction duties belong to the consuming app's interface.
 npm install @oddington/sdk
 ```
 
-An authored routine exports an inert definition from its conventional `run.ts`:
+An authored routine exports an inert definition from `routines/<directory>/routine.ts`:
 
 ```ts
 import { defineRoutine, file, schema } from '@oddington/sdk';
 
 export default defineRoutine({
+  id: 'invoice-import',
   input: schema.object({ document: file() }),
-  steps: { read: null, extract: schema.object({ pages: schema.integer() }) },
+  access: { files: 'read' },
+  steps: {
+    read: {
+      title: 'Read receipt',
+      async run(input: { document: import('@oddington/sdk').File }, os) {
+        const response = await os.files.read(input.document.id);
+        return { summary: { files: 1 }, data: { text: await response.text() } };
+      },
+    },
+  },
   result: schema.object({ recordsCreated: schema.integer() }),
   async run(input, os) {
-    await os.step('read');
-    await os.step('extract', { pages: 3 });
-    // Perform customer-owned work with the supplied installed capabilities.
-    return { recordsCreated: 1 };
+    await os.step('read', input);
+    return { recordsCreated: 0 };
   },
 });
 ```
 
-Importing or defining performs no business work. Input, step summaries and returned
-results are inferred from serializable declarations and checked at execution.
-Omitted input accepts only `{}`; omitted steps permit no public report; omitted
-result permits no returned value. `file()` declares a complete OS File descriptor;
+Importing or defining performs no business work. Input and result use bounded
+schemas; step inputs, summaries and detail are inferred from executable functions.
+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: [] })`.
+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;
 the trusted launcher separately verifies current File-use authority. The supplied
 runtime contains `run.id`, `data`, `files`, `connections`, `inbox`, and `step`.
-Accepted input and reported values are immutable snapshots.
+Accepted input and saved values are immutable snapshots. Access declarations set
+maximum named capabilities and grant no authority; the trusted host checks current
+authority. Response handler IDs are local to the routine and must be unique. A
+declared `review` handler crosses the Inbox publication seam as
+`invoice-import/review`, without deploying or executing that handler.
 
 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),
 finite numbers and safe integers with optional inclusive bounds, and Files.
 Definitions allow at most 64 steps, 64 total object properties across their schemas,
-and eight schema levels. Input, each summary and the result accept at most 256 KiB
-of serialized JSON; functions, cycles and non-JSON values reject. No name, entry,
-workspace, credentials or placement are authored in this definition.
+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.
+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;
+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.
+No entry, workspace, credentials or placement are authored in this definition.
+
+Local Run history returns the newest 20 summaries per canonical routine, without
+deleting older Runs or unpublished changes. Step titles and bounded summary/detail
+values are saved with the accepted Run, so later source edits cannot rewrite them.
+Each checkout-private execution/preparation JSON file has a 64 MiB total bound,
+including private diagnostics; app summaries never include those diagnostics.
+Publication reads the existing confirmed-receipt journal independently from the
+successful execution status. Refresh reads materialized state; watching provides
+connected updates without replay or interrupted-execution recovery.
 
 The named CLI local launcher requires native Node TypeScript stripping and a
 module `routines/package.json` whose `engines.node` range matches that executable.
@@ -188,63 +227,48 @@ changed local context fails closed, as do sign-out and initialization replacemen
 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 routine
-execution uses the installed routine's immediate-publication authority.
+falls back to hosted services. Local app routines use the same local execution
+and explicit publication lifecycle as the CLI.
 
 Apps can assess a declared routine without starting it:
 
 ```ts
-import { app, type AppRoutineBinding } from '@oddington/sdk';
-
-declare module '@oddington/sdk' {
-  interface AppRoutineTypes {
-    reconcile: AppRoutineBinding<
-      { includeArchived?: boolean; limit: number },
-      { processed: number },
-      { read: undefined; write: { changed: number } }
-    >;
-  }
-}
-
-const status = await app.routines.reconcile.availability();
-if (status.available) {
-  const steps: ('read' | 'write')[] = status.steps;
-}
-const run = await app.routines.reconcile.run({ limit: 2 });
-for await (const event of run.events()) {
-  if (event.type === 'step' && event.id === 'write') console.log(event.summary.changed);
-  if (event.type === 'finished' && event.state === 'succeeded') console.log(event.result.processed);
-}
-// After refresh or reopening the same live origin:
-const recovered = await app.routines.reconcile.recover();
-// await recovered[0]?.cancel(); // Resolves only after host acknowledgement.
+import { app } from '@oddington/sdk';
+
+const routines = await app.listRoutines(); // Declaration order, including unavailable routines.
+const description = await app.routines.receipts.describe();
+const run = await app.routines.receipts.run(); // Uses the definition's default input.
+for await (const state of run.watch()) console.log(state.status, state.steps);
+const detail = await run.step('read'); // Inferred summary and data for this new Run.
+// After refresh, under newly checked authority:
+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.
 ```
 
-Keep these business types in a customer-owned contract module. Augmentation
-types the property but grants no runtime authority: the local host checks its
-retained `app.json` mapping, current member and installed routine authority,
-and fixed local implementation on each assessment. Available status supplies
-only the declaration's ordered public step IDs. Unavailability supplies only
-`authority_unavailable` or `execution_unavailable`, without steps.
-Availability and recovery accept no arguments; run accepts only declared input.
-Bindings accept no endpoint, token, path, run selector or routine name. Hosted
-bindings report `execution_unavailable` after checking current context, with no
-remote request or local fallback. Availability is no reservation or guarantee
-of later execution. `run` rejects with `AppRoutineError.reason`:
-`authority_unavailable`, `execution_unavailable`, or `invalid_input`.
-Only event reads reconnect, with bounded backoff and duplicate suppression;
-launch and cancellation requests are never automatically retried. Failed
-cancellation requests do not acknowledge cancellation. Handles expose no IDs,
-cursors, raw output or process controls. Local sign-out, expiry, context
-replacement, origin changes and unconfirmed credential changes invalidate pending work.
+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,
+command, path or configuration selector. Hosted declarations stay visible and
+unavailable until hosted execution exists. Operations reject with
+`AppRoutineError.reason`: `authority_unavailable`, `execution_unavailable`, or
+`invalid_input`. Starts and publications 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
+per list; execution retains at most 10 MiB of report evidence. Raw process
+output and private authority stay private.
 
 The exact-origin browser credential survives document disposal, reload and tab
 closure in local storage. Disposal rejects the outgoing document's pending
 operations and disconnects its Run handles without cancelling the host-owned
 child. Fresh initialization at the same live Local Host origin can call the
-declared operation's `recover()` to continue that same owned Run without
-launching it again. Old handles remain invalid. Recovery is limited to the same
-authorized logical session, live Host and operation; it is not durable history.
+declared operation's `runs.get(id)` to read retained facts without launching it
+again. Old handles remain invalid. Terminal facts and bounded step detail live
+in the checkout's existing Run store; interrupted execution is not recovered.
 
 Each active initialization proactively renews before expiry, normally
 sixty seconds early with a shorter lead for shorter lifetimes. Only the exact