@byok-sdk/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ancienttwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @byok-sdk/core
+
+Tenant-first platform contracts, branded identity types, store ports, device
+proof canonicalization, object/quota contracts, and in-memory reference stores.
+This package is runtime-neutral: it has no Node built-in or protocol dependency.
+
+```ts
+import { tenantId, InMemoryCoreStores } from '@byok-sdk/core';
+```
+
+MIT licensed. Node.js 20 or newer.

package/dist/attestation.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Device proof envelope and canonical signing bytes (§12.6.3, sprint §S6.2).
+ *
+ * Three things live here and nothing else:
+ *
+ * 1. **The protected-claims schema.** Every field a signature must cover so the
+ *    proof binds a *specific request*: tenant, product, device, key + epoch,
+ *    request id, operation, resource, the request line (method+path or a stable
+ *    operation id), and the body's hash *and* size. Signing only the body is
+ *    forbidden — it would let a valid proof be replayed against a different
+ *    operation or resource.
+ * 2. **A dependency-free deterministic canonicalizer.** RFC 8785 (JCS) in the
+ *    narrow subset the envelope allows. Node and Workers must produce
+ *    byte-identical output, so the accepted value space is deliberately small:
+ *    strings, booleans, null, safe integers, plain objects, arrays. Floats,
+ *    non-safe integers, `NaN`, `Infinity`, `undefined`, `bigint`, dates and
+ *    class instances throw instead of being coerced — a signature over a value
+ *    whose serialization is implementation-defined is not a signature.
+ * 3. **The verify port.** An interface, never an implementation: core is
+ *    Node-free and Workers-safe, and `node:crypto` and WebCrypto disagree about
+ *    key handling. The composition brings its own verifier.
+ *
+ * Claims are **untrusted input**. `tenantId` here is a plain string, not a
+ * branded `TenantId`, because a device asserting a tenant proves nothing: the
+ * claim is a lookup key used to load the device row, and the row is the
+ * authority (§12.6.2 layer 5). Branding happens after that lookup, not here.
+ */
+import { z } from 'zod';
+/** Envelope schema id, self-consistent with the domain prefix below. */
+export declare const DEVICE_PROOF_SCHEMA_ID = "byok-device-proof-v1";
+/**
+ * Domain separation prefix (§12.6.3). Prepended to the canonical claim bytes
+ * before signing so a device-proof signature can never be replayed as a nonce
+ * signature (`byok-nonce-v1\n`) or a record attestation.
+ */
+export declare const DEVICE_PROOF_DOMAIN_PREFIX = "byok-device-proof-v1\n";
+export declare const DEVICE_PROOF_VERSION = 1;
+/** Signature algorithms this envelope version admits. */
+export declare const DEVICE_PROOF_ALGORITHMS: readonly ['ed25519'];
+export type DeviceProofAlgorithm = (typeof DEVICE_PROOF_ALGORITHMS)[number];
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * Canonical JSON text for `value`, per RFC 8785 restricted to the value space
+ * above. Key insertion order never affects the output; anything outside the
+ * accepted space throws `proof_canonicalization_failed`.
+ */
+export declare function canonicalizeJson(value: JsonValue): string;
+/** UTF-8 bytes of {@link canonicalizeJson}. `TextEncoder` is a platform global on Node and Workers. */
+export declare function canonicalizeJsonBytes(value: JsonValue): Uint8Array;
+/**
+ * The signed claim set (§S6.2).
+ *
+ * The request line is expressible two ways — `method` + `path`, or a stable
+ * `operationId` — and exactly one form must be present. Allowing both at once
+ * would create two different canonical byte strings for one request; allowing
+ * neither would drop the operation binding the whole design rests on.
+ */
+export declare const DeviceProofProtectedClaimsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    tenantId: z.ZodString;
+    productId: z.ZodString;
+    deviceId: z.ZodString;
+    keyId: z.ZodString;
+    keyEpoch: z.ZodNumber;
+    requestId: z.ZodString;
+    operation: z.ZodString;
+    resource: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    operationId: z.ZodOptional<z.ZodString>;
+    bodySha256: z.ZodString;
+    bodySize: z.ZodNumber;
+    issuedAt: z.ZodISODateTime;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    nonce: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type DeviceProofProtectedClaims = z.infer<typeof DeviceProofProtectedClaimsSchema>;
+export declare const DeviceProofEnvelopeV1Schema: z.ZodObject<{
+    schema: z.ZodLiteral<"byok-device-proof-v1">;
+    algorithm: z.ZodEnum<{
+        ed25519: "ed25519";
+    }>;
+    protected: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        tenantId: z.ZodString;
+        productId: z.ZodString;
+        deviceId: z.ZodString;
+        keyId: z.ZodString;
+        keyEpoch: z.ZodNumber;
+        requestId: z.ZodString;
+        operation: z.ZodString;
+        resource: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        operationId: z.ZodOptional<z.ZodString>;
+        bodySha256: z.ZodString;
+        bodySize: z.ZodNumber;
+        issuedAt: z.ZodISODateTime;
+        expiresAt: z.ZodOptional<z.ZodISODateTime>;
+        nonce: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    signature: z.ZodString;
+}, z.core.$strict>;
+export type DeviceProofEnvelopeV1 = z.infer<typeof DeviceProofEnvelopeV1Schema>;
+/**
+ * Parses an envelope fail-closed.
+ *
+ * @throws {ByokCoreError} code `proof_envelope_invalid`.
+ */
+export declare function parseDeviceProofEnvelope(input: unknown): DeviceProofEnvelopeV1;
+/**
+ * Projects claims into the exact JSON object that gets canonicalized.
+ *
+ * Built field by field rather than by spreading the parsed object: an absent
+ * optional must be an *absent key*, never a key holding `undefined`, or
+ * `{nonce: undefined}` and `{}` would be the same request with two different
+ * signatures. The canonicalizer refuses `undefined` outright, so this
+ * projection is where absence is decided.
+ */
+export declare function deviceProofCanonicalClaims(claims: DeviceProofProtectedClaims): JsonObject;
+/** Canonical JSON text of the protected claim set, without the domain prefix. */
+export declare function deviceProofCanonicalJson(claims: DeviceProofProtectedClaims): string;
+/**
+ * The exact bytes a device signs and a verifier reconstructs:
+ * `byok-device-proof-v1\n` followed by the canonical claim JSON, UTF-8 encoded.
+ *
+ * Frozen by `src/__tests__/golden/device-proof-v1.canonical.json`.
+ */
+export declare function deviceProofSigningInput(claims: DeviceProofProtectedClaims): Uint8Array;
+export interface DeviceProofVerifyInput {
+    readonly algorithm: DeviceProofAlgorithm;
+    /** Raw public key, base64url — the JWK `x` encoding the device registry stores. */
+    readonly publicKey: string;
+    readonly signature: string;
+    readonly signingInput: Uint8Array;
+}
+/**
+ * Injected signature verification.
+ *
+ * Not a store port, so it has no tenant parameter: it answers a pure
+ * cryptographic question about bytes. Deciding *which* key to check against is
+ * the caller's tenant-scoped device-row lookup, and keeping that out of here is
+ * what stops a verifier from becoming a second authority on device identity.
+ */
+export interface DeviceProofVerifier {
+    verify(input: DeviceProofVerifyInput): Promise<boolean>;
+}

package/dist/blob.d.ts

@@ -0,0 +1,116 @@
+import type { TenantId } from './tenant';
+/** `sha256:<64 lowercase hex>`. The only content-address form core accepts. */
+export declare const CONTENT_HASH_PATTERN: RegExp;
+/** A validated content address. Branded so an unvalidated digest cannot stand in for one. */
+export type ContentHash = string & {
+    readonly __byokContentHash: unique symbol;
+};
+/**
+ * The single mint point for {@link ContentHash}.
+ *
+ * Fail-closed on uppercase hex: accepting both cases would make the same bytes
+ * addressable under two keys, which breaks per-tenant deduplication and the
+ * "count each hash once" billing rule (§12.7.6).
+ *
+ * @throws {ByokCoreError} code `content_hash_invalid`.
+ */
+export declare function contentHash(value: string): ContentHash;
+/** Non-throwing form of {@link contentHash}. */
+export declare function isContentHash(value: unknown): value is ContentHash;
+/**
+ * Tenant-scoped object key, e.g.
+ * `tenants/<tenantId>/objects/sha256/<hex>` (§12.7.4).
+ */
+export declare function tenantObjectKey(tenant: TenantId, hash: ContentHash): string;
+/**
+ * Object manifest lifecycle (§12.7.8).
+ *
+ * `pending` exists because Postgres and R2 have no shared transaction: the row
+ * is written before the bytes land, and only `committed` rows may be referenced
+ * by a truth record. `delete_pending` is the tombstone the GC worker drives, so
+ * a failed R2 delete is retryable instead of leaving usage silently wrong.
+ */
+export declare const OBJECT_STATES: readonly ['pending', 'committed', 'delete_pending', 'deleted'];
+export type ObjectState = (typeof OBJECT_STATES)[number];
+/** Legal manifest transitions. Anything else raises `object_state_invalid`. */
+export declare const OBJECT_STATE_TRANSITIONS: Readonly<Record<ObjectState, readonly ObjectState[]>>;
+export declare function isLegalObjectTransition(from: ObjectState, to: ObjectState): boolean;
+/** One row of `object_manifest` (§12.7.6). */
+export interface ObjectManifestEntry {
+    readonly tenantId: TenantId;
+    readonly hash: ContentHash;
+    /** Declared at reservation time, re-verified at commit against the store's `HEAD`. */
+    readonly byteSize: bigint;
+    readonly contentType: string;
+    readonly state: ObjectState;
+    /** Number of live {@link ObjectReference} rows. `0` makes the object GC-eligible after grace. */
+    readonly refCount: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** Set when the row entered `delete_pending`; the grace window is measured from here. */
+    readonly deletePendingAt?: string;
+}
+/** What references an object. `refKind`/`refId` are opaque to core. */
+export interface ObjectReference {
+    readonly tenantId: TenantId;
+    readonly hash: ContentHash;
+    readonly refKind: string;
+    readonly refId: string;
+    readonly createdAt: string;
+}
+export interface ObjectManifestInput {
+    readonly hash: ContentHash;
+    readonly byteSize: bigint;
+    readonly contentType: string;
+}
+/**
+ * Finalize input. `byteSize`/`contentType` are what the composition actually
+ * observed on the object store, not what the client declared — the whole point
+ * of the check is that the two can differ (§12.7.7 step 4).
+ */
+export interface ObjectCommitInput {
+    readonly hash: ContentHash;
+    readonly observedByteSize: bigint;
+    readonly observedContentType: string;
+}
+export interface ObjectReferenceInput {
+    readonly hash: ContentHash;
+    readonly refKind: string;
+    readonly refId: string;
+}
+export interface ObjectListQuery {
+    readonly state?: ObjectState;
+    /**
+     * Only rows whose `deletePendingAt` is at or before this instant.
+     *
+     * Must be a **canonical ISO-8601 UTC instant** (`YYYY-MM-DDTHH:mm:ss.sssZ`);
+     * anything else is rejected with `timestamp_not_canonical`, because the
+     * in-memory composition compares it as a string and a SQL composition
+     * compares it as a `timestamptz` — see `time.ts`.
+     */
+    readonly deletePendingBefore?: string;
+    readonly limit?: number;
+}
+/**
+ * Object manifest port. Tenant-first, async, metadata only.
+ *
+ * Raises: `object_not_found`, `object_state_invalid`,
+ * `storage_integrity_mismatch` (commit observed size/type disagreeing with the
+ * declared manifest row), `timestamp_not_canonical` (a `list` query whose
+ * `deletePendingBefore` is not a canonical ISO-8601 UTC instant).
+ */
+export interface ObjectStore {
+    /** Creates or returns the `pending` row for `hash`. Idempotent per (tenant, hash). */
+    putManifest(tenant: TenantId, input: ObjectManifestInput): Promise<ObjectManifestEntry>;
+    /** `pending` → `committed` after verifying observed size/type. */
+    commit(tenant: TenantId, input: ObjectCommitInput): Promise<ObjectManifestEntry>;
+    get(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry | undefined>;
+    list(tenant: TenantId, query: ObjectListQuery): Promise<readonly ObjectManifestEntry[]>;
+    /** Idempotent per (tenant, hash, refKind, refId) — re-adding does not double-count. */
+    addReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    removeReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    /** Tombstone step 1: only legal at `refCount === 0`. */
+    markDeletePending(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+    /** Tombstone step 3: the object store delete succeeded. */
+    markDeleted(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+}

package/dist/board.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Board coordination state (§12.3).
+ *
+ * This is the *human and multi-device* collaboration lifecycle, and it is a
+ * separate vocabulary from the frozen wire execution vocabulary on purpose. One
+ * run attempt is not one work item: an item can outlive several attempts, and a
+ * finished attempt does not mean a human accepted the result. The constraint
+ * test asserts that no wire execution state name appears in this file — if the
+ * two vocabularies ever merge, status sniffing comes back and the board becomes
+ * a second, unreliable execution authority.
+ *
+ * Three invariants the ports below encode:
+ *
+ * - **assignee and status are two fields**, not one enum. "Who holds it" and
+ *   "where it is" change independently.
+ * - **every mutation is a CAS.** `claim` compares against "unheld"; every status
+ *   move carries `expectedStatus`. There is no last-write-wins path.
+ * - **conflicts return the snapshot they lost to**, so the caller re-decides
+ *   against real state instead of retrying blind.
+ */
+import type { TenantId } from './tenant';
+/** The five board statuses. `closed` means "terminated, unaccepted" (§12.3). */
+export declare const BOARD_STATUSES: readonly ['todo', 'in_progress', 'in_review', 'done', 'closed'];
+export type BoardStatus = (typeof BOARD_STATUSES)[number];
+/**
+ * Legal transitions, transcribed from the §12.3 state diagram.
+ *
+ * `in_review → done` is the human acceptance step: a device reporting a
+ * terminal record can push an item to `in_review`, never straight to `done`.
+ * `done` and `closed` are sinks — if archival semantics are ever needed, §12.3
+ * pins the answer to an `archivedAt` field, not a sixth status.
+ */
+export declare const BOARD_TRANSITIONS: Readonly<Record<BoardStatus, readonly BoardStatus[]>>;
+export declare function isLegalBoardTransition(from: BoardStatus, to: BoardStatus): boolean;
+/** Who currently holds the item. Separate from {@link BoardItem.status}. */
+export interface BoardAssignee {
+    readonly holderId: string;
+    readonly heldSince: string;
+}
+/**
+ * One work item.
+ *
+ * `boardSeq` is monotonic **per tenant** and bumps on every mutation, which is
+ * what makes incremental list polling possible without a cross-tenant sequence
+ * (a global sequence would leak other tenants' write rate).
+ */
+export interface BoardItem {
+    readonly tenantId: TenantId;
+    readonly itemId: string;
+    readonly channel: string;
+    readonly title: string;
+    readonly status: BoardStatus;
+    readonly assignee?: BoardAssignee;
+    readonly boardSeq: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface BoardItemInput {
+    readonly itemId: string;
+    readonly channel: string;
+    readonly title: string;
+    /** Defaults to `todo`. Creating directly into a sink status is legal but explicit. */
+    readonly status?: BoardStatus;
+}
+export interface BoardListQuery {
+    /** Exclusive lower bound on `boardSeq`, for incremental polling. */
+    readonly afterSeq?: number;
+    readonly channel?: string;
+    readonly status?: BoardStatus;
+    readonly limit?: number;
+}
+export interface BoardPage {
+    readonly items: readonly BoardItem[];
+    /** Highest `boardSeq` in this page, or the requested `afterSeq` when empty. */
+    readonly nextSeq: number;
+    readonly hasMore: boolean;
+}
+export interface BoardClaimInput {
+    readonly itemId: string;
+    readonly holderId: string;
+    /**
+     * Status the claimer believes the item is in. Defaults to `todo`; supplying
+     * it explicitly makes the claim a full CAS rather than an assignee-only one.
+     *
+     * The CAS holds on the idempotent path too: a re-claim by the current holder
+     * that supplies a stale `expectedStatus` fails with `board_status_conflict`
+     * and the current item. The default is *not* applied there — a retry of a
+     * successful claim legitimately observes `in_progress`.
+     */
+    readonly expectedStatus?: BoardStatus;
+}
+export interface BoardUnclaimInput {
+    readonly itemId: string;
+    /** Must match the current holder — releasing someone else's item is not a legal move. */
+    readonly holderId: string;
+}
+export interface BoardStatusUpdateInput {
+    readonly itemId: string;
+    readonly expectedStatus: BoardStatus;
+    readonly status: BoardStatus;
+    /** Optional holder assertion, for transitions only the holder may make. */
+    readonly holderId?: string;
+}
+/**
+ * Board port. Tenant-first, async.
+ *
+ * Raises: `board_item_not_found`, `board_claim_conflict` (loser gets the
+ * winner's holder snapshot), `board_status_conflict` (`expectedStatus` missed —
+ * carries the current item), `board_transition_invalid` (move not in
+ * {@link BOARD_TRANSITIONS} — also carries the current item), `board_not_held`.
+ */
+export interface BoardStore {
+    create(tenant: TenantId, input: BoardItemInput): Promise<BoardItem>;
+    get(tenant: TenantId, itemId: string): Promise<BoardItem | undefined>;
+    list(tenant: TenantId, query: BoardListQuery): Promise<BoardPage>;
+    /** CAS on "unheld". Exactly one concurrent caller wins; losers get the holder snapshot. */
+    claim(tenant: TenantId, input: BoardClaimInput): Promise<BoardItem>;
+    unclaim(tenant: TenantId, input: BoardUnclaimInput): Promise<BoardItem>;
+    updateStatus(tenant: TenantId, input: BoardStatusUpdateInput): Promise<BoardItem>;
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Capability declaration (ADR-010).
+ *
+ * A client learns what a deployment supports by reading a declaration, never by
+ * probing endpoints and interpreting 404/405/501. Status-code sniffing conflates
+ * "this build does not have that feature" with "that request was wrong" and
+ * with "a proxy ate it", and every consumer ends up with its own guess.
+ *
+ * The schema is intentionally the minimum that supports that rule: an opaque
+ * string set plus a monotonic declaration version. Capability names are host and
+ * deployment vocabulary — core validates their shape, never their meaning, so a
+ * new capability never requires a core release.
+ */
+import { z } from 'zod';
+export declare const CAPABILITY_DECLARATION_SCHEMA_ID = "byok-capabilities-v1";
+/** Capability names: lowercase dotted segments, e.g. `board.sse`, `storage.reservations`. */
+export declare const CAPABILITY_NAME_PATTERN: RegExp;
+export declare const CapabilityDeclarationSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"byok-capabilities-v1">;
+    version: z.ZodNumber;
+    capabilities: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type CapabilityDeclaration = z.infer<typeof CapabilityDeclarationSchema>;
+/**
+ * Parses a declaration fail-closed.
+ *
+ * @throws {ByokCoreError} code `capability_declaration_invalid`.
+ */
+export declare function parseCapabilityDeclaration(input: unknown): CapabilityDeclaration;
+export declare function hasCapability(declaration: CapabilityDeclaration, capability: string): boolean;
+/**
+ * The enforcement point ADR-010 exists for: a caller asserts the capability up
+ * front and gets a named failure, instead of issuing the request and guessing
+ * what the status code meant.
+ *
+ * @throws {ByokCoreError} code `capability_unavailable`.
+ */
+export declare function assertCapability(declaration: CapabilityDeclaration, capability: string): void;

package/dist/errors.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The one error taxonomy for `@byok-sdk/core`.
+ *
+ * Two rules the rest of the package is built around:
+ *
+ * 1. **One class, code-based branching.** Consumers switch on `error.code`, not
+ *    on class identity — the same idiom `@byok-sdk/keys` uses. A composition that
+ *    maps core errors onto HTTP does it with a code table, so adding a code is
+ *    an additive change instead of a new `instanceof` chain everywhere.
+ * 2. **Every conflict carries the current snapshot.** A CAS failure that
+ *    reports only "conflict" forces the caller into a second round trip and
+ *    invites last-write-wins retries. {@link CoreConflictError} therefore
+ *    carries `current` — the authoritative state the caller lost to — plus the
+ *    `observedAt` instant it was read at.
+ *
+ * This module imports nothing. It is the graph sink: `quota.ts` narrows
+ * {@link StorageErrorCode} out of this union and maps it to HTTP status, and
+ * every port module documents which codes it can raise. That keeps the code
+ * list in one place while letting each domain own its own status mapping.
+ */
+/**
+ * Every error code this package can raise.
+ *
+ * Codes are stable strings. Two groups are additionally **wire-stable** — a
+ * composition is expected to surface them verbatim to clients, so renaming one
+ * is a breaking change:
+ *
+ * - `terminal_conflict` (§12.6.4, HTTP 409)
+ * - the five `storage_*` codes (§12.7.7, see `quota.ts`)
+ */
+export declare const CORE_ERROR_CODES: {
+    readonly tenant_id_invalid: 'tenant_id_invalid';
+    readonly content_hash_invalid: 'content_hash_invalid';
+    readonly timestamp_not_canonical: 'timestamp_not_canonical';
+    readonly capability_declaration_invalid: 'capability_declaration_invalid';
+    readonly capability_unavailable: 'capability_unavailable';
+    readonly proof_envelope_invalid: 'proof_envelope_invalid';
+    readonly proof_canonicalization_failed: 'proof_canonicalization_failed';
+    readonly mailbox_message_not_found: 'mailbox_message_not_found';
+    readonly mailbox_cursor_regression: 'mailbox_cursor_regression';
+    readonly board_item_not_found: 'board_item_not_found';
+    readonly board_item_exists: 'board_item_exists';
+    readonly board_transition_invalid: 'board_transition_invalid';
+    readonly board_status_conflict: 'board_status_conflict';
+    readonly board_claim_conflict: 'board_claim_conflict';
+    readonly board_not_held: 'board_not_held';
+    readonly truth_record_not_found: 'truth_record_not_found';
+    readonly terminal_conflict: 'terminal_conflict';
+    readonly truth_revision_conflict: 'truth_revision_conflict';
+    readonly activity_capacity_invalid: 'activity_capacity_invalid';
+    readonly activity_batch_invalid: 'activity_batch_invalid';
+    readonly hint_ttl_invalid: 'hint_ttl_invalid';
+    readonly hint_rate_limited: 'hint_rate_limited';
+    readonly object_not_found: 'object_not_found';
+    readonly object_state_invalid: 'object_state_invalid';
+    readonly storage_entitlement_missing: 'storage_entitlement_missing';
+    readonly storage_entitlement_version_conflict: 'storage_entitlement_version_conflict';
+    readonly storage_reservation_not_found: 'storage_reservation_not_found';
+    readonly storage_object_too_large: 'storage_object_too_large';
+    readonly storage_quota_exceeded: 'storage_quota_exceeded';
+    readonly storage_reservation_expired: 'storage_reservation_expired';
+    readonly storage_integrity_mismatch: 'storage_integrity_mismatch';
+    readonly storage_write_suspended: 'storage_write_suspended';
+};
+export type CoreErrorCode = (typeof CORE_ERROR_CODES)[keyof typeof CORE_ERROR_CODES];
+/** Base error for every failure this package raises. */
+export declare class ByokCoreError extends Error {
+    readonly code: CoreErrorCode;
+    constructor(code: CoreErrorCode, message: string, options?: ErrorOptions);
+}
+/**
+ * A compare-and-set failure.
+ *
+ * `current` is the authoritative state at the moment the write was rejected —
+ * the board item whose status moved, the terminal record already committed, the
+ * entitlement row at a newer version. The caller re-decides against it; the
+ * store never merges (§12.3: "不做 silent last-write-wins", §12.6.4: 不覆写第一份事实).
+ */
+export declare class CoreConflictError<TCurrent> extends ByokCoreError {
+    readonly current: TCurrent;
+    readonly observedAt: string;
+    constructor(code: CoreErrorCode, message: string, current: TCurrent, observedAt: string, options?: ErrorOptions);
+}
+/** Narrows an unknown thrown value to a core error, optionally to one code. */
+export declare function isCoreError(value: unknown, code?: CoreErrorCode): value is ByokCoreError;
+/** Narrows an unknown thrown value to a conflict error carrying a snapshot. */
+export declare function isCoreConflictError<TCurrent>(value: unknown, code?: CoreErrorCode): value is CoreConflictError<TCurrent>;

package/dist/in-memory/blob.d.ts

@@ -0,0 +1,24 @@
+/**
+ * In-memory {@link ObjectStore} reference (§12.7.4, §12.7.8).
+ *
+ * Metadata only — there are no bytes here, and there are none in the Postgres
+ * composition either: the manifest is the transaction authority and the object
+ * store holds the payload. `refCount` is derived from the reference rows rather
+ * than incremented in place, so a double `addReference` for the same
+ * `(refKind, refId)` cannot inflate it and strand an object forever.
+ */
+import { type ContentHash, type ObjectCommitInput, type ObjectListQuery, type ObjectManifestEntry, type ObjectManifestInput, type ObjectReferenceInput, type ObjectStore } from '../blob';
+import type { Clock } from '../stores';
+import { type TenantId } from '../tenant';
+export declare class InMemoryObjectStore implements ObjectStore {
+    #private;
+    constructor(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/in-memory/board.d.ts

@@ -0,0 +1,26 @@
+/**
+ * In-memory {@link BoardStore} reference (§12.3).
+ *
+ * The claim path is the interesting one: because JavaScript resolves each
+ * `await` boundary atomically here, N concurrent `claim` calls serialize and
+ * exactly one finds `assignee === undefined`. A SQL composition gets the same
+ * outcome from a conditional `UPDATE ... WHERE assignee IS NULL`; the
+ * conformance suite asserts the outcome, not the mechanism.
+ *
+ * `boardSeq` is per tenant and bumps on every mutation, which is what makes
+ * `list({ afterSeq })` an incremental feed that cannot leak another tenant's
+ * write rate.
+ */
+import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardStore, type BoardUnclaimInput } from '../board';
+import type { Clock } from '../stores';
+import { type TenantId } from '../tenant';
+export declare class InMemoryBoardStore implements BoardStore {
+    #private;
+    constructor(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/in-memory/clock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A deterministic clock for the in-memory reference and the conformance suite.
+ *
+ * TTL behavior (presence expiry, activity expiry, reservation expiry) is part
+ * of the contract, and asserting it against a wall clock means either sleeping
+ * or accepting flakes. A composition under test injects one of these and moves
+ * time explicitly.
+ */
+import type { MutableClock } from '../stores';
+/** Fixed start instant, so golden-ish assertions in the suite read the same on every run. */
+export declare const IN_MEMORY_CLOCK_EPOCH = "2026-01-01T00:00:00.000Z";
+export declare function createMutableClock(start?: Date): MutableClock;

package/dist/in-memory/index.d.ts

@@ -0,0 +1,23 @@
+import type { Clock, CoreStores, MutableClock } from '../stores';
+export { createMutableClock, IN_MEMORY_CLOCK_EPOCH } from './clock';
+export { InMemoryMailboxStore } from './mailbox';
+export { InMemoryBoardStore } from './board';
+export { InMemoryTruthStore } from './truth';
+export { InMemoryPresenceStore, InMemoryActivityStore } from './presence';
+export { InMemoryObjectStore } from './blob';
+export { InMemoryQuotaStore } from './quota';
+export interface InMemoryCoreOptions {
+    /** Defaults to a fresh {@link createMutableClock}, so TTL behavior is deterministic. */
+    readonly clock?: Clock;
+}
+export interface InMemoryCoreComposition {
+    readonly stores: CoreStores;
+    /** The clock the stores read. Mutable only when the caller did not inject its own. */
+    readonly clock: Clock;
+}
+export declare function createInMemoryCoreStores(options?: InMemoryCoreOptions): InMemoryCoreComposition;
+/** Convenience for tests that need to move time: returns the composition and its mutable clock. */
+export declare function createInMemoryCoreCompositionWithClock(): {
+    readonly stores: CoreStores;
+    readonly clock: MutableClock;
+};

package/dist/in-memory/mailbox.d.ts

@@ -0,0 +1,12 @@
+import type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxCursorState, MailboxMessage, MailboxPage, MailboxReadQuery, MailboxRetentionInput, MailboxRetentionResult, MailboxStore } from '../mailbox';
+import type { Clock } from '../stores';
+import { type TenantId } from '../tenant';
+export declare class InMemoryMailboxStore implements MailboxStore {
+    #private;
+    constructor(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>;
+}