@oddington/sdk 0.1.7 → 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
@@ -113,6 +133,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