@oddington/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Oddington SDK License
+
+Copyright (c) 2026 Oddington. All rights reserved.
+
+Subject to the terms governing your use of Oddington services, Oddington grants
+you a limited, non-exclusive, non-transferable, revocable license to download,
+install, copy as reasonably necessary for installation or backup, and use an
+unmodified copy of this software solely to access Oddington services for which
+you are authorized.
+
+You may not distribute, sublicense, sell, modify, or create derivative works of
+this software except with Oddington's prior written permission. You may not
+reverse engineer or circumvent access controls except to the extent such a
+restriction is prohibited by applicable law.
+
+This software is provided "as is", without warranties of any kind, express or
+implied. Oddington may update or withdraw it at any time.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# Oddington SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The importable client for Oddington routines and response handlers. Requires
+Node.js 22.12.0 or later. Installing the package grants no authority.
+
+```sh
+npm install @oddington/sdk
+```
+
+```ts
+import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/sdk';
+
+const inbox = routinePublicationClient();
+```
+
+Managed routine launches supply workspace, scoped capability and working root.
+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.
+The same calls prepare locally when launched with `os routine run --local`, and
+the CLI owns explicit publication and recovery of that prepared run.
+
+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
+file. Use `inbox.repository.readRecords`, `writeRecords`, `updateRecords` and
+`deleteRecords` for shared Records capabilities. Writes require a trusted routine
+launch and installed write grant. Carry the returned `receipt.commit` into a
+subsequent `readRecords({ repository, refs, atCommit: receipt.commit })` to capture
+the prepared version for review. Retrying writes or publication uses the same
+request key and exact input; server boundaries own validation, effects and receipts.
+
+Hosts publishing as a member supply the existing `request` option:
+
+```ts
+const inbox = routinePublicationClient({ workspace, workingRoot, request });
+```
+
+Here `request` is the host's authorized member transport. A member can publish an
+initial handlerless Ask or Digest where allowed; a member login supplies no
+routine repository-write authority. Login, session storage and refresh belong
+to `@oddington/cli`.
+
+The CLI consumes the same SDK and supplies its signed-in member transport to CLI
+commands. The former `@oddington/cli/inbox` subpath is removed; routines import
+this package root.
+
+The managed response runner supplies the SDK to approved handler modules:
+
+```ts
+export const handlers = [defineHandler({
+  id: 'review',
+  run: async () => resolveAsk({ outcome: 'Reviewed' }),
+})];
+```
+
+A self-contained module importing only the SDK needs no customer dependency
+installation. Customer manifests cannot replace the runner-owned SDK. The runner
+selects the approved code revision and handler, and supplies only scoped capability
+transport. The package contains public runtime code, declarations, this README and
+its license; it has no executable, operator/server code or infrastructure credentials.
+
+From the product checkout, run `bun run --filter @oddington/sdk build`, then
+`bun run --filter @oddington/sdk verify:package`. Verification installs the actual
+tarball offline into a temporary consumer without the CLI, imports and typechecks
+through `@oddington/sdk`, and exercises retained evidence, handlerless publication
+and guarded repository calls. Set `PACKAGE_VERIFY_NODE` to the Node 22.12.0
+executable for supported-baseline proof. The CLI's corresponding verifier installs
+both local tarballs, checks `os --help` and refuses the removed subpath.