@oddington/sdk 0.1.11 → 0.1.13

package/README.md

@@ -8,14 +8,112 @@ Data and Files APIs work in browsers. Installing the package grants no authority
 npm install @oddington/sdk
 ```
 
+An authored routine exports an inert definition from its conventional `run.ts`:
+
+```ts
+import { defineRoutine, file, schema } from '@oddington/sdk';
+
+export default defineRoutine({
+  input: schema.object({ document: file() }),
+  steps: { read: null, extract: schema.object({ pages: schema.integer() }) },
+  result: schema.object({ recordsCreated: schema.integer() }),
+  async run(input, os) {
+    await os.step('read');
+    await os.step('extract', { pages: 3 });
+    // Perform customer-owned work with the supplied installed capabilities.
+    return { recordsCreated: 1 };
+  },
+});
+```
+
+Importing or defining performs no business work. Input, step summaries and returned
+results are inferred from serializable declarations and checked at execution.
+Omitted input accepts only `{}`; omitted steps permit no public report; omitted
+result permits no returned value. `file()` declares a complete OS File descriptor;
+the trusted launcher separately verifies current File-use authority. The supplied
+runtime contains `run.id`, `data`, `files`, `connections`, `inbox`, and `step`.
+Accepted input and reported values are immutable snapshots.
+
+The bounded grammar supports closed objects with required properties, arrays with
+an explicit `maxItems` from 1 to 64, booleans, strings (at most 4096 code points),
+finite numbers and safe integers with optional inclusive bounds, and Files.
+Definitions allow at most 64 steps, 64 total object properties across their schemas,
+and eight schema levels. Input, each summary and the result accept at most 256 KiB
+of serialized JSON; functions, cycles and non-JSON values reject. No name, entry,
+workspace, credentials or placement are authored in this definition.
+
+The named CLI local launcher requires native Node TypeScript stripping and a
+module `routines/package.json` whose `engines.node` range matches that executable.
+Before inspection it pins the selected entry's reachable TypeScript/JavaScript
+modules, checkout-local runtime packages, governing package metadata and static
+assets referenced by `new URL('./asset', import.meta.url)`. Literal imports,
+dynamic imports with literal specifiers, and literal CommonJS `require` are
+supported; computed loaders/assets, loader aliases, `createRequire`, evaluated
+code, `__dirname` assets, custom export conditions and export fallback arrays
+are refused. This first slice accepts at most 20,000 reachable files and 256 MiB;
+reachable symlinks, native addons and imports outside the pinned copy are refused.
+Historical `runs` output, unrelated routines, unused packages and files, package
+manager `.bin` links, caches and logs are excluded. Run evidence stays with the
+durable Run; artifacts are explicit File outputs. Dependency setup remains an
+explicit workspace action. JSON input transport is bounded to 256 KiB.
+The launcher renews its own 90-second ownership lease while queued or running;
+each execution retains the existing 15-minute temporary capability/connection
+bound. Lost ownership fails the Attempt without repeating customer code.
+
 ```ts
 import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/sdk';
 
 const inbox = routinePublicationClient();
 ```
 
-The OS-owned browser entry point initializes the existing shared refreshing
-session source before app code runs:
+The SDK owns browser provider setup, email/passcode actions, persisted restoration,
+refresh and expiry. Create one opaque handle outside rendering and bind the app's
+presentation to its state:
+
+```ts
+import { auth, os, BrowserAuthError } from '@oddington/sdk';
+
+const browserAuth = auth.create();
+const unsubscribe = browserAuth.subscribe(state => {
+  // Render status, account.email/displayName, pending action and safe error reason.
+});
+const current = browserAuth.getState();
+await browserAuth.sendCode(enteredEmail);
+try {
+  await browserAuth.verifyCode(enteredEmail, enteredCode);
+} catch (error) {
+  if (error instanceof BrowserAuthError) showFailure(error.reason);
+}
+
+os.init({ auth: browserAuth }); // Trusted workspace host startup only.
+// Later: await browserAuth.signOut(); // Ends only this browser's session.
+// On host teardown:
+unsubscribe();
+browserAuth.dispose();
+```
+
+`auth.create()` accepts no options. Trusted same-origin OS setup selects the
+provider internally through exact-origin `GET /api/auth`, owned by OS. The SDK
+uses same-origin credentials, refuses redirects and bypasses caching. Missing or
+invalid setup makes authentication unavailable without a legacy endpoint or
+app-configured provider fallback; ordinary app modules do not consume this
+internal bootstrap. State is `initializing`, `signed_out`, `signed_in`, `expired`
+or `unavailable`; actions complete without returning a session. Invitation-only
+code delivery never creates accounts or reveals account existence. Keep form
+selection, entered values, copy and navigation in the app. The handle exposes no
+provider, configuration, membership list or access/refresh credential. Consumers
+never construct bearer headers. Multiple handles share provider coordination on
+the same origin; each owns its subscription/disposal independently.
+
+The hosted runtime routes that exact capability path directly to OS while the
+app keeps its independently deployed interface and other paths. Operators must
+activate and verify the OS route before releasing a consumer that depends on
+it; installing this SDK does not deploy routes or migrate an app's sign-in UI.
+
+Only trusted workspace host startup passes that exact registered handle to
+`os.init`. Copying its public shape grants no authority. Fresh per-operation
+authority fails closed on sign-out, replacement, expiry or disposal. Existing
+hosts may continue supplying their shared refreshing session source:
 
 ```ts
 import { os, data, files, DataOperationError, FileOperationError } from '@oddington/sdk';
@@ -49,6 +147,15 @@ 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`.
 
+First-party Auth uses the handle without initializing workspace context. Its
+bounded `browserAuth.authorization.get(id)`, `approve(id)` and `deny(id)` actions
+support only the OS CLI request and fixed callback. Inspection/restoration never
+approves a fresh request. Results are validated consent labels, safe status or a
+completed `returnUrl`; Auth owns navigation. Decisions require prior inspection
+and remain bound to the current request and account. The reserved auth origin
+cannot obtain workspace capabilities even if a caller invokes `os.init` there.
+Existing Inbox/customer apps and local browser sessions are separate migrations.
+
 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.
@@ -164,6 +271,25 @@ 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.
 
+Auth uses a separately pinned installed fixture and **150,000 SDK-byte** ceiling.
+The private `@supabase/auth-js` **2.116.0** build dependency is bundled into the
+tarball, so installation needs no runtime provider dependency. Browser handle
+creation loads its internal provider chunk lazily; unused auth/provider code
+disappears from the Data/Files and Local Host fixture outputs. The audit counts
+both shipped SDK inputs and every emitted helper, rejects unexpected inputs and
+imports, and retains the full credential/server/customer leak scan. Node retains
+the complete package-root exports; provider classes are never public.
+
+Current auth measurement is **149,045 minified bytes**, including **5,177 fixture
+bytes** and **143,868 SDK bytes**, with **38,870 total gzip bytes**. Current
+unchanged Data/Files fixture measures **46,164 total / 5,893 fixture / 40,271 SDK
+bytes**, with **14,316 total gzip bytes**.
+Both fit their explicitly reviewed ceilings: **41,000 SDK bytes** for the pinned
+Data/Files fixture and **150,000 SDK bytes** for the separately pinned auth fixture.
+Those ceilings are fixed review decisions, not values regenerated from later
+measurements. The installed auth realm/host-handoff proof passes alongside the
+Node exports, declarations, tarball leak scan and browser compatibility audits.
+
 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
@@ -173,17 +299,17 @@ 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 |
+| Total minified JavaScript bytes | 488,539 | 46,164 |
+| Fixture-attributed bytes | 5,954 | 5,893 |
+| SDK bytes | 482,585 | 40,271 |
+| Total gzip bytes | 198,612 | 14,316 |
 
 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
+and reduces SDK bytes by 91.7%. Its literal ceiling is **41,000 SDK bytes**:
+729 bytes of deliberately limited headroom. The reviewed measurement includes
+the Local Host bootstrap and opaque browser-auth handoff 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.
@@ -221,10 +347,10 @@ configured root fails with `unsupported_context`. Files have one durable home;
 `both` is invalid. Local retention establishes no hosted registration.
 Fresh runs recover the same creator's File by its request key, and verify
 retained bytes before returning a descriptor or content. A dead parent fails
-closed. `os routine prepare` seals checked local File references and defers
-new remote Files, their enrichments and explicit uploads until `os routine publish`; legacy Inbox
-file preparation remains additive. Existing hosted Files are read-only during
-preparation.
+closed. `os routine run <name>` stages newly created Files locally for that Run,
+including local-placement Files, and defers promotion, enrichments and explicit
+uploads until `os routine publish <run>`. Legacy Inbox file capture remains
+additive. Existing hosted Files are read-only during local execution.
 `upload(id)` preserves the File descriptor, creator access and existing Source
 references. Local bytes remain authoritative until all remote objects verify;
 retrying a completed upload returns the same File. Later reads and enrichments
@@ -248,6 +374,22 @@ Response without consuming its body. Local transfer is bounded and buffered
 before constructing that Response. Creation grants private creator access;
 workspace membership alone never grants another creator's File.
 
+`await files.delete(fileId)` removes an unreferenced File's original and all
+retained enrichments under its current member or installed-routine creator.
+It returns `void` only after physical cleanup and durable completion; a completed
+retry succeeds. Independent retention returns `conflict` without changing the
+File. `access_denied` and `integrity` remain terminal; `unavailable` and
+`capacity` are retryable. Pending deletion denies reads, writes, new uses and
+creation-key replay while the same current creator retries cleanup. Deletion
+uses the authenticated parent for managed local Files and uploaded caches.
+R2 cleanup verifies the registered immutable key and native revision, removes
+only that object and confirms absence. Each physical writer owns a distinct
+candidate key, so a delayed writer cannot recreate the deleted representation.
+Pending admission is never success.
+When a completion reply is lost, retry `files.delete` with the same File ID and
+current creator authority. Keep stable creation keys separate from deletion
+recovery: a completed deleted key is denied and cannot recreate the File.
+
 `enrich` accepts a string encoded as UTF-8 or exact `Uint8Array` bytes, a safe
 flat filename, and an optional MIME hint. OS verifies text/Markdown/JSON or
 reduces the content to generic binary metadata; it performs no extraction or
@@ -287,8 +429,8 @@ if (next) await general.records.select({
 Binding is inert. Each operation resolves current workspace, endpoint and
 short-lived authority from the trusted app host or managed routine context.
 Customer calls cannot configure those values. Missing or expired context
-rejects; a named handle does not expand repository access. During explicit
-`os routine prepare`, the same calls use the matched checkout's committed
+rejects; a named handle does not expand repository access. During
+`os routine run <name>`, the same calls use the matched checkout's committed
 version through a private parent transport. Dirty files are ignored. An OS
 cache outside the checkout reuses derived data; reads require no remote access
 or preparation storage. Later accepted record effects advance the run's view
@@ -354,8 +496,8 @@ 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,
+publication. Hosted and app children publish immediately. During
+`os routine run <name>`, 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
@@ -389,7 +531,7 @@ For reads, only `capacity` and `unavailable` are retryable; an error never inclu
 server details. Server boundaries own query bounds and authorization.
 
 Schema-driven creates, guarded updates and guarded deletions use the same handle
-in immediate and prepared routines:
+in immediate and captured local routines:
 
 ```ts
 const changes = general.changes();
@@ -418,8 +560,8 @@ only after its exact index is ready. Later current reads discover that version.
 Deleted identities keep their captured versions; deletion creates no new Record
 version or tombstone. A Source deletion removes only that guarded Record, retaining
 its File, enrichments and existing durable uses.
-During `os routine prepare`, publication retains the exact proposal and
-advances only run-local reads. `os routine publish` later applies and indexes
+During `os routine run <name>`, publication retains the exact proposal and
+advances only run-local reads. `os routine publish <run>` later applies and indexes
 that immutable proposal; unrelated staged and unstaged work is preserved.
 
 `invalid_change` and known-unapplied `conflict` reject the batch.
@@ -468,14 +610,16 @@ The defaults read `ODDINGTON_ROUTINE_WORKSPACE`, `ODDINGTON_ROUTINE_RUN` and
 `ODDINGTON_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
 existing `workspace`, `capability` and `workingRoot` options. Runtime context
 provides authority; callers cannot select repository remotes or expand grants.
-`os routine run` publishes as capabilities are called. The same calls prepare
-work when launched with `os routine prepare`, and `os routine publish` owns
-explicit publication and recovery of that prepared run. Preparation may contact
-OS for authentication and reads, and declared connections may contact their
-providers; it does not promise offline execution. Execution location and File
-storage are independent of the publication lifecycle. `os routine run --local`
-remains a deprecated compatibility alias for `os routine prepare` and prints
-the replacement command.
+`os routine run <name> [--input <file|->]` executes the conventional inert
+definition with declared JSON input and captures OS-owned changes.
+`os routine publish <run>` sends those exact changes and recovers confirmed
+receipts without invoking business code again. Filesystem, model and installed
+connection effects occur immediately, including before a later failure.
+No-change success retains Run evidence without requiring publish. `--json`
+returns typed Run state/counts/result, or confirmed publish receipts/links.
+The former `prepare`, `run --local`, command/argv and authority-selection
+flags are rejected. Remote execution and deployment are not implemented here.
+Checkout-backed app children retain immediate publication.
 
 Retain evidence with `inbox.files.add({ path: 'evidence.txt' })`. Paths stay within
 the invocation's working root and uploaded bytes are verified against the retained