@oddington/sdk 0.1.6 → 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