@oddington/sdk 0.1.7 → 0.1.9

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
@@ -34,9 +54,10 @@ 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
+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.
 
 Apps can assess a declared routine without starting it:
@@ -84,14 +105,26 @@ 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.
+replacement, origin changes and unconfirmed 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.
+storage. Each active initialization proactively renews before expiry, normally
+sixty seconds early with a shorter lead for shorter lifetimes. Only the exact
+Local Host silently refreshes the secure CLI login and confirms unchanged
+complete access. Successful renewal rotates only the bounded browser credential;
+it exposes no CLI credential or login prompt. Other tabs and SDK instances
+retain only their unchanged deadline during a temporary renewal outage and
+retry proactively without starting or delaying Data reads. They
+confirm the stored winner against the same Host and logical session before
+silently adopting it. Rotation preserves admitted Data/results and owned runs;
+old credentials cannot admit new requests and failed writes, launches and
+cancellations are never replayed. Sign-out, replacement and expiry cancel
+renewal, including pending response bodies. Host expiry and current membership
+remain authoritative; stored state cannot revive a stopped host. Recovery
+covers only the operation's current logical 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.
+File-use transfer and a local browser Files adapter are separate work.
 
 The fixed child imports `appRun` from the same package and shares the app's
 customer-owned input/result/step types:
@@ -113,6 +146,48 @@ 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