@oddington/sdk 0.1.6 → 0.1.8

package/README.md

@@ -18,9 +18,29 @@ The OS-owned browser entry point initializes the existing shared refreshing
 session source before app code runs:
 
 ```ts
-import { os } from '@oddington/sdk';
+import { os, data, files, DataOperationError, FileOperationError } from '@oddington/sdk';
 
-os.init({ auth });
+os.init({ auth }); // OS-owned startup, once before app modules run.
+
+// App code uses the installed capabilities directly.
+const general = data.repository('general');
+try {
+  const selected = await general.records.select({ invoices: { $: { limit: 20 } } });
+  const found = await general.records.search('acme overdue', {
+    collections: ['invoices'], limit: 20,
+  });
+  const statement = await files.create({
+    file: selectedFile, name: 'September statement.csv', path: 'HSC/2026/09',
+  });
+  const content = await files.read(statement.id);
+  // selected and found contain canonical Records and their opaque version guards.
+  // content is an unconsumed Web Response.
+} catch (error) {
+  if (error instanceof DataOperationError || error instanceof FileOperationError) {
+    console.error(error.code, error.retryable); // Bounded public failure information.
+  }
+  throw error;
+}
 ```
 
 This returns `void` and derives context from the current HTTPS workspace origin
@@ -29,6 +49,132 @@ 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.
+
+Browser bundlers select the standard `browser` condition at the package root.
+Named imports retain the selected browser capabilities without Node built-ins,
+compatibility shims or unused routine, filesystem, Inbox and connection code.
+Use the same `@oddington/sdk` import and declarations in both environments;
+there is no browser subpath or required alias, polyfill or consumer build define.
+Node imports retain the complete supported routine and managed-handler runtime
+on Node.js 22.12.0 or later. Browser operations requiring a Node working root
+remain unsupported.
+
+Verify the installed tarball with `bun run --filter @oddington/sdk verify:package`
+from the repository. This checks Node runtime exports and declarations, all public
+text for leaks, and the named browser imports in a realm without Node globals or
+a module loader. It rejects bundler warnings, external dependencies, Node/shim
+code, unused implementations and increases beyond the reviewed SDK byte ceiling.
+The newer Local Host app imports are bundled and exercised separately under the
+same strict compatibility audit, so they cannot weaken or inflate the hosted
+Data/Files size comparison.
+
+The browser budget uses pinned esbuild 0.28.1, browser platform, bundled ESM,
+`es2022`, minification, default tree shaking and inline legal comments, with no
+source map, aliases, polyfills, external modules or consumer defines. Its fixed
+named-import fixture exercises hosted Data selection/search and Files operations.
+SDK bytes include all emitted JavaScript except the bundler-attributed fixture
+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 | 40,534 |
+| Fixture-attributed bytes | 5,954 | 5,897 |
+| SDK bytes | 482,585 | 34,637 |
+| Total gzip bytes | 198,612 | 12,414 |
+
+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 92.8%. Its literal ceiling is **40,000 SDK bytes**:
+5,363 bytes (15.5%) of headroom for bounded client fixes. The increase from the
+original 24,000-byte measurement accounts for the subsequently added Local Host
+bootstrap that `os.init` must select at runtime. 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.
+
 Create and recover a private immutable original through the same host context:
 
 ```ts