@byok-sdk/cloud-dataplane 0.4.1 → 0.4.2

package/README.md

@@ -1,15 +1,15 @@
 # @byok-sdk/cloud-dataplane
 
 The durable data plane for the BYOK SDK's hosted device surface: Postgres
-implementations of **all nine cloud-local store ports and all seven `@byok-sdk/core`
+implementations of **all ten cloud-local store ports and all seven `@byok-sdk/core`
 ports**, the R2/S3 object adapter that backs the blob port, and the forward-only
 migration runner that creates the tables they read.
 
 Three store/maintenance compositions plus one transaction authority ship from here. `createPostgresCloudStores` supplies the full
-`CloudStores` bundle (`devices`, `pairingCodes`, `nonces`, `dedup`, `tasks`,
+`CloudStores` bundle (`activity`, `devices`, `pairingCodes`, `nonces`, `dedup`, `tasks`,
 `receipts`, `proofReceipts`, `blobs`, `rateLimiter`); `createPostgresCoreStores`
 supplies the full `CoreStores` bundle (`mailbox`, `board`, `truth`, `presence`,
-`activity`, `objects`, `quota`). Both return every port rather than a subset,
+`objects`, `quota`, `skillPacks`). Both return every port rather than a subset,
 because the conformance suites certify a composition as a whole — there is no
 partial bundle for them to run. `createPostgresCloudMaintenance` is the third,
 host-only operational composition; it is deliberately outside both port
@@ -40,6 +40,48 @@ gets no table by design: persisting an allow-all would be a table that is always
 empty, and a real limiter is edge work rather than a per-request write. `blobs`
 is the R2 adapter described below.
 
+## Deployment compositions
+
+Two entries, one data plane, and the host picks the composition explicitly —
+the SDK never detects where it is running and never falls back between the two.
+
+- **Node/VPS resident service.** Import the package root
+  (`@byok-sdk/cloud-dataplane`) and talk to Postgres and R2/S3 directly. The
+  migration runner and the cleanup/maintenance composition run in-process:
+  this is the entry that carries the Node-only operations.
+- **Cloudflare Workers.** Import `@byok-sdk/cloud-dataplane/runtime` — the
+  online request path alone (pool, both store compositions, R2 blob store,
+  truth committer). Its graph never reaches a node builtin beyond what
+  `nodejs_compat` provides, so `pg` stays external in this package's build and
+  is satisfied by the platform: Hyperdrive terminates the database connection,
+  and R2 is reached over `fetch` with `aws4fetch`. Migrations and cleanup have
+  no place on a Worker — they read files off disk — so run them from a CI job
+  or an operator's Node process against the direct DSN:
+
+  ```ts
+  import { createByokPool, createPostgresCloudStores } from '@byok-sdk/cloud-dataplane/runtime';
+
+  const pool = createByokPool({ connectionString: env.BYOK_PG.connectionString });
+  ```
+
+  Pool lifecycle follows the composition. On Node/VPS the Pool is
+  process-scoped, and the host calls `pool.end()` at shutdown. On Workers,
+  create the Pool inside each `fetch`/`queue` handler — per invocation,
+  exactly like the `worker-smoke` probes already do — and never hold one in
+  module or global scope: cross-request pool reuse is forbidden, not a
+  preference. A Worker invocation's end cleans up its client connections, so
+  `pool.end()` is usually unnecessary there.
+
+Same contracts, same SQL, same Postgres + R2 authority either way. There is no
+D1 and no Durable Objects variant, and the runtime entry is a strict subset of
+the root rather than a second implementation: `src/index.ts` re-exports
+`src/runtime.ts` wholesale, so the two surfaces cannot drift. The boundary is
+build-enforced — the runtime entry compiles under the neutral platform, which
+fails the build the moment its graph reaches a node builtin — and CI exercises
+the Worker composition for real through the `worker-smoke/` fixture (packaged
+with `wrangler deploy --dry-run`, served by `wrangler dev` against the test
+substrate; see Testing below).
+
 ## Blobs
 
 `blobs` mints grants and never carries a byte. `createUpload` writes the
@@ -218,6 +260,13 @@ test rather than a step someone remembers. What runs:
   SigV4 implementation, and nothing stubs a signature check. The two that are
   about retry semantics go through a fault injector wrapped around `fetch`,
   which replaces individual attempts and never answers a request itself.
+- The worker suites, always for packaging and opt-in for serving:
+  `worker-packaging.test.ts` dry-runs `wrangler deploy` over `worker-smoke/`
+  on every run, and `worker-e2e.test.ts` additionally serves that fixture with
+  `wrangler dev` (local workerd) against the same Postgres when you set
+  `BYOK_TEST_WORKER_DATAPLANE=1`. CI's `dataplane` job sets it, plus the
+  `BYOK_REQUIRE_WORKER_DATAPLANE` flag that turns an unmet gate into a hard
+  failure.
 
 ## License
 

package/dist/index.d.ts

@@ -11,20 +11,24 @@
  * authority and R2/S3-compatible storage remains the byte plane; a future
  * alternative composition must use a distinct package name rather than making
  * this authority conditional at runtime.
+ *
+ * Two entries, one online surface:
+ *
+ * - `.` (this file) is the superset: the online request path plus the Node-only
+ *   operations — the migration runner, the migrations directory, and the
+ *   cleanup/maintenance composition — that a resident Node/VPS service runs
+ *   in-process.
+ * - `./runtime` is the Worker-loadable online surface alone, and is the single
+ *   authority for the online export list: this file re-exports it wholesale
+ *   rather than duplicating it, so the two entries cannot drift.
+ *
+ * The invariant that makes the split real: the `./runtime` subgraph must never
+ * reach a node builtin. It is enforced at build time by the neutral-platform
+ * tsup pass over `src/runtime.ts`, and pinned by the runtime-entry test.
  */
-export { createByokPool } from './pool';
-export type { ByokPoolOptions } from './pool';
+export * from './runtime';
 export { MigrationChecksumMismatchError, MigrationFilenameError, migrate, readMigrationFiles } from './migrate';
 export type { MigrationFile, MigrationResult } from './migrate';
 export { migrationsDir } from './migrations-dir';
-export { PostgresDeviceDirectory, PostgresInboundDedupStore, PostgresNonceStore, PostgresPairingCodeStore, PostgresRequestReceiptStore, PostgresTaskAttemptStore, createPostgresCloudStores, } from './stores/index';
-export type { PostgresCloudStoreOptions, PostgresCloudStores, PostgresObjectStorageOptions, } from './stores/index';
-export { DEFAULT_MAX_ATTEMPTS, DEFAULT_PRESIGN_TTL_SECONDS, DEFAULT_RETRY_DELAY_MS, MAX_PRESIGN_TTL_SECONDS, MIN_PRESIGN_TTL_SECONDS, ObjectStoreRequestError, R2_BLOB_ERROR_CODES, R2BlobStoreError, R2CloudBlobStore, R2ObjectMaintenanceStore, } from './stores/index';
-export type { ObjectStoreFetch, R2BlobErrorCode, R2BlobStoreOptions } from './stores/index';
-export type { R2DeleteResult, R2ListedObject, R2ObjectMaintenance, R2ObjectMaintenanceOptions, R2ObjectPage, } from './stores/index';
-export { PostgresActivityStore, PostgresBoardStore, PostgresMailboxStore, PostgresObjectStore, PostgresPresenceStore, PostgresQuotaStore, PostgresTruthStore, createPostgresCoreStores, } from './stores/core/index';
-export type { PostgresCoreStoreOptions } from './stores/core/index';
 export { CLOUD_CLEANUP_ERROR_CODES, CloudCleanupError, PostgresCloudCleanup, createPostgresCloudMaintenance, } from './cleanup';
-export { PostgresTruthCommitter } from './truth-committer';
-export type { PostgresTruthCommitterOptions } from './truth-committer';
 export type { CleanupJobState, CloudCleanupErrorCode, CloudCleanupResult, DeadLetterPage, DeadLetterQuery, DeadLetterRef, DeadLetterReplayInput, ObjectUsageRebuildResult, PostgresCloudCleanupOptions, PostgresCloudMaintenanceOptions, TenantRetentionPolicy, TenantRetentionPolicyInput, } from './cleanup';