@oddington/sdk 0.1.5 → 0.1.7

package/README.md

@@ -29,6 +29,90 @@ session subscription. Workspace existence and member access are checked by the
 OS service. App modules use capability namespaces; routines and handlers receive
 runtime context without calling `os.init`.
 
+The same `os.init({ auth })` call also consumes authenticated bootstrap state on
+an OS-launched IPv4 loopback origin. It checks `/_os/app/context` on that exact
+origin for every protected operation, without reading hosted access credentials.
+It accepts no workspace, endpoint or token option. Missing, forged, expired or
+changed local context fails closed, as do sign-out and initialization replacement.
+Local Data and Files currently return `context_unavailable` and
+`unsupported_context` respectively after checking context; they do not return
+empty data, upload locally or fall back to hosted services. Local app routine
+execution uses the installed routine's immediate-publication authority.
+
+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.
+```
+
+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 and origin/credential changes invalidate pending work.
+
+The exact-origin browser credential survives reload and tab closure in local
+storage. Host expiry and current membership remain authoritative; stored state
+cannot revive a stopped host. Recovery covers only the operation's current
+session and bounded terminal grace, without relaunching or durable history.
+Supplied File inputs currently reject `execution_unavailable` before launch;
+File-use transfer and local Data/Files adapters are separate work.
+
+The fixed child imports `appRun` from the same package and shares the app's
+customer-owned input/result/step types:
+
+```ts
+import { appRun } from '@oddington/sdk';
+import type { Input, Result, Steps } from './contract.ts';
+
+const context = appRun.current<Input, Result, Steps>();
+if (context) {
+  await context.step('read');
+  await context.step('write', { changed: 1 });
+  await context.finish({ processed: context.input.limit });
+}
+```
+
+`appRun.current()` is absent in ordinary Node and browser execution. Child
+input is deeply immutable; declared reports await host acceptance. Success
+requires accepted finish and zero exit. Cancellation or later failure does not
+undo already confirmed shared effects.
+
 Create and recover a private immutable original through the same host context:
 
 ```ts
@@ -140,8 +224,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