@byok-sdk/core 0.1.0

package/dist/presence.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Presence and activity hints (§12.3).
+ *
+ * Both are lossy, TTL-bounded, unsigned, and never authoritative. Expiry means
+ * *absence*, not a stale value: a hint past its TTL is invisible to readers, so
+ * nothing downstream can mistake an old level for a live one.
+ *
+ * These hints must never be used to derive coordination state, execution state,
+ * authorization, billing, or recovery — which is why this module shares no
+ * vocabulary with `board.ts` and no vocabulary with the frozen wire states. The
+ * constraint test enforces that separation by scanning this file for those
+ * names. A device that looks busy is not evidence that any particular work item
+ * moved anywhere.
+ *
+ * The activity tail is bounded by count and carries an explicit `dropped`
+ * counter: lossiness is written into the data instead of being hidden behind a
+ * stream that pretends to be complete.
+ */
+import type { TenantId } from './tenant';
+/** The five presence levels. */
+export declare const PRESENCE_LEVELS: readonly ['online', 'thinking', 'working', 'error', 'offline'];
+export type PresenceLevel = (typeof PRESENCE_LEVELS)[number];
+/** A device-level hint. `expiresAt` is authoritative: past it, the hint does not exist. */
+export interface PresenceHint {
+    readonly tenantId: TenantId;
+    readonly deviceId: string;
+    readonly level: PresenceLevel;
+    /** Free-form host label, bounded by the composition. Never parsed by core. */
+    readonly detail?: string;
+    readonly observedAt: string;
+    readonly expiresAt: string;
+}
+export interface PresenceHintInput {
+    readonly deviceId: string;
+    readonly level: PresenceLevel;
+    readonly detail?: string;
+    /** Hint lifetime. §12.7.5 suggests 60-120s for presence. */
+    readonly ttlMs: number;
+    /** Minimum time between accepted publications for this device. `0` explicitly disables throttling. */
+    readonly minimumIntervalMs: number;
+}
+/** One entry of a task's lossy tail. */
+export interface ActivityEntry {
+    readonly at: string;
+    readonly detail: string;
+}
+/**
+ * A task's bounded tail.
+ *
+ * `dropped` counts entries evicted by `capacity`, so a reader can tell the
+ * difference between "nothing happened" and "we lost the middle".
+ */
+export interface ActivityTail {
+    readonly tenantId: TenantId;
+    readonly taskId: string;
+    readonly entries: readonly ActivityEntry[];
+    readonly dropped: number;
+    readonly capacity: number;
+    readonly expiresAt: string;
+}
+export interface ActivityAppendInput {
+    readonly taskId: string;
+    /** One ProgressBatcher-shaped batch. Empty batches are rejected. */
+    readonly details: readonly string[];
+    /** Events the producer dropped before this batch reached the store. */
+    readonly dropped: number;
+    /** Tail lifetime. §12.7.5 suggests 5-15 minutes for activity. */
+    readonly ttlMs: number;
+    /** Maximum retained entries. Must be a positive integer. */
+    readonly capacity?: number;
+}
+/**
+ * Presence port. Tenant-first, async.
+ *
+ * Reads filter expired hints out rather than returning them with a flag: an
+ * expired hint is indistinguishable from one that was never written.
+ */
+export interface PresenceStore {
+    publish(tenant: TenantId, input: PresenceHintInput): Promise<PresenceHint>;
+    read(tenant: TenantId, deviceId: string): Promise<PresenceHint | undefined>;
+    list(tenant: TenantId): Promise<readonly PresenceHint[]>;
+}
+/**
+ * Activity port. Tenant-first, async.
+ *
+ * Raises: `activity_capacity_invalid` (non-positive or non-integer capacity —
+ * an unbounded tail is exactly what this contract exists to prevent),
+ * `activity_batch_invalid` (empty batch or invalid producer drop count).
+ */
+export interface ActivityStore {
+    append(tenant: TenantId, input: ActivityAppendInput): Promise<ActivityTail>;
+    read(tenant: TenantId, taskId: string): Promise<ActivityTail | undefined>;
+}
+/** Default tail capacity when an append does not specify one. */
+export declare const DEFAULT_ACTIVITY_CAPACITY = 50;

package/dist/principals.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Authenticated principals — layer 2 of the isolation model (§12.6.2).
+ *
+ * A handler never receives a raw tenant string; it receives a principal that
+ * already carries a minted {@link TenantId}. The two principal shapes are
+ * deliberately not one type with an optional `deviceId`: a control-plane caller
+ * that can write entitlements and a device that can write truth records have
+ * different authority, and a discriminated union makes a handler state which
+ * one it accepts.
+ *
+ * `keyId`/`keyEpoch` are **not** here. They are device-proof semantics
+ * (`plans/sprints/…sprint.md` §S6.2): the signing key's identity and rotation
+ * generation, resolved by looking up the device row during proof verification.
+ * Putting them on the principal would create permanently-empty fields on every
+ * principal minted by a non-proof path.
+ */
+import type { TenantId } from './tenant';
+/** Principal kinds. A composition may not invent a third without a contract change. */
+export declare const PRINCIPAL_KINDS: readonly ['device', 'control-plane'];
+export type PrincipalKind = (typeof PRINCIPAL_KINDS)[number];
+/**
+ * A paired device acting inside one tenant/product.
+ *
+ * Built only from a device row loaded with the tenant as part of the lookup key
+ * (§12.6.2 layer 5) — never from claims a device asserted about itself.
+ */
+export interface DevicePrincipal {
+    readonly kind: 'device';
+    readonly tenantId: TenantId;
+    readonly productId: string;
+    readonly deviceId: string;
+}
+/**
+ * The host's control plane acting on a tenant: entitlement writes, retention
+ * policy, administrative reads. Carries the operator identity for audit, which
+ * is opaque to the SDK.
+ */
+export interface ControlPlanePrincipal {
+    readonly kind: 'control-plane';
+    readonly tenantId: TenantId;
+    readonly operatorId: string;
+}
+/** Anything that can address a tenant-scoped store. */
+export type Principal = DevicePrincipal | ControlPlanePrincipal;
+export declare function isDevicePrincipal(principal: Principal): principal is DevicePrincipal;
+export declare function isControlPlanePrincipal(principal: Principal): principal is ControlPlanePrincipal;
+/**
+ * The tenant every store call must be scoped to.
+ *
+ * Exists so a handler cannot accidentally read `principal.tenantId` off one
+ * principal and pass a different tenant to a store: the facade that binds
+ * stores to a tenant takes this, not a loose string.
+ */
+export declare function principalTenant(principal: Principal): TenantId;

package/dist/quota.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Tenant storage entitlement, usage, reservation and retention (§12.7.6-12.7.7).
+ *
+ * The SDK does not know what a plan is. It never sees `free`, `pro`, a price, a
+ * currency, or a purchase flow — those belong to the host SaaS. What crosses
+ * this boundary is a *numeric, versioned* entitlement the host issues, and the
+ * constraint test asserts this file contains no plan-name or price vocabulary.
+ * The moment the SDK hardcodes a tier, every host is stuck with the SDK's
+ * commercial model.
+ *
+ * Byte counts are `bigint`. Serialization is a composition concern: JSON has no
+ * bigint, so a cloud handler renders them as decimal strings on the wire. Using
+ * `number` here would put a silent 2^53 ceiling into a storage quota contract.
+ *
+ * Reservation exists because Postgres and R2 have no shared transaction
+ * (§12.7.7). Every durable write reserves first, uploads second, finalizes
+ * third; the invariant `committed + reserved + expected <= hardLimit` is
+ * checked under the reservation lock, which is what makes concurrent uploads
+ * unable to oversell the tenant.
+ */
+import type { ContentHash } from './blob';
+import type { TenantId } from './tenant';
+/**
+ * The host-issued numeric entitlement (§12.7.6, verbatim).
+ *
+ * `version` is monotonic and CAS-checked on write: a delayed control-plane
+ * update must not resurrect an older plan over a newer one.
+ */
+export interface TenantStorageEntitlement {
+    tenantId: TenantId;
+    version: bigint;
+    hardLimitBytes: bigint;
+    maxObjectBytes: bigint;
+    maxInlineBytes: bigint;
+    mailboxLimitBytes: bigint;
+    retentionPolicyId: string;
+    /** Canonical ISO-8601 UTC instant — see {@link TenantStorageEntitlementInput}. */
+    downgradeGraceUntil?: string;
+}
+/**
+ * Measured tenant usage (§12.7.6, verbatim).
+ *
+ * Carries no `tenantId` because it is always read through a tenant-scoped port
+ * call — the tenant is the query, not a field of the answer.
+ */
+export interface TenantStorageUsage {
+    committedObjectBytes: bigint;
+    committedInlineBytes: bigint;
+    reservedBytes: bigint;
+    mailboxBytes: bigint;
+    objectCount: bigint;
+    updatedAt: string;
+}
+/** Entitlement write payload. `tenantId` comes from the port's first parameter. */
+export interface TenantStorageEntitlementInput {
+    readonly version: bigint;
+    readonly hardLimitBytes: bigint;
+    readonly maxObjectBytes: bigint;
+    readonly maxInlineBytes: bigint;
+    readonly mailboxLimitBytes: bigint;
+    readonly retentionPolicyId: string;
+    /**
+     * Deadline after which an over-limit tenant is suspended rather than blocked.
+     *
+     * Must be a **canonical ISO-8601 UTC instant** (`YYYY-MM-DDTHH:mm:ss.sssZ`);
+     * anything else is rejected with `timestamp_not_canonical`. The in-memory
+     * composition compares this deadline as a string and a SQL composition
+     * compares it as a `timestamptz`, and those two agree only on the canonical
+     * form — see `time.ts`.
+     */
+    readonly downgradeGraceUntil?: string;
+}
+/** Durable write classes a reservation can cover. */
+export declare const STORAGE_WRITE_KINDS: readonly ['object', 'inline'];
+export type StorageWriteKind = (typeof STORAGE_WRITE_KINDS)[number];
+export declare const STORAGE_RESERVATION_STATES: readonly ['reserved', 'committed', 'aborted', 'expired'];
+export type StorageReservationState = (typeof STORAGE_RESERVATION_STATES)[number];
+export interface StorageReservation {
+    readonly tenantId: TenantId;
+    readonly reservationId: string;
+    readonly state: StorageReservationState;
+    readonly kind: StorageWriteKind;
+    readonly expectedBytes: bigint;
+    readonly contentHash: ContentHash;
+    readonly contentType: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly settledAt?: string;
+}
+export interface StorageReservationInput {
+    readonly reservationId: string;
+    readonly kind: StorageWriteKind;
+    readonly expectedBytes: bigint;
+    readonly contentHash: ContentHash;
+    readonly contentType: string;
+    readonly ttlMs: number;
+}
+/**
+ * Finalize payload. Size/type are what the composition observed on the object
+ * store, not what the client promised — disagreement is
+ * `storage_integrity_mismatch`.
+ *
+ * Hash identity stays on the reservation as the authenticated daemon's
+ * declaration (ADR-024). Object-store HEAD does not independently observe a
+ * SHA-256 digest, so accepting one here would turn a copied declaration into a
+ * false verification claim.
+ */
+export interface StorageFinalizeInput {
+    readonly reservationId: string;
+    readonly observedByteSize: bigint;
+    readonly observedContentType: string;
+}
+export interface StorageFinalizeResult {
+    readonly reservation: StorageReservation;
+    readonly usage: TenantStorageUsage;
+    /**
+     * True when this tenant already had the same content hash committed. The
+     * reserved bytes are released and nothing is added: same tenant, same hash,
+     * counted once (§12.7.6). Cross-tenant sharing never happens — usage is
+     * per-tenant even when the bytes are identical.
+     */
+    readonly deduplicated: boolean;
+}
+/** Effective write posture derived from entitlement + usage + clock (§12.7.8). */
+export declare const STORAGE_WRITE_POSTURES: readonly ['normal', 'warning', 'blocked', 'suspended'];
+export type StorageWritePosture = (typeof STORAGE_WRITE_POSTURES)[number];
+export interface StorageStatus {
+    readonly entitlement: TenantStorageEntitlement;
+    readonly usage: TenantStorageUsage;
+    readonly posture: StorageWritePosture;
+    /** `committed + reserved` against `hardLimitBytes`, for host UI. */
+    readonly availableBytes: bigint;
+    readonly graceActive: boolean;
+}
+/**
+ * The five wire-stable storage error codes (§12.7.7). Renaming one is a
+ * breaking change for every host that branches on them.
+ */
+export declare const STORAGE_ERROR_CODES: readonly ["storage_object_too_large", "storage_quota_exceeded", "storage_reservation_expired", "storage_integrity_mismatch", "storage_write_suspended"];
+export type StorageErrorCode = (typeof STORAGE_ERROR_CODES)[number];
+/** HTTP status mapping from §12.7.7. Compositions render these verbatim. */
+export declare const STORAGE_ERROR_HTTP_STATUS: {
+    readonly storage_object_too_large: 413;
+    readonly storage_quota_exceeded: 507;
+    readonly storage_reservation_expired: 409;
+    readonly storage_integrity_mismatch: 422;
+    readonly storage_write_suspended: 423;
+};
+export interface MailboxUsageDeltaInput {
+    /** Signed. Negative deltas release bytes after retention deletes rows. */
+    readonly deltaBytes: bigint;
+}
+/**
+ * Quota port. Tenant-first, async.
+ *
+ * Raises: `storage_entitlement_missing`,
+ * `storage_entitlement_version_conflict` (carries the current entitlement),
+ * `storage_reservation_not_found`, and the five wire-stable codes above.
+ */
+export interface QuotaStore {
+    readEntitlement(tenant: TenantId): Promise<TenantStorageEntitlement | undefined>;
+    /**
+     * Version CAS: a write at or below the stored version is rejected with the
+     * current row. Raises `timestamp_not_canonical` when `downgradeGraceUntil` is
+     * not a canonical ISO-8601 UTC instant.
+     */
+    writeEntitlement(tenant: TenantId, input: TenantStorageEntitlementInput): Promise<TenantStorageEntitlement>;
+    readUsage(tenant: TenantId): Promise<TenantStorageUsage>;
+    readStatus(tenant: TenantId): Promise<StorageStatus>;
+    /** Tenant-scoped lookup used to bind a finalize request to its reservation. */
+    readReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation | undefined>;
+    /**
+     * Atomically checks `committed + reserved + expected <= hardLimitBytes` and,
+     * on success, adds `expectedBytes` to `reservedBytes`.
+     */
+    reserve(tenant: TenantId, input: StorageReservationInput): Promise<StorageReservation>;
+    /**
+     * Moves reserved bytes to committed after verifying the observed object.
+     * For object reservations, the composition commits the matching manifest in
+     * the same authority step as reservation/accounting settlement.
+     */
+    finalizeReservation(tenant: TenantId, input: StorageFinalizeInput): Promise<StorageFinalizeResult>;
+    /** Idempotent release. Already-settled reservations return their settled row. */
+    abortReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation>;
+    /** Cleanup hook: expires reservations past their TTL and releases their bytes. */
+    expireReservations(tenant: TenantId): Promise<readonly StorageReservation[]>;
+    /** Mailbox bytes are platform-protection accounting, bounded by `mailboxLimitBytes`. */
+    applyMailboxDelta(tenant: TenantId, input: MailboxUsageDeltaInput): Promise<TenantStorageUsage>;
+}

package/dist/stores.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The composition contract: the full set of store ports, plus the clock seam.
+ *
+ * Every method on every port in this package obeys two rules, and
+ * `src/__tests__/constraints.test.ts` enumerates them method by method to prove
+ * it (sprint I7):
+ *
+ * 1. **Async.** Every method returns a `Promise`. A synchronous port would
+ *    silently exclude SQL and object-store compositions from the contract.
+ * 2. **Tenant-first.** Every method's first parameter is a required
+ *    {@link TenantId}. There is no bare `deviceId`/`taskId` lookup anywhere —
+ *    §12.6.2 layer 3 forbids the index such a lookup would need, and layer 5
+ *    requires the tenant to be part of the lookup key rather than a second
+ *    comparison step that can be forgotten.
+ *
+ * No port method can change the tenant of an existing row. That is not an
+ * omission: "move this to another tenant" is the one operation that would make
+ * every cross-tenant assertion in the conformance suite unfalsifiable.
+ */
+import type { ActivityStore, PresenceStore } from './presence';
+import type { BoardStore } from './board';
+import type { MailboxStore } from './mailbox';
+import type { ObjectStore } from './blob';
+import type { QuotaStore } from './quota';
+import type { TruthStore } from './truth';
+/**
+ * Injected time.
+ *
+ * TTL semantics (presence expiry, activity expiry, reservation expiry) are
+ * behavior the conformance suite has to assert deterministically, which is
+ * impossible against a wall clock. Compositions inject one; nothing in core
+ * calls `Date.now()` directly.
+ */
+export interface Clock {
+    now(): Date;
+}
+/** A clock pinned to a fixed instant, advanced explicitly. Used by tests and the in-memory reference. */
+export interface MutableClock extends Clock {
+    advance(ms: number): void;
+    set(instant: Date): void;
+}
+/** Every port a composition must supply. */
+export interface CoreStores {
+    readonly mailbox: MailboxStore;
+    readonly board: BoardStore;
+    readonly truth: TruthStore;
+    readonly presence: PresenceStore;
+    readonly activity: ActivityStore;
+    readonly objects: ObjectStore;
+    readonly quota: QuotaStore;
+}
+/** Names of the ports in {@link CoreStores}, in contract order. */
+export declare const CORE_STORE_NAMES: readonly ['mailbox', 'board', 'truth', 'presence', 'activity', 'objects', 'quota'];
+export type CoreStoreName = (typeof CORE_STORE_NAMES)[number];

package/dist/tenant.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A validated tenant identifier.
+ *
+ * Nominal by construction: structurally a `string`, but the phantom brand makes
+ * it unassignable from an arbitrary string. Assignment the other way
+ * (`TenantId` → `string`) stays legal on purpose, so composition code can pass
+ * it as a SQL parameter or key prefix without a cast.
+ */
+export type TenantId = string & {
+    readonly __byokTenantId: unique symbol;
+};
+/**
+ * Upper bound on tenant id length. Not a security boundary — a bound so a
+ * pathological id cannot become an unbounded key prefix inside a store.
+ */
+export declare const TENANT_ID_MAX_LENGTH = 200;
+/**
+ * Separator for flat composite keys. `NUL` cannot appear in a tenant id that a
+ * control plane can express in a URL, a header, or a SQL identifier, and
+ * {@link tenantId} rejects it outright — so a composite key is never ambiguous
+ * between `(a, bc)` and `(ab, c)`.
+ */
+export declare const TENANT_KEY_SEPARATOR = "\0";
+/**
+ * The single mint point for {@link TenantId}.
+ *
+ * Fail-closed: empty, whitespace-padded, over-long, non-string, or
+ * `NUL`-bearing values are rejected rather than normalized. Normalizing here
+ * would create a second source of truth for "which tenant is this", because the
+ * control plane that issued the id would then disagree with the SDK about its
+ * canonical form.
+ *
+ * @throws {ByokCoreError} code `tenant_id_invalid`.
+ */
+export declare function tenantId(value: string): TenantId;
+/**
+ * Non-throwing form of {@link tenantId}, for surfaces that must answer "is this
+ * a tenant id?" without building an error (route matching, log redaction).
+ * Accepts exactly what {@link tenantId} accepts, never more.
+ */
+export declare function isTenantId(value: unknown): value is TenantId;
+/**
+ * Composite key helper for compositions that need a flat key space (in-memory
+ * maps, KV namespaces). SQL compositions use a tenant-prefixed composite
+ * primary key instead — §12.6.2 layer 3 forbids a bare device/task index
+ * regardless of which representation a composition picks.
+ */
+export declare function tenantKey(tenant: TenantId, ...parts: readonly string[]): string;

package/dist/time.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Exactly what `toISOString()` produces: four-digit year, `T` separator,
+ * millisecond precision, literal `Z`. No offsets, no omitted milliseconds, no
+ * expanded-year form — each of those breaks the lexicographic-order property.
+ */
+export declare const CANONICAL_TIMESTAMP_PATTERN: RegExp;
+/**
+ * True when `value` is a canonical ISO-8601 UTC instant.
+ *
+ * Two checks, in order: the pattern pins the *shape*, then a round trip
+ * through `Date` pins *calendar validity* — `2026-02-30T00:00:00.000Z` matches
+ * the pattern and is not an instant.
+ */
+export declare function isCanonicalTimestamp(value: unknown): value is string;
+/**
+ * Fail-closed gate for a caller-supplied instant.
+ *
+ * @param value The timestamp as received from the caller.
+ * @param field Field name, so the failure names the contract that was missed
+ *   rather than just the bad string.
+ * @returns The same string, so call sites can validate and assign in one step.
+ * @throws {ByokCoreError} code `timestamp_not_canonical`.
+ */
+export declare function assertCanonicalTimestamp(value: string, field: string): string;

package/dist/truth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Truth records: attested metadata with two different write models (§12.3, §12.6.4).
+ *
+ * | kind            | write model                    | conflict model                          |
+ * | --------------- | ------------------------------ | --------------------------------------- |
+ * | `task.terminal` | first write per task, immutable | different hash → `terminal_conflict`    |
+ * | `profile`       | per-key snapshot                | `expectedRev` CAS                       |
+ * | `memory`        | per-key snapshot                | `expectedRev` CAS                       |
+ *
+ * The store is deliberately dumb about content. It can match, sort, and return
+ * by tenant/kind/key/rev/hash, and that is the whole of its authority: no
+ * summarizing, no merging, no relevance ranking (§12.3). Merge decisions belong
+ * to the device that holds the context, which is why a conflict hands back the
+ * current snapshot and stops.
+ *
+ * The manifest listing returns metadata only — never bodies. Selecting which
+ * bodies to fetch is a local decision (§S6.4), so shipping bodies in the list
+ * response would both defeat that and make the response unbounded.
+ */
+import type { ContentHash } from './blob';
+import type { TenantId } from './tenant';
+export declare const TRUTH_RECORD_KINDS: readonly ['task.terminal', 'profile', 'memory'];
+export type TruthRecordKind = (typeof TRUTH_RECORD_KINDS)[number];
+/**
+ * Where the record body lives. Small payloads may be inline and still count
+ * against tenant usage (§12.7.6); larger ones are an object reference.
+ */
+export type TruthBodyRef = {
+    readonly kind: 'inline';
+    readonly body: string;
+} | {
+    readonly kind: 'object';
+    readonly hash: ContentHash;
+};
+export interface TruthRecord {
+    readonly tenantId: TenantId;
+    readonly kind: TruthRecordKind;
+    /** For `task.terminal` this is the task id; for snapshots, the host's key. */
+    readonly recordKey: string;
+    /** `1` for the first write. Terminal records never advance past `1`. */
+    readonly rev: number;
+    readonly contentHash: ContentHash;
+    readonly byteSize: bigint;
+    readonly body: TruthBodyRef;
+    readonly label?: string;
+    /** Idempotency key of the accepted write, for replay detection. */
+    readonly requestId?: string;
+    readonly writtenAt: string;
+}
+/** Manifest projection: everything needed to decide *whether* to fetch a body. */
+export interface TruthManifestEntry {
+    readonly kind: TruthRecordKind;
+    readonly recordKey: string;
+    readonly rev: number;
+    readonly contentHash: ContentHash;
+    readonly byteSize: bigint;
+    readonly label?: string;
+    readonly updatedAt: string;
+}
+export interface TerminalWriteInput {
+    readonly taskId: string;
+    readonly contentHash: ContentHash;
+    readonly byteSize: bigint;
+    readonly body: TruthBodyRef;
+    readonly label?: string;
+    readonly requestId?: string;
+}
+export interface SnapshotWriteInput {
+    readonly kind: 'profile' | 'memory';
+    readonly recordKey: string;
+    /** `0` asserts "no record yet". Any other value must equal the stored `rev`. */
+    readonly expectedRev: number;
+    readonly contentHash: ContentHash;
+    readonly byteSize: bigint;
+    readonly body: TruthBodyRef;
+    readonly label?: string;
+    readonly requestId?: string;
+}
+export interface TruthRecordSelector {
+    readonly kind: TruthRecordKind;
+    readonly recordKey: string;
+}
+export interface TruthManifestQuery {
+    readonly kind?: TruthRecordKind;
+    readonly keyPrefix?: string;
+    readonly limit?: number;
+}
+/**
+ * Truth port. Tenant-first, async.
+ *
+ * Raises: `terminal_conflict` (same task, different hash — carries the record
+ * already committed), `truth_revision_conflict` (`expectedRev` missed — carries
+ * the current record), `truth_record_not_found`.
+ */
+export interface TruthStore {
+    /**
+     * Writes the first terminal record for a task.
+     *
+     * Replaying the identical hash returns the original record unchanged, so a
+     * retry after a lost response is safe. A different hash for the same task is
+     * a conflict: the first fact is never overwritten.
+     */
+    writeTerminal(tenant: TenantId, input: TerminalWriteInput): Promise<TruthRecord>;
+    /** Per-key snapshot write under `expectedRev` CAS. The store never merges bodies. */
+    writeSnapshot(tenant: TenantId, input: SnapshotWriteInput): Promise<TruthRecord>;
+    getRecord(tenant: TenantId, selector: TruthRecordSelector): Promise<TruthRecord | undefined>;
+    /** Metadata only — key/rev/hash/size/label, no bodies. */
+    listManifest(tenant: TenantId, query: TruthManifestQuery): Promise<readonly TruthManifestEntry[]>;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@byok-sdk/core",
+  "version": "0.1.0",
+  "description": "BYOK SDK platform contracts: branded tenant identity, tenant-first store ports, device proof canonicalization, and the composition conformance reference",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ancienttwo/byok-sdk.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/Ancienttwo/byok-sdk/issues"
+  },
+  "homepage": "https://github.com/Ancienttwo/byok-sdk#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}