@abloatai/transaction 0.37.0

package/src/headlessClient.ts

@@ -0,0 +1,161 @@
+import {
+  createAbloHttpClient,
+  type AbloHttpClient,
+  type AbloHttpClientOptions,
+} from './transport/httpClient.js';
+import { createHttpFeed } from './transport/httpFeed.js';
+import type { SchemaRecord } from './schema/schema.js';
+import { fieldRef } from './schema/fieldRef.js';
+import type { ClaimParams, ServerReadOptions } from './resources/modelOperations.js';
+import type { ModelData } from './types/modelData.js';
+import type { ClaimLeaseOptions, ClaimTarget, HeldClaim } from './types/streams.js';
+import type { CommitMessage } from './wire/frames.js';
+import type {
+  CommitReceipt,
+  ListQuery,
+  TransactionLayer,
+} from './transactionLayer.js';
+import { AbloConnectionError } from './errors.js';
+
+export interface TransactionClientOptions<S extends SchemaRecord>
+  extends AbloHttpClientOptions<S> {}
+
+export type TransactionClient<S extends SchemaRecord> =
+  TransactionLayer
+  & AbloHttpClient<S>
+  & { dispose(): Promise<void> };
+
+type DynamicModel = {
+  get(options: { id: string }): Promise<ModelData | undefined>;
+  list(options?: ServerReadOptions<ModelData>): Promise<ModelData[]>;
+  claim(options: ClaimParams<ModelData>): Promise<HeldClaim>;
+};
+
+const LAYER_MEMBERS = new Set<PropertyKey>([
+  'ready',
+  'get',
+  'list',
+  'commit',
+  'settled',
+  'claim',
+  'observe',
+  'dispose',
+]);
+
+function toCommitOptions(payload: CommitMessage['payload']) {
+  return {
+    idempotencyKey: payload.clientTxId,
+    operations: payload.operations.map((operation) => ({
+      action: operation.type.toLowerCase() as
+        | 'create'
+        | 'update'
+        | 'delete'
+        | 'archive'
+        | 'unarchive',
+      model: operation.model,
+      id: operation.id,
+      data: operation.input,
+      readAt: operation.readAt,
+      onStale: operation.onStale,
+      transactionId: operation.transactionId,
+      fenceToken: operation.fenceToken,
+    })),
+    reads: payload.reads,
+    track: payload.track,
+  } as const;
+}
+
+export function createTransactionClient<S extends SchemaRecord>(
+  options: TransactionClientOptions<S>,
+): TransactionClient<S> {
+  const http = createAbloHttpClient(options);
+  const pending = new Map<string, ReturnType<typeof toCommitOptions>>();
+  const observe = createHttpFeed(http.logs);
+  const hasDurableWrites =
+    options.durableWrites !== undefined || options.commitOutbox !== undefined;
+
+  function model(name: string): DynamicModel {
+    const resource = Reflect.get(http, name) as DynamicModel | undefined;
+    if (!resource) {
+      throw new AbloConnectionError(`Unknown schema model: ${name}.`, {
+        code: 'invalid_options',
+      });
+    }
+    return resource;
+  }
+
+  const layer: TransactionLayer & { dispose(): Promise<void> } = {
+    ready: () => http.ready(),
+    async get(modelName, id) {
+      return (await model(modelName).get({ id })) ?? null;
+    },
+    list(modelName, query?: ListQuery) {
+      return model(modelName).list({
+        ...(query?.where ? { where: query.where } : {}),
+        ...(query?.orderBy ? { orderBy: query.orderBy } : {}),
+        ...(query?.limit !== undefined ? { limit: query.limit } : {}),
+        ...(query?.offset !== undefined ? { offset: query.offset } : {}),
+        ...(query?.state !== undefined ? { state: query.state } : {}),
+      });
+    },
+    async commit(payload) {
+      const request = toCommitOptions(payload);
+      pending.set(payload.clientTxId, request);
+      const receipt = await http.commits.create({ ...request, wait: 'queued' });
+      return { ...receipt, clientTxId: payload.clientTxId };
+    },
+    async settled(receipt) {
+      if (receipt.status === 'confirmed') return;
+      const request = pending.get(receipt.clientTxId);
+      if (!request) {
+        if (hasDurableWrites) {
+          await http.waitForFlush();
+          return;
+        }
+        throw new AbloConnectionError(
+          'The original commit request is not available. Configure durableWrites to settle queued receipts after a process restart.',
+          { code: 'commit_no_result' },
+        );
+      }
+      const result = await http.commits.create({ ...request, wait: 'confirmed' });
+      if (result.status !== 'confirmed') {
+        throw new AbloConnectionError('The commit remains queued.', {
+          code: 'replication_lag_timeout',
+        });
+      }
+      pending.delete(receipt.clientTxId);
+    },
+    claim(target: ClaimTarget, claimOptions?: ClaimLeaseOptions) {
+      return model(target.type).claim({
+        id: target.id,
+        ...(target.field
+          ? { fields: () => fieldRef(target.type, target.field!) }
+          : target.fields
+            ? {
+                fields: () =>
+                  target.fields!.map((field) => fieldRef(target.type, field)) as [
+                    ReturnType<typeof fieldRef>,
+                    ...ReturnType<typeof fieldRef>[],
+                  ],
+              }
+            : {}),
+        ...(target.meta ? { meta: target.meta } : {}),
+        ...claimOptions,
+      });
+    },
+    observe,
+    dispose: () => http.dispose(),
+  };
+
+  return new Proxy(layer as TransactionClient<S>, {
+    get(target, property, receiver) {
+      if (LAYER_MEMBERS.has(property)) {
+        return Reflect.get(target, property, receiver);
+      }
+      return Reflect.get(http, property);
+    },
+    has(target, property) {
+      return Reflect.has(target, property) || Reflect.has(http, property);
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * The Ablo settlement core (ADR 0013).
+ *
+ * The transaction layer that the reactive client is a consumer of, not the
+ * other way round. The root barrel is deliberate: it exports the seam —
+ * {@link TransactionLayer} — plus exactly the vocabulary its signatures
+ * reference and the error hierarchy callers catch. Everything else stays on
+ * subpaths; every addition here is a decision
+ * (docs/plans/transaction-layer-barrel-design.md).
+ */
+
+// The seam.
+export type {
+  TransactionLayer,
+  ListQuery,
+  CommitReceipt,
+  ObserveOptions,
+  ObserveCursorStore,
+  ObservedDelta,
+} from './transactionLayer.js';
+export { createTransactionClient } from './headlessClient.js';
+export type {
+  TransactionClient,
+  TransactionClientOptions,
+} from './headlessClient.js';
+
+// The client entry point (ADR 0016). The bare import constructs the
+// coordination layer over request/response transport; the reactive
+// materialiser is the consumer package's entry point, layered above it.
+export { Ablo } from './ablo.js';
+export type {
+  AbloHttpClient,
+  AbloHttpClientOptions,
+  HttpModelClient,
+} from './transport/httpClient.js';
+
+// The types the seam's signatures reference.
+export type {
+  Delta,
+  HeldClaim,
+  HeldLease,
+  ClaimTarget,
+  ClaimLeaseOptions,
+} from './types/streams.js';
+export type { ModelData } from './types/modelData.js';
+
+// The error hierarchy and its wire/recovery helpers.
+export * from './errors.js';
+
+// Pre-seam leaf surfaces, kept for compatibility with the first extraction.
+export * from './errorCodes.js';
+export * from './environment.js';

package/src/keys/index.ts

@@ -0,0 +1,254 @@
+/**
+ * The Ablo API-key format: how keys are minted, hashed, and validated, in one
+ * place so every component that issues or checks a key agrees on the format.
+ *
+ * This module uses `node:crypto` and is therefore Node-only. It is published on
+ * the `@abloatai/transaction/keys` subpath and kept off the main browser-facing entry
+ * so a browser bundle never pulls in `node:crypto`.
+ *
+ * A key looks like `<sk|rk|ek|pk>_<live|test>_<30 base62 chars><6-char base62
+ * CRC32 checksum>`. The middle segment is the stable environment prefix, mapped
+ * on parse to `production` or `sandbox`. The recognizable prefix lets secret
+ * scanners spot a leaked key, and the trailing checksum lets the format reject a
+ * mistyped or forged key locally, without a database round-trip. Older keys
+ * (roughly a 43-character base64url body with no checksum) still validate by hash
+ * and parse here with `checksummed: false`.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import {
+  KEY_ENVIRONMENTS,
+  KEY_PREFIX_ENVIRONMENTS,
+  environmentFromKeyPrefix,
+  environmentToKeyPrefix,
+  type KeyEnvironment,
+  type KeyPrefixEnvironment,
+} from '../environment.js';
+
+// ── Vocabulary ──────────────────────────────────────────────────────────
+
+// The four key kinds:
+//   secret (sk_)      — backend and server-to-server use, including agents. Full
+//                       authority; never expose one in a browser.
+//   restricted (rk_)  — a scoped server key, such as an agent session token or a
+//                       narrowed capability.
+//   ephemeral (ek_)   — a short-lived, backend-minted session credential scoped to
+//                       one user, safe to hand to that user's browser. Carries
+//                       `participantKind: 'user'` and its baked-in sync groups.
+//   publishable (pk_) — a long-lived, browser-safe, organization-scoped read-only
+//                       key. It is used directly as the bearer token — never
+//                       exchanged, never expires, nothing to refresh. It grants
+//                       read access to the organization's data and cannot write or
+//                       reach any control-plane operation.
+export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral', 'publishable'] as const;
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+
+// A key's environment is the CREDENTIAL axis, not the plane axis: the format
+// below spells it as one of two prefixes, so a plane name outside those two has
+// no representation here and must not reach `generateApiKey`.
+export const API_KEY_ENVS = KEY_ENVIRONMENTS;
+export type ApiKeyEnv = KeyEnvironment;
+
+const PREFIX_BY_KIND: Record<ApiKeyKind, string> = {
+  secret: 'sk',
+  restricted: 'rk',
+  ephemeral: 'ek',
+  publishable: 'pk',
+};
+const KIND_BY_PREFIX: Record<string, ApiKeyKind> = {
+  sk: 'secret',
+  rk: 'restricted',
+  ek: 'ephemeral',
+  pk: 'publishable',
+};
+
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** Random base62 chars before the checksum. */
+const KEY_BODY_LEN = 30;
+/** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
+const CHECKSUM_LEN = 6;
+/** A new checksummed body is exactly this long and pure base62. */
+const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
+
+/** `<sk|rk|ek|pk>_<live|test>_<body>`; the body charset covers base62 as well as the legacy base64url form. */
+const KEY_RE = /^(sk|rk|ek|pk)_(live|test)_([0-9A-Za-z\-_]+)$/;
+const BASE62_RE = /^[0-9A-Za-z]+$/;
+
+// ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
+
+const CRC32_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+function crc32(s: string): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < s.length; i++) {
+    // `& 0xff` bounds the index to the 256-entry table — the ?? 0 is unreachable.
+    c = ((CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ?? 0) ^ (c >>> 8)) >>> 0;
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** 6-char base62 encoding of the CRC32 of `payload`. */
+function checksum6(payload: string): string {
+  let n = crc32(payload);
+  let out = '';
+  for (let i = 0; i < CHECKSUM_LEN; i++) {
+    out = BASE62.charAt(n % 62) + out;
+    n = Math.floor(n / 62);
+  }
+  return out;
+}
+
+/** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
+function randomBase62(len: number): string {
+  let out = '';
+  while (out.length < len) {
+    for (const b of randomBytes(len * 2)) {
+      if (b < 248) {
+        out += BASE62.charAt(b % 62);
+        if (out.length === len) break;
+      }
+    }
+  }
+  return out;
+}
+
+// ── Zod schema (the executable spec) ────────────────────────────────────
+
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+  /** The original plaintext. */
+  raw: string;
+  kind: ApiKeyKind;
+  env: ApiKeyEnv;
+  /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+  body: string;
+  /** True when this is the new checksummed format (36-char base62 body). */
+  checksummed: boolean;
+}
+
+function bodyIsChecksummed(body: string): boolean {
+  return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
+}
+
+/**
+ * The Zod schema for an Ablo API key. `parse` and `safeParse` return a typed
+ * {@link ParsedApiKey}. A checksummed-format key whose checksum does not match is
+ * rejected without any network call; an older key with no checksum parses with
+ * `checksummed: false` and is left for the server to validate by hash.
+ */
+export const apiKeySchema = z.string().transform((raw, ctx): ParsedApiKey => {
+  const m = KEY_RE.exec(raw);
+  if (!m) {
+    ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+    return z.NEVER;
+  }
+  const [, prefix, env, body] = m;
+  const kind = prefix === undefined ? undefined : KIND_BY_PREFIX[prefix];
+  // Unreachable on a KEY_RE match (all three groups are non-optional and the
+  // prefix alternation is exactly the KIND_BY_PREFIX key set) — narrows the
+  // regex-group lookups for the checks below.
+  if (kind === undefined || env === undefined || body === undefined) {
+    ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+    return z.NEVER;
+  }
+  const checksummed = bodyIsChecksummed(body);
+  if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
+    ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
+    return z.NEVER;
+  }
+  return {
+    raw,
+    kind,
+    env: environmentFromKeyPrefix(env as KeyPrefixEnvironment),
+    body,
+    checksummed,
+  };
+});
+
+// ── Derived validators (thin wrappers over the same spec) ───────────────
+
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export function parseApiKey(raw: string): ParsedApiKey | null {
+  const r = apiKeySchema.safeParse(raw);
+  return r.success ? r.data : null;
+}
+
+/**
+ * Read the environment off a STORED display prefix (`keyPrefix`, the first 12
+ * chars — `rk_test_abcd`), rather than off a full plaintext key.
+ *
+ * A key row records its environment nowhere but its prefix, so this is how a
+ * server-side flow that only has the row — rotation, most importantly — recovers
+ * the credential's own mode. Returns null when the prefix is not a recognizable
+ * key spelling, so callers can fail closed rather than fall back to a default.
+ */
+export function environmentFromStoredKeyPrefix(prefix: string): KeyEnvironment | null {
+  const spelling = /^(?:sk|rk|ek|pk)_([a-z]+)_/.exec(prefix)?.[1];
+  const env = KEY_PREFIX_ENVIRONMENTS.find((candidate) => candidate === spelling);
+  return env === undefined ? null : environmentFromKeyPrefix(env);
+}
+
+/** True when the key uses the new checksummed format (regardless of validity). */
+export function isChecksummedKey(raw: string): boolean {
+  const body = KEY_RE.exec(raw)?.[3];
+  return body !== undefined && bodyIsChecksummed(body);
+}
+
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export function keyChecksumMatches(raw: string): boolean {
+  const body = KEY_RE.exec(raw)?.[3];
+  if (body === undefined || !bodyIsChecksummed(body)) return false;
+  return checksum6(raw.slice(0, -CHECKSUM_LEN)) === body.slice(KEY_BODY_LEN);
+}
+
+// ── Mint + hash (node:crypto) ───────────────────────────────────────────
+
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export function generateApiKey(
+  env: ApiKeyEnv = 'production',
+  kind: ApiKeyKind = 'secret',
+): { plaintext: string; hash: string; prefix: string } {
+  const body = randomBase62(KEY_BODY_LEN);
+  const payload = `${PREFIX_BY_KIND[kind]}_${environmentToKeyPrefix(env)}_${body}`;
+  const plaintext = `${payload}${checksum6(payload)}`;
+  return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
+}
+
+/**
+ * The stable SHA-256 hex digest of a plaintext key, computed both when a key is
+ * minted and when one is looked up. A fast hash is the right choice here rather
+ * than a password hash like bcrypt: API keys are long random strings, so there is
+ * no dictionary of guesses to slow down.
+ */
+export function hashApiKey(plaintext: string): string {
+  return createHash('sha256').update(plaintext).digest('hex');
+}
+
+/** `whsec_` label prefix per the Standard Webhooks spec (not part of the key material). */
+export const WEBHOOK_SECRET_PREFIX = 'whsec_';
+
+/**
+ * Mints a webhook signing secret following the Standard Webhooks specification
+ * (https://www.standardwebhooks.com): a base64-encoded random key of 24–64 bytes,
+ * labelled with the `whsec_` prefix. This uses 32 bytes (256 bits), comfortably
+ * inside that range. Unlike an API key, a signing secret is not hashed at rest,
+ * because signing a request with {@link signAbloSourceRequest} needs the live
+ * value. It is therefore kept in a secret store, returned to the customer once at
+ * creation, and never shown again.
+ */
+export function generateWebhookSecret(): { plaintext: string; last4: string } {
+  const plaintext = `${WEBHOOK_SECRET_PREFIX}${randomBytes(32).toString('base64')}`;
+  return { plaintext, last4: plaintext.slice(-4) };
+}

package/src/log/syncDeltaRow.ts

@@ -0,0 +1,119 @@
+/**
+ * Zod schemas that describe the `sync_deltas` storage row — the durable record of
+ * one committed change. The row is split into two slices by the concern each one
+ * serves:
+ *
+ *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
+ *     needs to reconstruct the change, plus the tenant key. This is a portable
+ *     payload shape; it is not a statement that the row is physically stored in
+ *     the customer's database.
+ *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
+ *
+ * {@link syncDeltaRowSchema} composes both into the full stored row.
+ * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
+ * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
+ * Keeping those axes separate prevents a portable schema slice from being cited
+ * incorrectly as a physical-residency guarantee.
+ *
+ * This is the stored shape. The delta broadcast to clients is a narrower projection
+ * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
+ * the field names here mirror those on that wire delta.
+ */
+
+import { z } from 'zod';
+import type { ModelResidency } from '../schema/residency.js';
+import {
+  participantKindSchema,
+  confirmationStateSchema,
+  syncDeltaActionSchema,
+} from '../wire/delta.js';
+
+// ── Enumerations that mirror the corresponding Postgres enum types ────────────
+
+// `participant_kind` and `confirmation_state` are shared with the wire delta and
+// live at the wire layer (see `../wire/delta.js`); they are re-exported here so
+// code that imports them from `schema` keeps resolving.
+export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
+export type { ParticipantKind, ConfirmationState } from '../wire/delta.js';
+
+/** `backfill_provenance` */
+export const backfillProvenanceSchema = z.enum(['exact', 'inferred', 'unknown']);
+export type BackfillProvenance = z.infer<typeof backfillProvenanceSchema>;
+
+/** A delta payload: the full post-mutation row (or null for deletes). */
+const deltaDataSchema = z.record(z.string(), z.unknown()).nullable();
+
+// ── Core — the sync-protocol slice ────────────────────────────────────────────
+
+/**
+ * Everything a client needs to materialize the change, plus the tenant key. This
+ * is the portable shape an authoritative WAL change or endpoint event carries.
+ * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
+ * sync log; it is not written atomically with a direct application-row mutation.
+ * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
+ * appended, so they are optional at the ingestion boundary.
+ */
+export const syncDeltaCoreSchema = z.object({
+  /** Monotonically increasing sync id, assigned by the server when the delta is appended; absent on an outbox marker. */
+  id: z.union([z.bigint(), z.number()]).optional(),
+  /** The `action_type` column; its eight values are owned by the wire delta contract. */
+  actionType: syncDeltaActionSchema,
+  modelName: z.string().min(1),
+  modelId: z.string().min(1),
+  data: deltaDataSchema,
+  previousData: deltaDataSchema.optional(),
+  /** Routing keys that decide which subscribers receive this delta; computed by the server at append time. */
+  syncGroups: z.array(z.string()).optional(),
+  /** The committing organization id — the coarse-grained tenant-isolation boundary. */
+  organizationId: z.string().nullable(),
+  /** ISO 8601 timestamp, assigned by the server when the delta is appended. */
+  createdAt: z.string().optional(),
+  transactionId: z.string().nullable(),
+  /**
+   * Stable identity of the authoritative WAL row or endpoint event. It is
+   * nullable for hosted/legacy rows and is never exposed as the optimistic
+   * client transaction id.
+   */
+  sourceChangeId: z.string().min(1).nullable().optional(),
+});
+export type SyncDeltaCore = z.infer<typeof syncDeltaCoreSchema>;
+
+// ── Attribution — who made the change, and on whose authority ─────────────────
+
+export const deltaAttributionSchema = z.object({
+  /** The acting participant, recorded as a single column for compatibility; the structured pair below is the richer form. */
+  createdBy: z.string().nullable(),
+  actorId: z.string().nullable(),
+  actorKind: participantKindSchema.nullable(),
+  onBehalfOfId: z.string().nullable(),
+  onBehalfOfKind: participantKindSchema.nullable(),
+  capabilityId: z.string().nullable(),
+  delegationChainRootUserId: z.string().nullable().optional(),
+  confirmationState: confirmationStateSchema.nullable(),
+  backfillProvenance: backfillProvenanceSchema.nullable(),
+});
+export type DeltaAttribution = z.infer<typeof deltaAttributionSchema>;
+
+// ── Full stored row, classification, and physical storage ─────────────────────
+
+/** The complete `sync_deltas` row: core and attribution combined. */
+export const syncDeltaRowSchema = syncDeltaCoreSchema.extend(deltaAttributionSchema.shape);
+export type SyncDeltaRow = z.infer<typeof syncDeltaRowSchema>;
+
+/** Which slices contain retained customer row data versus control metadata. */
+export const DELTA_DATA_CLASSIFICATION = {
+  core: 'customer-data',
+  attribution: 'control-metadata',
+} as const;
+
+/**
+ * Where the current runtime physically persists each slice. Both live in
+ * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
+ * payloads (and optional previous payloads), so `control` here must not be read
+ * as "metadata only."
+ */
+export const DELTA_PHYSICAL_STORAGE = {
+  core: 'control',
+  attribution: 'control',
+} as const satisfies Record<string, ModelResidency>;
+

package/src/logger.ts

@@ -0,0 +1,22 @@
+/**
+ * The logging port the SDK writes through.
+ *
+ * A contract with no framework and no local state: credential exchange, commit,
+ * and claim all need to log with no UI and no offline store present, so the port
+ * belongs to the settlement core (ADR 0016). The consumer supplies the
+ * implementation; the SDK ships a no-op default.
+ */
+export interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+
+/** The no-op default — what the core logs through when no logger is wired. */
+export const noopLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};