@optimystic/db-core 0.14.1 → 0.16.3

package/dist/src/transaction/transaction.d.ts

@@ -17,6 +17,16 @@ export type TransactionStamp = {
     engineId: string;
     /** Absolute ms epoch after which transaction is invalid */
     expiration: number;
+    /**
+     * Random per-transaction nonce, folded into {@link TransactionStamp.id}.
+     *
+     * Anti-replay for read-free transactions: a transaction with no reads has nothing
+     * binding it to a point in history beyond {@link expiration}, so without this a
+     * captured signed read-free transaction could be re-submitted within the TTL window.
+     * The nonce makes two otherwise-identical transactions from the same peer at the
+     * same millisecond produce different ids (hence different signed bytes).
+     */
+    nonce: string;
     /** Hash of the stamp fields (computed) - stable identifier throughout transaction */
     id: string;
 };
@@ -41,6 +51,42 @@ export type Transaction = {
      * Final transaction identity, used in logs
      */
     id: string;
+    /**
+     * Optional client signature (base64url) over {@link clientSignaturePayload}
+     * `(stamp.id, statements, reads)`, produced at commit by an injected
+     * {@link TransactionSigner}.
+     *
+     * A node that wires a {@link ClientSignatureVerifier} into its
+     * {@link TransactionValidator} verifies this at pend; where no verifier is wired,
+     * unsigned transactions are still accepted (migration / single-node-dev posture).
+     * Plain field on the transaction, so it rides along through serialization/persistence
+     * for later recovery-time re-verification.
+     *
+     * NOTE: preservation is verified only through JSON round-trip and an in-memory session commit —
+     * NOT yet through the db-p2p cluster-repo on-disk transaction-log serialization. No recovery
+     * reader exists today; when one lands, confirm this field survives that path so `verifyPeerSig`
+     * can re-run at recovery time.
+     */
+    signature?: string;
+    /**
+     * Aged, advisory retry priority (default 0 when absent). Rises by one per failed retry
+     * attempt (attempt-count-derived — deterministic, no wall clock, clock-skew-free) and is
+     * capped at {@link MaxPriority}. A cluster member uses it ONLY as the first tiebreak in a
+     * concurrent race between two simultaneously-pending conflicting transactions
+     * (`resolveRace`), so a transaction that keeps losing races eventually out-ranks fresh
+     * (priority-0) rivals instead of losing at random forever.
+     *
+     * FAIRNESS-ONLY — MUST NOT influence validity, the operations hash, stale-read checks, the
+     * transaction id, or the client signature. It is deliberately excluded from
+     * {@link createTransactionId} and {@link clientSignaturePayload} so two attempts of the same
+     * logical transaction (differing only in priority) keep the same id and signature; folding it
+     * into either would churn identity/anti-replay on every retry. It rides inside the signed
+     * cluster `message` (via the pend operation), so it is integrity-protected in transit — a
+     * relaying peer cannot strip or inflate it without invalidating the message hash — but the
+     * originating coordinator can still self-assert it (a fairness concern, not a safety one; see
+     * `docs/correctness.md` Theorem 9).
+     */
+    priority?: number;
 };
 /**
  * Read dependency for optimistic concurrency control.
@@ -58,8 +104,34 @@ export type ReadDependency = {
 export type TransactionRef = string;
 /** Default transaction time-to-live in milliseconds (30 seconds). */
 export declare const DEFAULT_TRANSACTION_TTL_MS = 30000;
+/**
+ * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
+ * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
+ * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
+ * commits). Two transactions capped out at `MaxPriority` fall back to the existing promise-count /
+ * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
+ */
+export declare const MaxPriority = 8;
+/**
+ * Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
+ * input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
+ * to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
+ * cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
+ * cannot exceed the cap.
+ */
+export declare function clampPriority(priority: number | undefined): number;
 /** Check whether a transaction stamp has expired. */
 export declare function isTransactionExpired(stamp: TransactionStamp): boolean;
+/** The stamp fields that feed the id hash (everything except the id itself). */
+export type StampFields = Omit<TransactionStamp, 'id'>;
+/**
+ * Compute the canonical stamp id from its fields. MUST match the historical field order
+ * (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
+ * existing stamp id and client signature. Both {@link createTransactionStamp} and the
+ * validator's integrity check derive the id through this one function, so a validating node
+ * can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
+ */
+export declare function computeStampId(fields: StampFields): Promise<string>;
 /**
  * Create a transaction stamp with computed id.
  * The id is a hash of the stamp fields (including expiration).
@@ -68,8 +140,51 @@ export declare function createTransactionStamp(peerId: string, timestamp: number
 /**
  * Create a transaction id from stamp id, statements, and reads.
  * This is the final transaction identity used in logs.
+ *
+ * NOTE: reads are serialized in their given order here (non-canonical). This differs
+ * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
+ * intentional for this ticket — the signature payload is self-contained — but the
+ * non-canonical ordering here is a separate hygiene concern (see
+ * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
+ * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
+ * priority produce the SAME id. Do not add priority here.
  */
 export declare function createTransactionId(stampId: string, statements: string[], reads: ReadDependency[]): Promise<string>;
+/**
+ * Version prefix for the client-signature payload, so the signed form can evolve
+ * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
+ * canonical form — this covers transaction INPUTS, not operations.
+ */
+export declare const CLIENT_SIG_VERSION = "txsig:v1";
+/**
+ * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
+ * (blockId, then revision); statements keep their sequential order.
+ *
+ * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
+ * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
+ * binding" for anti-replay). Both signer and verifier derive the bytes from
+ * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
+ * one function, so they reproduce identical bytes regardless of read ordering.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
+ * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
+ * add priority here.
+ */
+export declare function clientSignaturePayload(stampId: string, statements: readonly string[], reads: readonly ReadDependency[]): Uint8Array;
+/**
+ * Signs the canonical client-signature payload, returning base64url. Async to allow
+ * libp2p `PrivateKey.sign`; tests pass a synchronous fake.
+ */
+export type TransactionSigner = (payload: Uint8Array) => Promise<string> | string;
+/**
+ * Returns true iff `signature` (base64url) is a valid client signature over `payload`
+ * for signer identity `peerId`. Total: returns false, never throws, on any malformed
+ * input. The p2p wiring backs this with verifyPeerSig + peerIdBindsPublicKey; tests
+ * pass a fake.
+ */
+export type ClientSignatureVerifier = (peerId: string, payload: Uint8Array, signature: string) => boolean;
 /**
  * Transaction engine interface.
  * Pluggable engines implement this to process transaction statements.
@@ -78,8 +193,40 @@ export declare function createTransactionId(stampId: string, statements: string[
  * 1. Parsing the engine-specific statements
  * 2. Executing/re-executing to produce actions
  * 3. Returning the resulting actions per collection
+ *
+ * CONTRACT — an engine must never cause the same action to be applied twice. The
+ * caller (a {@link TransactionSession} on the no-pre-supplied-actions branch, or a
+ * {@link TransactionCoordinator} in `execute()`) applies whatever non-empty
+ * `CollectionActions[]` this method RETURNS. Therefore `execute()` must satisfy
+ * exactly ONE of:
+ *
+ *   (a) PURE TRANSLATOR (preferred; how {@link ActionsEngine} works) — parse the
+ *       statements, RETURN the actions, and do NOT apply them / do NOT call
+ *       `coordinator.applyActions` / do NOT mutate any collection state. The caller
+ *       applies them exactly once.
+ *
+ *   (b) SIDE-EFFECT APPLY — apply the actions itself while translating (e.g. the
+ *       Quereus vtab path stages rows into the coordinator during `db.exec`) and then
+ *       RETURN an EMPTY actions array, so the caller re-applies nothing.
+ *
+ * An engine that BOTH applies as a side effect AND returns those same actions
+ * double-applies (the caller re-applies the returned actions). Additionally, a
+ * side-effecting engine used for validation must apply only to the validator's
+ * ISOLATED coordinator — applying to the main coordinator leaks into the validating
+ * node's live state.
  */
 export interface ITransactionEngine {
+    /**
+     * Stable identifier for this engine.
+     *
+     * This is the value stamped into {@link TransactionStamp.engineId} when a
+     * {@link TransactionSession} builds a transaction, and the key a
+     * {@link TransactionValidator} resolves the engine by. It MUST match the key the
+     * engine is registered under in the validator's `engines` map — otherwise a
+     * validating node rejects the transaction as `Unknown engine: <id>` before it
+     * ever re-executes.
+     */
+    readonly id: string;
     /**
      * Process a transaction statements to produce actions.
      *
@@ -104,6 +251,16 @@ export type ExecutionResult = {
     results?: Map<CollectionId, any[]>;
     /** Error message if execution failed */
     error?: string;
+    /**
+     * On a PARTIAL multi-collection commit failure, the collections that DID durably
+     * commit through consensus before the failure (and thus CANNOT be rolled back —
+     * reconciliation is required). Absent/empty means nothing durably committed, so
+     * the caller may treat the failure as a clean abort. See
+     * {@link CoordinatorPartialCommitError} for the session-mode (commit) analog.
+     */
+    committedCollections?: CollectionId[];
+    /** On a partial multi-collection commit failure, the collections that failed to commit. */
+    failedCollections?: CollectionId[];
 };
 /**
  * Actions for a specific collection resulting from transaction execution.
@@ -148,7 +305,11 @@ export interface ITransactionValidator {
     /**
      * Validate a transaction by re-executing and comparing operations hash.
      *
-     * Validation steps:
+     * Validation steps (see TransactionValidator.validate for the authoritative order):
+     * 0.0. Verify stamp.id is the true hash of the stamp fields (integrity — runs first,
+     *      since every later step trusts a stamp field)
+     * 0. Verify the stamp has not expired
+     * 0.5. Verify the client signature (only if a signature verifier is wired)
      * 1. Verify stamp.engineId matches a known engine
      * 2. Verify stamp.schemaHash matches local schema
      * 3. Verify read dependencies (no stale reads)

package/dist/src/transaction/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"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"}

package/dist/src/transaction/transaction.js

@@ -1,28 +1,110 @@
+import { randomBytes } from "@noble/hashes/utils.js";
+import { toString as uint8ArrayToString } from "uint8arrays/to-string";
 import { hashString } from "../utility/hash-string.js";
 /** Default transaction time-to-live in milliseconds (30 seconds). */
 export const DEFAULT_TRANSACTION_TTL_MS = 30_000;
+/**
+ * Upper bound on a transaction's aged {@link Transaction.priority}. Capping is essential: it
+ * bounds the fairness effect (an aged transaction cannot accrue unlimited advantage) and bounds
+ * the throughput cost (it can impose at most `MaxPriority` extra race-losses on rivals before it
+ * commits). Two transactions capped out at `MaxPriority` fall back to the existing promise-count /
+ * message-hash tiebreak, so behavior degrades gracefully to the pre-priority status quo.
+ */
+export const MaxPriority = 8;
+/**
+ * Clamp an attempt-derived priority into `[0, MaxPriority]`. Total: any non-finite / negative
+ * input collapses to 0, anything above the cap to {@link MaxPriority}, and the result is floored
+ * to an integer. Used both where priority is *set* (the retry loops) and where it is *read* (a
+ * cluster member's `resolveRace`), so a Byzantine coordinator self-asserting an out-of-range value
+ * cannot exceed the cap.
+ */
+export function clampPriority(priority) {
+    if (typeof priority !== 'number' || Number.isNaN(priority) || priority <= 0) {
+        return 0;
+    }
+    // A positive out-of-range value (including +Infinity, or a Byzantine self-asserted number) clamps
+    // DOWN to the cap; anything strictly inside the range is floored to an integer.
+    if (priority >= MaxPriority) {
+        return MaxPriority;
+    }
+    return Math.floor(priority);
+}
 /** Check whether a transaction stamp has expired. */
 export function isTransactionExpired(stamp) {
     return Date.now() > stamp.expiration;
 }
+/**
+ * Compute the canonical stamp id from its fields. MUST match the historical field order
+ * (peerId, timestamp, schemaHash, engineId, expiration, nonce) — changing it churns every
+ * existing stamp id and client signature. Both {@link createTransactionStamp} and the
+ * validator's integrity check derive the id through this one function, so a validating node
+ * can re-derive the id and reject a stamp whose fields were tampered while id stayed fixed.
+ */
+export async function computeStampId(fields) {
+    // Destructure and rebuild in fixed order rather than passing `fields` straight to
+    // JSON.stringify — this ignores any stray `id` (or extra) property a caller slipped in,
+    // so the serialized bytes depend on exactly the six fields and nothing else.
+    const { peerId, timestamp, schemaHash, engineId, expiration, nonce } = fields;
+    const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
+    return `stamp:${await hashString(stampData)}`;
+}
 /**
  * Create a transaction stamp with computed id.
  * The id is a hash of the stamp fields (including expiration).
  */
 export async function createTransactionStamp(peerId, timestamp, schemaHash, engineId, ttlMs = DEFAULT_TRANSACTION_TTL_MS) {
     const expiration = timestamp + ttlMs;
-    const stampData = JSON.stringify({ peerId, timestamp, schemaHash, engineId, expiration });
-    const id = `stamp:${await hashString(stampData)}`;
-    return { peerId, timestamp, schemaHash, engineId, expiration, id };
+    // Cross-platform CSPRNG (Node + browser) via @noble/hashes — matches the rest of
+    // db-core (see collection.ts, transactor-source.ts). The nonce is folded into the
+    // id hash so two otherwise-identical stamps diverge.
+    const nonce = uint8ArrayToString(randomBytes(16), 'base64url');
+    const id = await computeStampId({ peerId, timestamp, schemaHash, engineId, expiration, nonce });
+    return { peerId, timestamp, schemaHash, engineId, expiration, nonce, id };
 }
 /**
  * Create a transaction id from stamp id, statements, and reads.
  * This is the final transaction identity used in logs.
+ *
+ * NOTE: reads are serialized in their given order here (non-canonical). This differs
+ * from {@link clientSignaturePayload}, which canonicalises reads before hashing. That is
+ * intentional for this ticket — the signature payload is self-contained — but the
+ * non-canonical ordering here is a separate hygiene concern (see
+ * design-consensus-hygiene-notes), NOT fixed here to avoid changing existing tx ids.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from this preimage — the id is a pure
+ * function of `(stampId, statements, reads)`, so two retry attempts that differ only in aged
+ * priority produce the SAME id. Do not add priority here.
  */
 export async function createTransactionId(stampId, statements, reads) {
     const txData = JSON.stringify({ stampId, statements, reads });
     return `tx:${await hashString(txData)}`;
 }
+/**
+ * Version prefix for the client-signature payload, so the signed form can evolve
+ * without ambiguity. Distinct from (but consistent in spirit with) the operations-hash
+ * canonical form — this covers transaction INPUTS, not operations.
+ */
+export const CLIENT_SIG_VERSION = 'txsig:v1';
+/**
+ * Canonical bytes a client signs and a node verifies. Deterministic: reads are sorted
+ * (blockId, then revision); statements keep their sequential order.
+ *
+ * Binds three things at once: the CLIENT IDENTITY (via `stampId`, which hashes peerId +
+ * nonce), the EXACT statements, and the OCC read set (blockId + revision — "tail
+ * binding" for anti-replay). Both signer and verifier derive the bytes from
+ * `transaction.stamp.id` + `transaction.statements` + `transaction.reads` through this
+ * one function, so they reproduce identical bytes regardless of read ordering.
+ *
+ * NOTE: {@link Transaction.priority} is deliberately absent from the signed bytes — a retry that
+ * only bumps priority keeps the same signature, so anti-replay / OCC binding never churns. Do not
+ * add priority here.
+ */
+export function clientSignaturePayload(stampId, statements, reads) {
+    const canonicalReads = [...reads].sort((a, b) => a.blockId < b.blockId ? -1 : a.blockId > b.blockId ? 1
+        : a.revision - b.revision);
+    const body = JSON.stringify({ stampId, statements, reads: canonicalReads });
+    return new TextEncoder().encode(`${CLIENT_SIG_VERSION}:${body}`);
+}
 /**
  * Helper to create an actions-based transaction statements array.
  * Each CollectionActions becomes a separate JSON-encoded statement.

package/dist/src/transaction/transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAsEvD,qEAAqE;AACrE,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AAEjD,qDAAqD;AACrD,MAAM,UAAU,oBAAoB,CAAC,KAAuB;IAC3D,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC3C,MAAc,EACd,SAAiB,EACjB,UAAkB,EAClB,QAAgB,EAChB,QAAgB,0BAA0B;IAE1C,MAAM,UAAU,GAAG,SAAS,GAAG,KAAK,CAAC;IACrC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1F,MAAM,EAAE,GAAG,SAAS,MAAM,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;IAClD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAe,EACf,UAAoB,EACpB,KAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,OAAO,MAAM,MAAM,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;AACzC,CAAC;AAmDD;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAgC;IACvE,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/transaction/transaction.ts"],"names":[],"mappings":"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"}

package/dist/src/transaction/validator.d.ts

@@ -1,5 +1,5 @@
 import type { BlockId, CollectionId, Transforms } from '../index.js';
-import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions } from './transaction.js';
+import type { Transaction, ITransactionEngine, ITransactionValidator, ValidationResult, CollectionActions, ClientSignatureVerifier } from './transaction.js';
 import type { BlockActionState } from '../network/struct.js';
 /**
  * Engine registration for validation.
@@ -37,17 +37,9 @@ export declare class TransactionValidator implements ITransactionValidator {
     private readonly engines;
     private readonly createValidationCoordinator;
     private readonly blockStateProvider?;
-    constructor(engines: Map<string, EngineRegistration>, createValidationCoordinator: ValidationCoordinatorFactory, blockStateProvider?: BlockStateProvider | undefined);
+    private readonly verifyClientSignature?;
+    constructor(engines: Map<string, EngineRegistration>, createValidationCoordinator: ValidationCoordinatorFactory, blockStateProvider?: BlockStateProvider | undefined, verifyClientSignature?: ClientSignatureVerifier | undefined);
     validate(transaction: Transaction, operationsHash: string): Promise<ValidationResult>;
     getSchemaHash(engineId: string): Promise<string | undefined>;
-    /**
-     * Collect all operations from transforms.
-     */
-    private collectOperations;
-    /**
-     * Compute hash of all operations.
-     * Must match TransactionCoordinator.hashOperations for consistent validation.
-     */
-    private hashOperations;
 }
 //# sourceMappingURL=validator.d.ts.map

package/dist/src/transaction/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAA2B,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACpI,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAa7D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,sCAAsC;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,kDAAkD;IAClD,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,MAAM;IAChD,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,mDAAmD;IACnD,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC/C,4CAA4C;IAC5C,OAAO,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;AAE7F;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,qBAAqB;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,2BAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBAFnB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACxC,2BAA2B,EAAE,4BAA4B,EACzD,kBAAkB,CAAC,EAAE,kBAAkB,YAAA;IAGnD,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmFrF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAKlE;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAczB;;;OAGG;YACW,cAAc;CAI5B"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC7J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAI7D;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,sCAAsC;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,kDAAkD;IAClD,aAAa,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,MAAM;IAChD,qDAAqD;IACrD,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E,mDAAmD;IACnD,aAAa,IAAI,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC/C,4CAA4C;IAC5C,OAAO,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;AAE7F;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,qBAAqB;IAEhE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,2BAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC;gBAHtB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACxC,2BAA2B,EAAE,4BAA4B,EACzD,kBAAkB,CAAC,EAAE,kBAAkB,YAAA,EACvC,qBAAqB,CAAC,EAAE,uBAAuB,YAAA;IAG3D,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8IrF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAIlE"}

package/dist/src/transaction/validator.js

@@ -1,5 +1,5 @@
-import { isTransactionExpired } from './transaction.js';
-import { hashString } from '../utility/hash-string.js';
+import { isTransactionExpired, clientSignaturePayload, computeStampId } from './transaction.js';
+import { collectOperations, hashOperations, opsHashVersion, OPS_HASH_VERSION } from './operations-hash.js';
 /**
  * Transaction validator implementation.
  *
@@ -10,20 +10,43 @@ export class TransactionValidator {
     engines;
     createValidationCoordinator;
     blockStateProvider;
-    constructor(engines, createValidationCoordinator, blockStateProvider) {
+    verifyClientSignature;
+    constructor(engines, createValidationCoordinator, blockStateProvider, verifyClientSignature) {
         this.engines = engines;
         this.createValidationCoordinator = createValidationCoordinator;
         this.blockStateProvider = blockStateProvider;
+        this.verifyClientSignature = verifyClientSignature;
     }
     async validate(transaction, operationsHash) {
         const { stamp } = transaction;
-        // 0. Check expiration before any other work
+        // 0.0. Integrity: the id must be the true hash of the stamp fields. Runs FIRST because
+        // every later step (expiration, signature, engine/schema selection) trusts a stamp field.
+        // Always-on (one SHA-256, cheap) and independent of whether a signature verifier is wired —
+        // a tampered stamp corrupts expiration and engine selection regardless of signatures.
+        const expectedId = await computeStampId(stamp);
+        if (expectedId !== stamp.id) {
+            return { valid: false, reason: 'Tampered transaction stamp' };
+        }
+        // 0. Check expiration before any other work. Ordered BEFORE the signature check so
+        // an attacker cannot learn signature-validity for an already-expired transaction.
         if (isTransactionExpired(stamp)) {
             return {
                 valid: false,
                 reason: `Transaction expired at ${stamp.expiration}`
             };
         }
+        // 0.5. Verify the client signature, if a verifier port is wired. When the port is
+        // absent (migration / single-node-dev posture) unsigned AND signed transactions
+        // both pass — the p2p enforcement flag decides whether to inject the port at all.
+        if (this.verifyClientSignature) {
+            if (transaction.signature === undefined) {
+                return { valid: false, reason: 'Missing client signature' };
+            }
+            const payload = clientSignaturePayload(stamp.id, transaction.statements, transaction.reads);
+            if (!this.verifyClientSignature(stamp.peerId, payload, transaction.signature)) {
+                return { valid: false, reason: 'Invalid client signature' };
+            }
+        }
         // 1. Verify engine exists
         const registration = this.engines.get(stamp.engineId);
         if (!registration) {
@@ -56,7 +79,24 @@ export class TransactionValidator {
         // 4. Create isolated validation coordinator
         const validationCoordinator = this.createValidationCoordinator();
         try {
-            // 5. Re-execute transaction through engine
+            // 5. Re-execute transaction through engine.
+            //
+            // Which of the two ITransactionEngine models the registered engine uses decides
+            // where isolation comes from (see the contract in transaction.ts):
+            //
+            //   (a) PURE TRANSLATOR (ActionsEngine) — execute() parses statements into
+            //       actions and mutates NOTHING, so even an engine constructed against the
+            //       MAIN coordinator cannot leak into main state here. The returned actions
+            //       are applied once, on the isolated validationCoordinator at step 6.
+            //
+            //   (b) SIDE-EFFECT APPLY (QuereusEngine) — execute() applies while translating
+            //       (db.exec drives the vtab into coordinator.applyActions) and returns EMPTY
+            //       actions. That application lands on whatever coordinator the engine/vtab is
+            //       bound to, NOT on validationCoordinator, so isolation is the caller's job:
+            //       the createValidationCoordinator wiring must bind/reset an isolated world
+            //       (see quereus-validator, which resets the coordinator before each run and
+            //       makes its validationCoordinator.applyActions a no-op). Step 6 is then
+            //       skipped by the empty-actions guard.
             const result = await registration.engine.execute(transaction);
             if (!result.success) {
                 return {
@@ -64,17 +104,36 @@ export class TransactionValidator {
                     reason: `Re-execution failed: ${result.error}`
                 };
             }
-            // 6. Apply actions to validation coordinator (builds transforms)
+            // 6. Apply actions to the isolated validation coordinator (builds transforms).
+            // Reached only for pure-translator engines that RETURNED actions; a side-effect
+            // engine returns empty and already applied during execute() (see above).
             if (result.actions && result.actions.length > 0) {
                 await validationCoordinator.applyActions(result.actions, stamp.id);
             }
             // 7. Collect operations from validation coordinator
             const transforms = validationCoordinator.getTransforms();
-            const allOperations = this.collectOperations(transforms);
-            // 8. Compute hash
-            const computedHash = await this.hashOperations(allOperations);
-            // 9. Compare with sender's hash
+            // 8. Compute hash via the shared operations-hash module — the SAME collect +
+            // canonicalise + hash the coordinator ran, so an honest sender and this
+            // validator cannot diverge on ordering.
+            const computedHash = await hashOperations(collectOperations(transforms));
+            // 9. Compare with sender's hash. Split the failure into two distinct causes so
+            // version skew is diagnosable rather than looking like a content fault:
+            //   - VERSION SKEW: the sender's token carries a format version this node does not
+            //     produce (a foreign vN, a bare legacy `ops:`, or an unparseable token → null).
+            //     These bytes are not even comparable, so surface a clear "unsupported format
+            //     version" error. This is DETECTION only — the node cannot cross-compute the
+            //     peer's format, so a mixed-version cluster fails legibly, not silently.
+            //   - CONTENT MISMATCH: same format version, different bytes — a genuine operations
+            //     disagreement (or a Byzantine lie); the existing error is unchanged.
             if (computedHash !== operationsHash) {
+                const senderVersion = opsHashVersion(operationsHash);
+                if (senderVersion !== OPS_HASH_VERSION) {
+                    return {
+                        valid: false,
+                        reason: `Unsupported operations-hash format version: local=${OPS_HASH_VERSION}, sender=${senderVersion ?? 'unrecognized'}`,
+                        computedHash
+                    };
+                }
                 return {
                     valid: false,
                     reason: `Operations hash mismatch`,
@@ -91,23 +150,5 @@ export class TransactionValidator {
         const registration = this.engines.get(engineId);
         return registration ? await registration.getSchemaHash() : undefined;
     }
-    /**
-     * Collect all operations from transforms.
-     */
-    collectOperations(transforms) {
-        return Array.from(transforms.entries()).flatMap(([collectionId, t]) => [
-            ...Object.entries(t.inserts ?? {}).map(([blockId, block]) => ({ type: 'insert', collectionId, blockId, block })),
-            ...Object.entries(t.updates ?? {}).map(([blockId, operations]) => ({ type: 'update', collectionId, blockId, operations })),
-            ...(t.deletes ?? []).map(blockId => ({ type: 'delete', collectionId, blockId }))
-        ]);
-    }
-    /**
-     * Compute hash of all operations.
-     * Must match TransactionCoordinator.hashOperations for consistent validation.
-     */
-    async hashOperations(operations) {
-        const operationsData = JSON.stringify(operations);
-        return `ops:${await hashString(operationsData)}`;
-    }
 }
 //# sourceMappingURL=validator.js.map

package/dist/src/transaction/validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../../src/transaction/validator.ts"],"names":[],"mappings":"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"}

package/dist/src/transactor/network-transactor.d.ts

@@ -31,6 +31,25 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
     private readonly dialTimeoutMs;
     private readonly getRepo;
     private readonly localChangeNotifier;
+    /**
+     * Per-transaction coordinator cache: `actionId → (blockId → resolved coordinator)`.
+     * {@link pend} populates it from its final (retry-adjusted) batch assignment; commit
+     * reads it via {@link resolveCoordinator} before falling back to a live
+     * `findCoordinator`, so a block's coordinator is resolved once per transaction across
+     * the pend→commit window instead of once at pend and again at commit.
+     *
+     * Keyed by `actionId`, which is unique per transaction, so an entry is only ever read
+     * by commits of the SAME transaction — the ones that immediately follow its pend. Once
+     * those finish, nothing reads the entry again (a later transaction has a fresh
+     * actionId), so it carries no cross-transaction staleness even if it lingers. The TTL
+     * and size cap in {@link txnCoordinatorsFor} are therefore only a memory backstop that
+     * reclaims entries from transactions that pend but never commit — NOT a staleness
+     * bound. This is why keying by actionId gives the same "thrown away when the
+     * transaction ends" safety as threading a Map through the call, without touching the
+     * ITransactor contract.
+     */
+    private readonly txnCoordinatorCache;
+    private static readonly MAX_TXN_COORDINATOR_CACHE_ENTRIES;
     constructor(init: NetworkTransactorInit);
     /**
      * Subscribe to commits landing on the local node for `collectionId`, delegating
@@ -66,6 +85,22 @@ export declare class NetworkTransactor implements ITransactor, IBlockChangeNotif
     private commitBlocks;
     /** Creates batches for a given payload, grouped by the coordinating peer for each block id */
     private batchesForPayload;
+    /**
+     * Resolve the coordinator for `blockId`, preferring one this transaction already
+     * resolved during pend (the per-transaction cache) before falling back to a live
+     * `findCoordinator`. A cached coordinator that is in `excludedPeers` (already tried and
+     * failed during a retry) is skipped so a retry can't loop on a dead coordinator. A
+     * cache miss — including every call with no `actionId` (get/cancel) — never fails; it
+     * always falls through to live resolution.
+     */
+    private resolveCoordinator;
+    /**
+     * Get (creating if absent) the per-transaction coordinator map for `actionId`,
+     * refreshing its expiry and lazily sweeping expired sibling entries. See
+     * {@link txnCoordinatorCache} for why the TTL/size cap here is a memory backstop and
+     * not a staleness bound.
+     */
+    private txnCoordinatorsFor;
     /** Cancels a pending transaction by canceling all blocks associated with the transaction, including failed peers */
     private cancelBatch;
     private formatBatchStatuses;

package/dist/src/transactor/network-transactor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/network-transactor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAA6B,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAc,aAAa,EAA+B,qBAAqB,EAAE,YAAY,EAAU,MAAM,aAAa,CAAC;AAClU,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAS3F,KAAK,qBAAqB,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,WAAW,CAAC;IACxB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;CAC3C,CAAA;AAWD,qBAAa,iBAAkB,YAAW,WAAW,EAAE,oBAAoB;IAC1E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmC;gBAGtE,IAAI,EAAE,qBAAqB;IAc5B;;;;;OAKG;IACH,kBAAkB,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAQxF,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC;IAyHnD,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0C3E;;;;;;;;;;;OAWG;YACW,yBAAyB;IA6BvC,yGAAyG;YAC3F,sBAAsB;YAuBtB,uBAAuB;IA+F/B,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAgGnD,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOtE,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;YAyC7C,WAAW;IAezB,0EAA0E;YAC5D,YAAY;IAoC1B,8FAA8F;YAChF,iBAAiB;IAe/B,oHAAoH;YACtG,WAAW;IAqBzB,OAAO,CAAC,mBAAmB;CAY3B;AAiDD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAIlG"}
+{"version":3,"file":"network-transactor.d.ts","sourceRoot":"","sources":["../../../src/transactor/network-transactor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAA6B,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAc,aAAa,EAA+B,qBAAqB,EAAE,YAAY,EAAU,MAAM,aAAa,CAAC;AAClU,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAS3F,KAAK,qBAAqB,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,UAAU,EAAE,WAAW,CAAC;IACxB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;IACnC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;CAC3C,CAAA;AAWD,qBAAa,iBAAkB,YAAW,WAAW,EAAE,oBAAoB;IAC1E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmC;IAEvE;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAgF;IACpH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iCAAiC,CAAQ;gBAGhE,IAAI,EAAE,qBAAqB;IAc5B;;;;;OAKG;IACH,kBAAkB,CAAC,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,wBAAwB,GAAG,MAAM,IAAI;IAQxF,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC;IAsInD,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA0C3E;;;;;;;;;;;OAWG;YACW,yBAAyB;IA6BvC,yGAAyG;YAC3F,sBAAsB;YAuBtB,uBAAuB;IA+F/B,IAAI,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAiHnD,MAAM,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAOtE,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;YAyC7C,WAAW;IAqBzB,0EAA0E;YAC5D,YAAY;IAsC1B,8FAA8F;YAChF,iBAAiB;IAiB/B;;;;;;;OAOG;YACW,kBAAkB;IAchC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA2B1B,oHAAoH;YACtG,WAAW;IAqBzB,OAAO,CAAC,mBAAmB;CAY3B;AAiDD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,gBAAgB,EAAE,GAAG,gBAAgB,EAAE,CAIlG"}