@byok-sdk/cloud-dataplane 0.4.0

package/dist/stores/core/board.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Postgres {@link BoardStore} (§12.3).
+ *
+ * Every mutation is one guarded `UPDATE ... WHERE`, and the guard carries the
+ * caller's whole expectation: who holds the item, what status it is in, and —
+ * for `claim` — that it is claimable at all. Zero rows is the rejection, and
+ * the store then re-reads the item to say WHICH rejection and to hand the
+ * caller the snapshot it lost to. A conflict that reports only "conflict"
+ * forces a second round trip and invites a retry loop that eventually
+ * overwrites the winner (§12.3: no silent last-write-wins).
+ *
+ * The concurrent-claim property comes out of Postgres' own re-check: three
+ * sessions issue the same `UPDATE ... WHERE holder_id IS NULL`, one wins, and
+ * the other two re-evaluate the qual against the winner's committed row and
+ * match nothing. The suite asserts the outcome, not the mechanism — the
+ * in-memory reference gets the same outcome from its `await` boundaries.
+ *
+ * **`board_seq` is allocated in its own statement, before the guarded write.**
+ * Folding the allocator into a data-modifying CTE would let one session lock
+ * `tenant_stream` then `board_item` while another locks them in the order the
+ * planner picked for it, which is a deadlock rather than a conflict. Allocating
+ * first, in an autocommitted statement that releases immediately, gives every
+ * writer one lock order. A rejected write therefore burns a sequence number:
+ * `boardSeq` is contractually monotonic, never contractually gapless, and the
+ * incremental feed reads `> afterSeq` either way.
+ */
+import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardStore, type BoardUnclaimInput, type Clock, type TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresBoardStore implements BoardStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    create(tenant: TenantId, input: BoardItemInput): Promise<BoardItem>;
+    get(tenant: TenantId, itemId: string): Promise<BoardItem | undefined>;
+    list(tenant: TenantId, query: BoardListQuery): Promise<BoardPage>;
+    claim(tenant: TenantId, input: BoardClaimInput): Promise<BoardItem>;
+    unclaim(tenant: TenantId, input: BoardUnclaimInput): Promise<BoardItem>;
+    updateStatus(tenant: TenantId, input: BoardStatusUpdateInput): Promise<BoardItem>;
+}

package/dist/stores/core/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The Postgres composition of the eight `@byok-sdk/core` ports.
+ *
+ * All eight, or none: `runCoreConformance`'s port-inventory dimension asserts a
+ * composition supplies exactly `CORE_STORE_NAMES` and exactly the methods
+ * `CORE_PORT_METHODS` declares, so there is no such thing as a partial core
+ * composition to certify. The original seven landed in one slice (design §11);
+ * `skillPacks` is the eighth, added in Phase 2 of `skill-pack-delivery-channel`
+ * when it graduated from a bridge port to a mandatory `CoreStores` member. This
+ * function returns a full `CoreStores` where the cloud-local sibling returns a
+ * named subset.
+ *
+ * Everything that reads time reads the injected clock. Nothing calls SQL
+ * `now()` — presence expiry, activity expiry and reservation expiry are all
+ * contract behavior the suite asserts by moving a test clock, and a store that
+ * asked the database for the time would make every one of those assertions
+ * either a sleep or a flake.
+ */
+import type { Clock, CoreStores } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export { PostgresMailboxStore } from './mailbox';
+export { PostgresBoardStore } from './board';
+export { PostgresTruthStore } from './truth';
+export { PostgresPresenceStore, PostgresActivityStore } from './presence';
+export { PostgresObjectStore } from './objects';
+export { PostgresQuotaStore } from './quota';
+export { PostgresSkillPackStore } from './skill-pack';
+export interface PostgresCoreStoreOptions {
+    readonly pool: Pool;
+    /**
+     * The clock every TTL and timestamp in this composition reads. Injected, not
+     * the database's `now()`: expiry has to be assertable under a test clock, and
+     * a store that asks the server for the time cannot be.
+     */
+    readonly clock: Clock;
+}
+export declare function createPostgresCoreStores(options: PostgresCoreStoreOptions): CoreStores;

package/dist/stores/core/mailbox-sequence.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one Postgres mailbox sequence allocator.
+ *
+ * The caller must already be in a transaction and must keep that transaction
+ * open until its outbox row is inserted. The returned row lock is what makes a
+ * lower sequence commit before any higher sequence for the same device.
+ */
+import type { TenantId } from '@byok-sdk/core';
+import type { PoolClient } from 'pg';
+export declare function allocateMailboxSequence(client: PoolClient, tenant: TenantId, deviceId: string, now: string): Promise<number>;

package/dist/stores/core/mailbox.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Postgres {@link MailboxStore} (§12.7.3).
+ *
+ * The load-bearing rule, and the one a composition can break silently:
+ * **reading is not acknowledging.** `readAfter` is a `SELECT` and nothing else.
+ * The only ack is `advanceCursor`, which the daemon calls after it has durably
+ * journaled the envelope, and it is monotonic — a lower cursor is refused with
+ * the cursor it lost to rather than quietly re-delivering work the device has
+ * already run.
+ *
+ * `collectRetired` deletes acked rows and **marks** unacked ones `expired`. It
+ * never deletes an unacked row. §12.7.5 requires an envelope that aged out
+ * before anyone consumed it to stay visible; deleting it would make "we dropped
+ * work" indistinguishable from "there was no work", and dead-lettering those
+ * rows is S4B's job (O-009), not this one's.
+ *
+ * Every row lives under `(tenant_id, device_id, seq)`, so a cross-tenant read
+ * is not denied — it addresses a different key space and finds nothing. That is
+ * the SQL expression of §12.6.2 layer 3: there is no bare device index to
+ * accidentally query.
+ */
+import { type Clock, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type MailboxRetentionInput, type MailboxRetentionResult, type MailboxStore, type TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresMailboxStore implements MailboxStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
+    readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
+    advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
+    readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
+    collectRetired(tenant: TenantId, input: MailboxRetentionInput): Promise<MailboxRetentionResult>;
+}

package/dist/stores/core/objects.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Postgres {@link ObjectStore} — the manifest, and only the manifest
+ * (§12.7.4, §12.7.8).
+ *
+ * Zero bytes cross this file. The manifest is the transaction authority and the
+ * object store holds the payload; the R2 adapter that moves bytes is S4A-c.
+ * What lives here is the state machine that stands between a failed object-store
+ * delete and either a leaked object or a deleted one a truth record still points
+ * at.
+ *
+ * Three properties the SQL is shaped around:
+ *
+ * - **`ref_count` is recomputed, never incremented.** Every reference mutation
+ *   sets it to `count(*)` over `object_reference`. An increment drifts the
+ *   moment a retried `addReference` lands twice, and a drifted count strands
+ *   the object forever because `markDeletePending` refuses at `refCount != 0`.
+ *   The reference table's primary key already makes the write idempotent; the
+ *   count just reads it.
+ * - **Reference mutations hold the manifest row under `FOR UPDATE`.** The
+ *   recomputation above is only authoritative because of this lock, not on its
+ *   own: under READ COMMITTED the `count(*)` subquery is evaluated on the
+ *   snapshot its statement started with, so an unlocked `addReference` reads a
+ *   `committed` state, and `markDeletePending`'s `ref_count = 0` guard can pass
+ *   in the window before the reference row lands — leaving `delete_pending`
+ *   with a live reference, which is a truth record pointing at bytes S4B's GC
+ *   is entitled to delete. Taking the manifest row exclusively first makes the
+ *   tombstone and the reference write queue against each other, exactly as
+ *   `PostgresQuotaStore.reserve` serializes reservers on the entitlement row.
+ * - **Every state move is a guarded `UPDATE`.** The legal transitions are the
+ *   guard, so an illegal one writes nothing and the row is re-read to say which
+ *   typed rejection applies. `commit` additionally guards on the DECLARED size
+ *   and type, because the whole point of the check is that what the composition
+ *   observed on the object store and what the client declared can differ
+ *   (§12.7.7 step 4).
+ */
+import { type Clock, type ContentHash, type ObjectCommitInput, type ObjectListQuery, type ObjectManifestEntry, type ObjectManifestInput, type ObjectReferenceInput, type ObjectStore, type TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresObjectStore implements ObjectStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    putManifest(tenant: TenantId, input: ObjectManifestInput): Promise<ObjectManifestEntry>;
+    commit(tenant: TenantId, input: ObjectCommitInput): Promise<ObjectManifestEntry>;
+    get(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry | undefined>;
+    list(tenant: TenantId, query: ObjectListQuery): Promise<readonly ObjectManifestEntry[]>;
+    addReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    removeReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    markDeletePending(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+    markDeleted(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+}

package/dist/stores/core/presence.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Postgres {@link PresenceStore} and {@link ActivityStore} (§12.3).
+ *
+ * Both are lossy, TTL-bounded, unsigned, and never authoritative, and both are
+ * bounded upserts: one row per device, one row per task. Nothing here may be
+ * used to derive coordination state, execution state, authorization, billing or
+ * recovery — which is why this file shares no vocabulary with `board.ts` and
+ * none with the frozen wire states.
+ *
+ * **Expiry is absence, and it is expressed as a read filter.** A hint past its
+ * `expiresAt` is invisible to every read, so no reader can observe a stale
+ * level and mistake it for a live one. The in-memory reference deletes the
+ * entry lazily on read; here the row stays and the predicate excludes it. Same
+ * observable answer, and a `SELECT` that does not write to answer itself.
+ *
+ * Every instant is the injected clock's. Asserting TTL behavior against a wall
+ * clock means sleeping or accepting flakes, which is why the port takes `ttlMs`
+ * and the composition supplies the clock.
+ */
+import { type ActivityAppendInput, type ActivityStore, type ActivityTail, type Clock, type PresenceHint, type PresenceHintInput, type PresenceStore, type TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresPresenceStore implements PresenceStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    publish(tenant: TenantId, input: PresenceHintInput): Promise<PresenceHint>;
+    read(tenant: TenantId, deviceId: string): Promise<PresenceHint | undefined>;
+    list(tenant: TenantId): Promise<readonly PresenceHint[]>;
+}
+export declare class PostgresActivityStore implements ActivityStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    append(tenant: TenantId, input: ActivityAppendInput): Promise<ActivityTail>;
+    read(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
+}

package/dist/stores/core/quota.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Postgres {@link QuotaStore} — entitlement, usage, reservation (§12.7.6-12.7.7).
+ *
+ * The invariant this file exists to hold is
+ * `committed + reserved + expected <= hardLimitBytes`, and the reason it is the
+ * hardest statement in the slice is that the obvious shapes all get it wrong in
+ * a way nothing throws about.
+ *
+ * **Why `reserve` opens a transaction.** Admission is one guarded
+ * `INSERT ... SELECT ... WHERE`, exactly as every other CAS in this package is
+ * one guarded statement. But the guard's operand is an AGGREGATE over the
+ * tenant's live reservations, and under READ COMMITTED a statement's snapshot
+ * is taken when the statement starts. Two concurrent reservers therefore both
+ * read a pre-insert world and both pass — the classic oversell. Postgres'
+ * EvalPlanQual re-check, which is what makes `UPDATE ... WHERE status = $x` a
+ * genuine CAS elsewhere in this package, re-evaluates the qual only against the
+ * updated TARGET row; a subquery over another table keeps the original
+ * snapshot. So no single statement over this shape can serialize reservers.
+ *
+ * The two ways out are a counter column CAS'd in place, or a lock. The counter
+ * loses: it has to be decremented on all three of finalize / abort / expire,
+ * and a path that settles without decrementing leaves a tenant permanently
+ * short of quota it actually released — durable drift, invisible until someone
+ * audits. So `storage_usage` has NO `reserved_bytes` column and
+ * `TenantStorageUsage.reservedBytes` is a `SUM` over live reservations, which
+ * cannot drift, and admission takes `FOR UPDATE` on the tenant's entitlement
+ * row first. The next statement in that transaction takes a FRESH snapshot,
+ * acquired behind the lock, so it sees every committed reservation. This is the
+ * "row-locked transaction" `packages/core/src/in-memory/quota.ts` names as the
+ * Postgres shape.
+ *
+ * What is NOT happening here: a read whose result is compared in TypeScript and
+ * then written. Every admission decision lives in the SQL guard. The reads on
+ * the rejection path exist only to answer "which of the five typed rejections
+ * is this", after the write has already been refused.
+ *
+ * Nothing in this file calls SQL `now()`. Every instant is the injected clock's,
+ * so reservation expiry is assertable under a test clock — and
+ * `__tests__/constraints.test.ts` scans this directory to keep it that way.
+ */
+import { type Clock, type MailboxUsageDeltaInput, type QuotaStore, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type StorageStatus, type TenantId, type TenantStorageEntitlement, type TenantStorageEntitlementInput, type TenantStorageUsage } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresQuotaStore implements QuotaStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    readEntitlement(tenant: TenantId): Promise<TenantStorageEntitlement | undefined>;
+    writeEntitlement(tenant: TenantId, input: TenantStorageEntitlementInput): Promise<TenantStorageEntitlement>;
+    readUsage(tenant: TenantId): Promise<TenantStorageUsage>;
+    readStatus(tenant: TenantId): Promise<StorageStatus>;
+    readReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation | undefined>;
+    reserve(tenant: TenantId, input: StorageReservationInput): Promise<StorageReservation>;
+    finalizeReservation(tenant: TenantId, input: StorageFinalizeInput): Promise<StorageFinalizeResult>;
+    abortReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation>;
+    expireReservations(tenant: TenantId): Promise<readonly StorageReservation[]>;
+    applyMailboxDelta(tenant: TenantId, input: MailboxUsageDeltaInput): Promise<TenantStorageUsage>;
+}

package/dist/stores/core/skill-pack.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Postgres {@link SkillPackStore} (plan `skill-pack-delivery-channel`, Phase 2).
+ *
+ * A faithful projection of {@link InMemorySkillPackStore}: same validators, same
+ * refusals, same read shape. What `publish` checks and what it rejects is core's
+ * decision, not this store's — it reuses `checkSkillPackManifest` /
+ * `checkSkillPackEntry` and the manifest/file cross-checks the reference
+ * performs, because this store cannot hash (integrity is the installing device's
+ * job) but it CAN refuse to persist a pack whose declared path set or byte sizes
+ * already disagree with the bytes it was handed. Storing that pair unchecked
+ * would hand a device a corrupt publication it could not tell from a tampered
+ * response.
+ *
+ * Two tables, one per level of the manifest (`deploy/sql/0005_skill_packs.sql`):
+ * `skill_pack` carries the pack-level fields a `SkillPackManifest` needs to be
+ * reconstructed (version, description, the pack content hash), and
+ * `skill_pack_file` carries one row per declared file with its content hash,
+ * byte size, and the UTF-8 text itself. A publish is a single transaction that
+ * upserts the pack row and REPLACES its file set, so a re-publish of a changed
+ * pack under the same name never leaves a stale file behind.
+ *
+ * `byte_size` is `integer`, not `bigint`: `SkillPackFile.byteSize` is a core
+ * `number` bounded by `SKILL_PACK_FILE_MAX_BYTES` (256 KiB), unlike the quota
+ * and truth byte fields the contract declares as `bigint`. `integer` is the
+ * type that round-trips a `number` without a cast at the boundary — the same
+ * call `object_manifest.ref_count` makes for a small count.
+ *
+ * No injected clock: a manifest carries no timestamp, so this store writes none
+ * and asks the database for none. That mirrors the reference, which takes no
+ * clock either.
+ */
+import { type SkillPackFileContent, type SkillPackListQuery, type SkillPackManifest, type SkillPackPublishInput, type SkillPackStore, type TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresSkillPackStore implements SkillPackStore {
+    #private;
+    constructor(pool: Pool);
+    publish(tenant: TenantId, input: SkillPackPublishInput): Promise<SkillPackManifest>;
+    get(tenant: TenantId, name: string): Promise<SkillPackManifest | undefined>;
+    list(tenant: TenantId, query: SkillPackListQuery): Promise<readonly SkillPackManifest[]>;
+    readFile(tenant: TenantId, name: string, path: string): Promise<SkillPackFileContent | undefined>;
+}

package/dist/stores/core/truth.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Postgres {@link TruthStore} (§12.3, §12.6.4).
+ *
+ * Two write models over one table, and the primary key does the deciding for
+ * both.
+ *
+ * - `task.terminal` is first-write-wins: `INSERT ... ON CONFLICT DO NOTHING`
+ *   plus an equality re-read. A replay of the identical hash returns the
+ *   ORIGINAL row — same `rev`, same `writtenAt`, same `requestId` — and a
+ *   different hash for the same task is refused with the record already
+ *   committed attached. An upsert would pass a naive "write it twice" check
+ *   while quietly restamping the first fact, which §12.6.4 forbids outright.
+ * - `profile` / `memory` are per-key snapshots under an `expectedRev` CAS:
+ *   `UPDATE ... WHERE rev = $expectedRev`, with `expectedRev = 0` expressed as
+ *   the insert. Zero rows is the conflict, and the caller gets the current
+ *   record — or `undefined` when it claimed a revision of a record that does
+ *   not exist.
+ *
+ * The store never merges bodies. A conflict hands back what it lost to and
+ * stops, because the device holding the context is the only party that can
+ * decide what the merged truth should be (§12.3).
+ */
+import { type Clock, type SnapshotWriteInput, type TenantId, type TerminalWriteInput, type TruthManifestEntry, type TruthManifestQuery, type TruthRecord, type TruthRecordSelector, type TruthStore } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresTruthStore implements TruthStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    writeTerminal(tenant: TenantId, input: TerminalWriteInput): Promise<TruthRecord>;
+    writeSnapshot(tenant: TenantId, input: SnapshotWriteInput): Promise<TruthRecord>;
+    getRecord(tenant: TenantId, selector: TruthRecordSelector): Promise<TruthRecord | undefined>;
+    listManifest(tenant: TenantId, query: TruthManifestQuery): Promise<readonly TruthManifestEntry[]>;
+}

package/dist/stores/dedup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Postgres {@link InboundDedupStore} (N3): bounded at-most-once processing.
+ *
+ * Check-and-record is one `INSERT ... ON CONFLICT DO NOTHING`, so a
+ * composition cannot accidentally split it into a racy read-then-write: the
+ * primary key does the deciding, and zero returned rows means "already seen".
+ *
+ * Reclaim runs only on the path that actually grew the table, and it deletes
+ * oldest-first down to `DEDUP_RING_CAPACITY` rows for that device — the same
+ * bound the in-memory ring holds. The ids most likely to be redelivered are the
+ * recent ones, so dropping the oldest is the retention that matches the wire's
+ * behavior. An unbounded set would pass every duplicate assertion and still let
+ * one chatty device grow this table without limit.
+ */
+import { type InboundDedupStore } from '@byok-sdk/cloud';
+import type { TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresInboundDedupStore implements InboundDedupStore {
+    #private;
+    constructor(pool: Pool, capacity?: number);
+    checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
+}

package/dist/stores/devices.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Postgres {@link DeviceDirectory}.
+ *
+ * Rows live under the composite key `(tenant_id, device_id)`, so a cross-tenant
+ * read is not "denied" — it addresses a different key space and finds nothing
+ * (§12.6.2 layer 3). `resolveByDeviceId` is the documented pre-tenant entry
+ * point, and it is safe for exactly one reason: the row it returns CARRIES its
+ * tenant, so the caller never compares a tenant it was handed against one it
+ * guessed. One row, two access paths, never two copies to keep in sync — a
+ * stale pre-tenant index would be a revoked device that can still get a token.
+ */
+import type { TenantId } from '@byok-sdk/core';
+import type { DeviceDirectory, DeviceRecord, DeviceRegistration } from '@byok-sdk/cloud';
+import type { Pool } from 'pg';
+export declare class PostgresDeviceDirectory implements DeviceDirectory {
+    #private;
+    constructor(pool: Pool);
+    register(tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
+    get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
+    revoke(tenant: TenantId, deviceId: string): Promise<void>;
+    list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The Postgres composition of the cloud-local ports.
+ *
+ * Seven durable stores, one object-storage blob store, one in-memory limiter:
+ *
+ * - Six durable ones have rows in `deploy/sql/0001_cloud_local.sql`; S6's
+ *   proof receipt authority is the seventh, in `0004_device_proof_truth.sql`.
+ * - `blobs` is the R2 adapter over the `object_manifest` row the core store
+ *   already owns: metadata in Postgres, bytes in the object store, one
+ *   reserve/verify protocol binding them (design §6). It supplies grants only,
+ *   and this composition deliberately hands `createByokCloud` NO
+ *   `BlobContentProxy` — a device uploading straight to R2 is what having no
+ *   byte-proxy path means, and saying so by absence is what keeps the two
+ *   `/content` routes from mounting on a deployment that cannot serve them.
+ * - `rateLimiter` gets the allow-all reference and NO table, by design
+ *   (docs/researches/s4a-dataplane-design.md §5). Persisting an allow-all would
+ *   create a table that is always empty, and a real limiter is edge/infra work
+ *   whose implementation would not be a per-request Postgres write either.
+ */
+import { type CloudStores } from '@byok-sdk/cloud';
+import type { CloudCrypto } from '@byok-sdk/cloud';
+import type { Clock } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+import { type R2BlobStoreOptions } from './r2-blobs';
+export { PostgresDeviceDirectory } from './devices';
+export { PostgresInboundDedupStore } from './dedup';
+export { PostgresNonceStore } from './nonces';
+export { PostgresPairingCodeStore } from './pairing-codes';
+export { PostgresRequestReceiptStore } from './receipts';
+export { PostgresProofRequestReceiptStore } from './proof-receipts';
+export { PostgresTaskAttemptStore } from './task-attempts';
+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 './r2-blobs';
+export type { ObjectStoreFetch, R2BlobErrorCode, R2BlobStoreOptions } from './r2-blobs';
+export type { R2DeleteResult, R2ListedObject, R2ObjectMaintenance, R2ObjectMaintenanceOptions, R2ObjectPage, } from './r2-blobs';
+/** Every cloud-local port. All nine, or it is not a composition. */
+export type PostgresCloudStores = CloudStores;
+/** Everything the blob store needs that is not already a composition-wide input. */
+export type PostgresObjectStorageOptions = Omit<R2BlobStoreOptions, 'objects'>;
+export interface PostgresCloudStoreOptions {
+    readonly pool: Pool;
+    /**
+     * The clock every TTL and timestamp in this composition reads. Injected, not
+     * the database's own: expiry has to be assertable under a test clock, and a
+     * store that asks the server for the time cannot be.
+     */
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+    /**
+     * Where the bytes go. Required, because a composition that cannot say where
+     * its objects live cannot honestly claim the `blobs` port — and the
+     * conformance suite certifies compositions whole, never in parts.
+     */
+    readonly objectStorage: PostgresObjectStorageOptions;
+}
+export declare function createPostgresCloudStores(options: PostgresCloudStoreOptions): PostgresCloudStores;

package/dist/stores/nonces.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Postgres {@link NonceStore}: single-use challenge nonces bound to the
+ * (tenant, device) they were issued for, expiring after `NONCE_TTL_MS`
+ * (docs/protocol.md §6.2).
+ *
+ * Expiry is compared against the INJECTED clock, never the database's `now()`.
+ * A store that asked the server for the time would be unassertable under a test
+ * clock, and the conformance suite's TTL dimension would have to sleep — which
+ * is how a replay-window regression ships unnoticed.
+ *
+ * `issue` sweeps this device's spent and expired rows inline, same posture as
+ * the in-memory reference and the reference server: a long-lived deployment
+ * never calls a sweep on a timer, and the sweep is bounded to one (tenant,
+ * device) so it stays proportional to the caller that triggered it.
+ */
+import { type NonceStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { CloudCrypto } from '@byok-sdk/cloud';
+import type { Pool } from 'pg';
+export declare class PostgresNonceStore implements NonceStore {
+    #private;
+    constructor(pool: Pool, clock: Clock, crypto: CloudCrypto, ttlMs?: number);
+    issue(tenant: TenantId, deviceId: string): Promise<string>;
+    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
+    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+}

package/dist/stores/pairing-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Postgres {@link PairingCodeStore}: single-use codes bound to the tenant and
+ * product they were minted for.
+ *
+ * Redemption is one guarded statement. `UPDATE ... WHERE redeemed_at IS NULL
+ * AND expires_at >= $now RETURNING ...` consumes and reports in the same
+ * round trip, and zero rows is the typed rejection. A read-then-write would let
+ * two concurrent redemptions both observe an unused code, and single-use is
+ * exactly what makes the caller's "redeem, then register the device" sequence
+ * exclusive.
+ *
+ * Unknown, expired, and already-used all answer `undefined`. The reference
+ * server distinguishes them in its 401 text; a hosted multi-tenant surface
+ * deliberately does not — the code is a bearer credential addressable across
+ * every tenant, and "already used" versus "never existed" is precisely the
+ * difference an attacker enumerating codes would pay for.
+ */
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '@byok-sdk/cloud';
+import type { Pool } from 'pg';
+export declare class PostgresPairingCodeStore implements PairingCodeStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
+    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+}

package/dist/stores/proof-receipts.d.ts

@@ -0,0 +1,12 @@
+import type { ProofRequestReceipt, ProofRequestReceiptInput, ProofRequestReceiptStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+export declare class PostgresProofRequestReceiptStore implements ProofRequestReceiptStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    record(tenant: TenantId, input: ProofRequestReceiptInput): Promise<{
+        readonly receipt: ProofRequestReceipt;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, requestId: string): Promise<ProofRequestReceipt | undefined>;
+}