@aztec/pxe 5.0.0-private.20260319 → 5.0.0-rc.2

package/dest/storage/fact_store/fact_store.d.ts

@@ -0,0 +1,95 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { AztecAsyncKVStore } from '@aztec/kv-store';
+import type { StagedStore } from '../../job_coordinator/job_coordinator.js';
+import { FactCollectionKey, type FactCollectionTypeKey, type OriginBlock } from './fact_store_keys.js';
+import { type Fact } from './stored_fact.js';
+type BlockNum = number;
+/** A fact collection as returned by the store. */
+export type FactCollection = {
+    key: FactCollectionKey;
+    facts: Fact[];
+};
+/**
+ * Stores immutable facts grouped into collections, isolated by contract and scope.
+ *
+ * A fact collection is a contract-defined bag of facts identified by a {@link FactCollectionKey} (contract, scope,
+ * collection type, and id). A fact is a contract-defined immutable, typed datum in a collection. Collections are
+ * implicit: one comes into being when its first fact is recorded and ceases to exist once it has no facts left.
+ *
+ * What makes this store different to, for example, the `CapsuleStore`, is that it is designed to support use cases
+ * where resilience to reorgs is needed, via what we call _retractability_.
+ *
+ * Facts can be retractable or non-retractable. They are retractable if they are associated to an origin block.
+ * Retractable facts are removed from the store when their origin block is pruned (typically due to a reorg).
+ * Non-retractable facts survive reorgs: they must then be explicitly deleted, so as not to keep consuming resources
+ * (storage and compute) indefinitely.
+ *
+ * Fact collections are isolated by scope.
+ *
+ * This store is designed to enable Aztec.nr to implement complex workflows such as offchain reception or partial note
+ * processing by storing structured data that is guaranteed to exist conditionally to specific blocks being included in
+ * the chain, while leaving the complexity of ensuring said guarantees to PXE.
+ *
+ * A key design driver is that PXE knows nothing about the actual fact contents: it just manages enough metadata to
+ * provide the guarantees mentioned above. That way, concepts such as offchain delivery or partial notes are completely
+ * defined by Aztec.nr, opening the door to further extension without the need for ad-hoc PXE support.
+ *
+ * As with most other PXE stores, writes are staged per-job and flushed atomically on commit.
+ */
+export declare class FactStore implements StagedStore {
+    #private;
+    readonly storeName: string;
+    logger: import("@aztec/foundation/log").Logger;
+    constructor(store: AztecAsyncKVStore);
+    /**
+     * Records a fact in a collection.
+     *
+     * The collection is created implicitly on the first fact recorded for its key: recording into an existing collection
+     * just adds to it.
+     *
+     * If `originBlock === undefined`, the fact is non-retractable: it survives reorgs. A defined origin block makes the
+     * fact retractable: on a prune below its block, it will be deleted.
+     *
+     * Idempotent: re-recording an identical fact (same collection, fact type, payload, and origin block) is a no-op.
+     * The same payload tied to a different origin block is a distinct fact.
+     */
+    recordFact(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined, jobId: string): Promise<void>;
+    /**
+     * Deletes a fact collection: removes every fact under the (scope-qualified) collection key.
+     *
+     * Idempotent: deleting a collection that does not exist is a no-op.
+     */
+    deleteFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<void>;
+    /**
+     * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+     */
+    getFactCollection(factCollectionKey: FactCollectionKey, jobId: string): Promise<FactCollection | undefined>;
+    /**
+     * Returns every fact collection of the given type for the queried scope, each holding its facts.
+     */
+    getFactCollectionsByType(factCollectionTypeKey: FactCollectionTypeKey, jobId: string): Promise<FactCollection[]>;
+    /**
+     * Commits all staged operations for the given job to persistent storage.
+     *
+     * Must be called inside a transaction owned by the caller (JobCoordinator wraps all commits in a single
+     * transactionAsync, and IndexedDB does not support nested transactions).
+     *
+     * DO NOT call `#withJobLock` here: awaiting the lock creates a microtask boundary that causes IndexedDB to
+     * auto-commit the outer transaction.
+     */
+    commit(jobId: string): Promise<void>;
+    /** Discards all staged operations for the given job without persisting them. */
+    discardStaged(jobId: string): Promise<void>;
+    /**
+     * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+     *
+     * Non-retractable facts are untouched. Must run inside a caller-owned transaction (because it needs to share the
+     * transaction with other stores and IndexedDB has no nested transactions).
+     *
+     * Throws if any job is in flight (has accessed the store and not yet committed or discarded), since rolling back
+     * mid-job could re-introduce records originating from deleted blocks or change state underneath a job's view.
+     */
+    rollback(toBlock: BlockNum): Promise<void>;
+}
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zdG9yZS5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3N0b3JhZ2UvZmFjdF9zdG9yZS9mYWN0X3N0b3JlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBR3pELE9BQU8sS0FBSyxFQUFFLGlCQUFpQixFQUFxQyxNQUFNLGlCQUFpQixDQUFDO0FBRTVGLE9BQU8sS0FBSyxFQUFFLFdBQVcsRUFBRSxNQUFNLDBDQUEwQyxDQUFDO0FBQzVFLE9BQU8sRUFBRSxpQkFBaUIsRUFBRSxLQUFLLHFCQUFxQixFQUFFLEtBQUssV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDdkcsT0FBTyxFQUFFLEtBQUssSUFBSSxFQUE0QixNQUFNLGtCQUFrQixDQUFDO0FBR3ZFLEtBQUssUUFBUSxHQUFHLE1BQU0sQ0FBQztBQU12QixrREFBa0Q7QUFDbEQsTUFBTSxNQUFNLGNBQWMsR0FBRztJQUFFLEdBQUcsRUFBRSxpQkFBaUIsQ0FBQztJQUFDLEtBQUssRUFBRSxJQUFJLEVBQUUsQ0FBQTtDQUFFLENBQUM7QUFRdkU7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBMEJHO0FBQ0gscUJBQWEsU0FBVSxZQUFXLFdBQVc7O0lBQzNDLFFBQVEsQ0FBQyxTQUFTLEVBQUUsTUFBTSxDQUFVO0lBbUJwQyxNQUFNLHlDQUE4QjtJQUVwQyxZQUFZLEtBQUssRUFBRSxpQkFBaUIsRUFPbkM7SUFFRDs7Ozs7Ozs7Ozs7T0FXRztJQUNILFVBQVUsQ0FDUixpQkFBaUIsRUFBRSxpQkFBaUIsRUFDcEMsVUFBVSxFQUFFLEVBQUUsRUFDZCxPQUFPLEVBQUUsRUFBRSxFQUFFLEVBQ2IsV0FBVyxFQUFFLFdBQVcsR0FBRyxTQUFTLEVBQ3BDLEtBQUssRUFBRSxNQUFNLEdBQ1osT0FBTyxDQUFDLElBQUksQ0FBQyxDQVFmO0lBRUQ7Ozs7T0FJRztJQUNILG9CQUFvQixDQUFDLGlCQUFpQixFQUFFLGlCQUFpQixFQUFFLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUt2RjtJQUVEOztPQUVHO0lBQ0csaUJBQWlCLENBQUMsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQUUsS0FBSyxFQUFFLE1BQU0sR0FBRyxPQUFPLENBQUMsY0FBYyxHQUFHLFNBQVMsQ0FBQyxDQVVoSDtJQUVEOztPQUVHO0lBQ0csd0JBQXdCLENBQzVCLHFCQUFxQixFQUFFLHFCQUFxQixFQUM1QyxLQUFLLEVBQUUsTUFBTSxHQUNaLE9BQU8sQ0FBQyxjQUFjLEVBQUUsQ0FBQyxDQU8zQjtJQUVEOzs7Ozs7OztPQVFHO0lBQ0csTUFBTSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQWdCekM7SUFFRCxnRkFBZ0Y7SUFDaEYsYUFBYSxDQUFDLEtBQUssRUFBRSxNQUFNLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQUcxQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0csUUFBUSxDQUFDLE9BQU8sRUFBRSxRQUFRLEdBQUcsT0FBTyxDQUFDLElBQUksQ0FBQyxDQVEvQztDQTJSRiJ9

package/dest/storage/fact_store/fact_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/fact_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAqC,MAAM,iBAAiB,CAAC;AAE5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACvG,OAAO,EAAE,KAAK,IAAI,EAA4B,MAAM,kBAAkB,CAAC;AAGvE,KAAK,QAAQ,GAAG,MAAM,CAAC;AAMvB,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC;AAQvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAU,YAAW,WAAW;;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAU;IAmBpC,MAAM,yCAA8B;IAEpC,YAAY,KAAK,EAAE,iBAAiB,EAOnC;IAED;;;;;;;;;;;OAWG;IACH,UAAU,CACR,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAQf;IAED;;;;OAIG;IACH,oBAAoB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvF;IAED;;OAEG;IACG,iBAAiB,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAUhH;IAED;;OAEG;IACG,wBAAwB,CAC5B,qBAAqB,EAAE,qBAAqB,EAC5C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,EAAE,CAAC,CAO3B;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBzC;IAED,gFAAgF;IAChF,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1C;IAED;;;;;;;;OAQG;IACG,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/C;CA2RF"}

package/dest/storage/fact_store/fact_store.js

@@ -0,0 +1,408 @@
+import { createLogger } from '@aztec/foundation/log';
+import { Semaphore } from '@aztec/foundation/queue';
+import { FactCollectionKey } from './fact_store_keys.js';
+import { StoredFact, factKeyStrOf } from './stored_fact.js';
+/**
+ * Stores immutable facts grouped into collections, isolated by contract and scope.
+ *
+ * A fact collection is a contract-defined bag of facts identified by a {@link FactCollectionKey} (contract, scope,
+ * collection type, and id). A fact is a contract-defined immutable, typed datum in a collection. Collections are
+ * implicit: one comes into being when its first fact is recorded and ceases to exist once it has no facts left.
+ *
+ * What makes this store different to, for example, the `CapsuleStore`, is that it is designed to support use cases
+ * where resilience to reorgs is needed, via what we call _retractability_.
+ *
+ * Facts can be retractable or non-retractable. They are retractable if they are associated to an origin block.
+ * Retractable facts are removed from the store when their origin block is pruned (typically due to a reorg).
+ * Non-retractable facts survive reorgs: they must then be explicitly deleted, so as not to keep consuming resources
+ * (storage and compute) indefinitely.
+ *
+ * Fact collections are isolated by scope.
+ *
+ * This store is designed to enable Aztec.nr to implement complex workflows such as offchain reception or partial note
+ * processing by storing structured data that is guaranteed to exist conditionally to specific blocks being included in
+ * the chain, while leaving the complexity of ensuring said guarantees to PXE.
+ *
+ * A key design driver is that PXE knows nothing about the actual fact contents: it just manages enough metadata to
+ * provide the guarantees mentioned above. That way, concepts such as offchain delivery or partial notes are completely
+ * defined by Aztec.nr, opening the door to further extension without the need for ad-hoc PXE support.
+ *
+ * As with most other PXE stores, writes are staged per-job and flushed atomically on commit.
+ */ export class FactStore {
+    storeName = 'fact';
+    #store;
+    /** Primary index of fact records. */ #facts;
+    /** Index for per-collection fact enumeration and by-type collection discovery. */ #factsByCollection;
+    /** Index for delete-on-prune of retractable facts (those with an origin block). */ #factsByBlock;
+    /** Job uncommitted data */ #opsForJob;
+    /** Per-job locks */ #jobLocks;
+    logger = createLogger('fact_store');
+    constructor(store){
+        this.#store = store;
+        this.#facts = store.openMap('facts');
+        this.#factsByCollection = store.openMultiMap('facts_by_collection');
+        this.#factsByBlock = store.openMultiMap('facts_by_block');
+        this.#opsForJob = new Map();
+        this.#jobLocks = new Map();
+    }
+    /**
+   * Records a fact in a collection.
+   *
+   * The collection is created implicitly on the first fact recorded for its key: recording into an existing collection
+   * just adds to it.
+   *
+   * If `originBlock === undefined`, the fact is non-retractable: it survives reorgs. A defined origin block makes the
+   * fact retractable: on a prune below its block, it will be deleted.
+   *
+   * Idempotent: re-recording an identical fact (same collection, fact type, payload, and origin block) is a no-op.
+   * The same payload tied to a different origin block is a distinct fact.
+   */ recordFact(factCollectionKey, factTypeId, payload, originBlock, jobId) {
+        return this.#withJobLock(jobId, ()=>{
+            this.#stagedOpsFor(jobId).push({
+                kind: 'recordFact',
+                fact: new StoredFact(factCollectionKey, factTypeId, payload, originBlock)
+            });
+            return Promise.resolve();
+        });
+    }
+    /**
+   * Deletes a fact collection: removes every fact under the (scope-qualified) collection key.
+   *
+   * Idempotent: deleting a collection that does not exist is a no-op.
+   */ deleteFactCollection(factCollectionKey, jobId) {
+        return this.#withJobLock(jobId, ()=>{
+            this.#stagedOpsFor(jobId).push({
+                kind: 'deleteFactCollection',
+                key: factCollectionKey
+            });
+            return Promise.resolve();
+        });
+    }
+    /**
+   * Returns the fact collection for the (scope-qualified) key, or undefined if it has no facts.
+   */ async getFactCollection(factCollectionKey, jobId) {
+        const collectionKey = factCollectionKey.toString();
+        const committed = await this.#store.transactionAsync(()=>this.#readCollectionsFromDb([
+                factCollectionKey
+            ]));
+        const collection = this.#foldStagedOps(committed, jobId).get(collectionKey);
+        if (!collection) {
+            return undefined;
+        }
+        const facts = [
+            ...collection.facts.values()
+        ];
+        return facts.length > 0 ? {
+            key: factCollectionKey,
+            facts
+        } : undefined;
+    }
+    /**
+   * Returns every fact collection of the given type for the queried scope, each holding its facts.
+   */ async getFactCollectionsByType(factCollectionTypeKey, jobId) {
+        const typeKey = factCollectionTypeKey.toString();
+        const committed = await this.#readCollectionsFromDbByType(typeKey);
+        return Array.from(this.#foldStagedOps(committed, jobId, typeKey).values()).map((collection)=>({
+                key: collection.key,
+                facts: [
+                    ...collection.facts.values()
+                ]
+            })).filter((collection)=>collection.facts.length > 0);
+    }
+    /**
+   * Commits all staged operations for the given job to persistent storage.
+   *
+   * Must be called inside a transaction owned by the caller (JobCoordinator wraps all commits in a single
+   * transactionAsync, and IndexedDB does not support nested transactions).
+   *
+   * DO NOT call `#withJobLock` here: awaiting the lock creates a microtask boundary that causes IndexedDB to
+   * auto-commit the outer transaction.
+   */ async commit(jobId) {
+        for (const op of this.#stagedOpsFor(jobId)){
+            switch(op.kind){
+                case 'recordFact':
+                    await this.#commitFact(op.fact);
+                    break;
+                case 'deleteFactCollection':
+                    await this.#deleteCollection(op.key.toString());
+                    break;
+                default:
+                    {
+                        const _exhaustive = op;
+                        throw new Error(`Unhandled FactStore staged op kind: ${JSON.stringify(_exhaustive)}`);
+                    }
+            }
+        }
+        this.#clearJobData(jobId);
+    }
+    /** Discards all staged operations for the given job without persisting them. */ discardStaged(jobId) {
+        this.#clearJobData(jobId);
+        return Promise.resolve();
+    }
+    /**
+   * Removes every retractable fact originating from blocks over height `toBlock`, across all scopes.
+   *
+   * Non-retractable facts are untouched. Must run inside a caller-owned transaction (because it needs to share the
+   * transaction with other stores and IndexedDB has no nested transactions).
+   *
+   * Throws if any job is in flight (has accessed the store and not yet committed or discarded), since rolling back
+   * mid-job could re-introduce records originating from deleted blocks or change state underneath a job's view.
+   */ async rollback(toBlock) {
+        if (this.#opsForJob.size > 0) {
+            throw new Error('PXE fact store rollback is not allowed while jobs are running');
+        }
+        const removedFacts = await this.#retractFacts(toBlock);
+        this.logger.verbose('rolled back fact store', {
+            removedFacts,
+            toBlock
+        });
+    }
+    /**
+   * Deletes retractable facts originating above `toBlock`, returning the number of by-block entries scanned.
+   * Retraction is scope-agnostic: a reorg invalidates a fact regardless of which scope's collection it belongs to.
+   *
+   * Requires to be run in a transactionAsync context.
+   */ async #retractFacts(toBlock) {
+        // Snapshot the orphaned fact keys before mutating so we never delete from the cursor we are iterating, kicking off
+        // each fact-body read during the scan so a DB request stays pending across the cursor-to-delete boundary (a drained
+        // cursor with no read in flight would let the transaction auto-commit before the deletes).
+        const factReads = new Map();
+        for await (const [, factKey] of this.#factsByBlock.entriesAsync({
+            start: toBlock + 1
+        })){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        await Promise.all(Array.from(factReads, async ([factKey, read])=>{
+            const buf = await read;
+            if (!buf) {
+                // The by-block index just yielded this factKey, so a missing primary record means the indexes are out of
+                // sync. Log as this should be unreachable unless there is a bug.
+                this.logger.warn('Skipping retraction of a fact missing from the primary store: by-block index is stale', {
+                    factKey
+                });
+                return;
+            }
+            await this.#deleteFact(factKey, StoredFact.fromBuffer(buf));
+        }));
+        return factReads.size;
+    }
+    /**
+   * Reads the given collections (their facts) by key into a Map keyed by collection key, skipping
+   * keys with no committed facts.
+   *
+   * Reads are not wrapped in a transaction: the caller owns the transaction boundary.
+   */ async #readCollectionsFromDb(keys) {
+        const result = new Map();
+        for (const key of keys){
+            const collection = await this.#loadCommittedCollection(key);
+            if (collection) {
+                result.set(key.toString(), collection);
+            }
+        }
+        return result;
+    }
+    #readCollectionsFromDbByType(typeKey) {
+        return this.#store.transactionAsync(async ()=>{
+            const factReadsByCollection = new Map();
+            for await (const [collectionKey, factKey] of this.#factsByCollection.entriesAsync({
+                start: `${typeKey}:`,
+                end: `${typeKey};`
+            })){
+                let reads = factReadsByCollection.get(collectionKey);
+                if (!reads) {
+                    reads = new Map();
+                    factReadsByCollection.set(collectionKey, reads);
+                }
+                reads.set(factKey, this.#facts.getAsync(factKey));
+            }
+            const result = new Map();
+            for (const [collectionKey, reads] of factReadsByCollection){
+                const collection = await this.#assembleCollection(FactCollectionKey.fromString(collectionKey), reads);
+                result.set(collectionKey, collection);
+            }
+            return result;
+        });
+    }
+    async #loadCommittedCollection(collectionKey) {
+        // Kick off each fact read while iterating the index so a DB request is always pending. Draining the cursor and only
+        // then reading the facts one `await` at a time would let the IndexedDB transaction auto-commit at the boundary
+        // (IndexedDB auto-commits once control returns to the event loop with no pending request), throwing mid-read on the
+        // browser backend.
+        const factReads = new Map();
+        for await (const factKey of this.#factsByCollection.getValuesAsync(collectionKey.toString())){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        if (factReads.size === 0) {
+            return undefined;
+        }
+        return this.#assembleCollection(collectionKey, factReads);
+    }
+    /**
+   * Assemble a collection's facts from a set of in-flight DB reads.
+   */ async #assembleCollection(collectionKey, reads) {
+        const factKeys = [
+            ...reads.keys()
+        ];
+        const bufs = await Promise.all(reads.values());
+        // Await-free tail: deserialize. No DB ops from here on.
+        const facts = new Map();
+        for(let i = 0; i < factKeys.length; i++){
+            const factKey = factKeys[i];
+            const buf = bufs[i];
+            if (!buf) {
+                // Defensive: a #factsByCollection entry must always reference a live #facts entry. A missing one means the
+                // indexes are corrupt.
+                throw new Error(`Fact not found for factKey ${factKey}`);
+            }
+            const stored = StoredFact.fromBuffer(buf);
+            if (stored.factCollectionKey.toString() !== collectionKey.toString()) {
+                // Defensive: every read fact must belong to the collection being assembled. A mismatch means the indexes are
+                // corrupt.
+                throw new Error(`Fact ${factKey} does not belong to collection ${collectionKey}`);
+            }
+            facts.set(factKey, stored.toFact());
+        }
+        return {
+            key: collectionKey,
+            facts
+        };
+    }
+    /**
+   * Assembles the current view of a collection of collections together with their facts, combining the committed with
+   * staged data.
+   *
+   * When `typeKey` is given, staged records of other types are ignored, so the result holds only that type.
+   */ #foldStagedOps(committed, jobId, typeKey) {
+        const result = new Map();
+        // Copy to avoid mutating the contents of `committed`.
+        for (const [collectionKey, { key, facts }] of committed){
+            result.set(collectionKey, {
+                key,
+                facts: new Map(facts)
+            });
+        }
+        for (const op of this.#stagedOpsFor(jobId)){
+            switch(op.kind){
+                case 'recordFact':
+                    this.#foldRecordFact(result, op, typeKey);
+                    break;
+                case 'deleteFactCollection':
+                    this.#foldDeleteFactCollection(result, op);
+                    break;
+                default:
+                    {
+                        const _exhaustive = op;
+                        throw new Error(`Unhandled FactStore staged op kind: ${JSON.stringify(_exhaustive)}`);
+                    }
+            }
+        }
+        return result;
+    }
+    /**
+   * Folds a staged `recordFact` op into view.
+   *
+   * When `typeKey` is given, an op of another type is ignored, keeping the view limited to that type.
+   */ #foldRecordFact(result, op, typeKey) {
+        const key = op.fact.factCollectionKey;
+        // Type filter doesn't match, nothing to do with this fact
+        if (typeKey !== undefined && key.factCollectionTypeKey().toString() !== typeKey) {
+            return;
+        }
+        const collectionKey = key.toString();
+        let collection = result.get(collectionKey);
+        // Collection didn't exist before this point, the created fact brings it into existence
+        if (!collection) {
+            collection = {
+                key,
+                facts: new Map()
+            };
+            result.set(collectionKey, collection);
+        }
+        const fKey = factKeyStrOf(op.fact);
+        if (!collection.facts.has(fKey)) {
+            collection.facts.set(fKey, op.fact.toFact());
+        }
+    }
+    /**
+   * Folds a staged `deleteFactCollection` op into the view: the scope-qualified collection is removed outright.
+   */ #foldDeleteFactCollection(result, op) {
+        result.delete(op.key.toString());
+    }
+    /**
+   * Writes a fact to persistent storage. Idempotent: an identical fact (same scope-qualified key) is left untouched.
+   */ async #commitFact(fact) {
+        const factKey = factKeyStrOf(fact);
+        if (await this.#facts.hasAsync(factKey)) {
+            this.logger.debug(`Ignoring already recorded fact`, {
+                factKey
+            });
+            return;
+        }
+        await this.#facts.set(factKey, fact.toBuffer());
+        await this.#factsByCollection.set(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await this.#factsByBlock.set(fact.originBlock.blockNumber, factKey);
+        }
+    }
+    /**
+   * Deletes every fact under the (scope-qualified) collection key.
+   *
+   * Caller must wrap in a transaction.
+   */ async #deleteCollection(collectionKey) {
+        // Snapshot the fact index before mutating so we never delete from the cursor we are iterating, kicking off each
+        // fact-body read during the scan so a DB request stays pending across the cursor-to-mutation boundary (a drained
+        // cursor with no read in flight would let the transaction auto-commit before the deletes).
+        const factReads = new Map();
+        for await (const factKey of this.#factsByCollection.getValuesAsync(collectionKey)){
+            factReads.set(factKey, this.#facts.getAsync(factKey));
+        }
+        await Promise.all(Array.from(factReads, async ([factKey, read])=>{
+            const buf = await read;
+            if (!buf) {
+                // A #factsByCollection entry must always reference a live #facts entry, a missing one means the indexes are
+                // corrupt.
+                throw new Error(`Fact not found for factKey ${factKey}`);
+            }
+            await this.#deleteFact(factKey, StoredFact.fromBuffer(buf));
+        }));
+    }
+    /**
+   * Deletes a fact from the primary store and all its indexes (`#factsByCollection`, plus `#factsByBlock` if
+   * retractable).
+   *
+   * Caller must wrap in a transaction.
+   */ async #deleteFact(factKey, fact) {
+        await this.#facts.delete(factKey);
+        await this.#factsByCollection.deleteValue(fact.factCollectionKey.toString(), factKey);
+        if (fact.originBlock !== undefined) {
+            await this.#factsByBlock.deleteValue(fact.originBlock.blockNumber, factKey);
+        }
+    }
+    /**
+   * Returns the job's staged-ops array, creating it on first access.
+   * */ #stagedOpsFor(jobId) {
+        let ops = this.#opsForJob.get(jobId);
+        if (ops === undefined) {
+            ops = [];
+            this.#opsForJob.set(jobId, ops);
+        }
+        return ops;
+    }
+    #clearJobData(jobId) {
+        this.#opsForJob.delete(jobId);
+        this.#jobLocks.delete(jobId);
+    }
+    async #withJobLock(jobId, fn) {
+        let lock = this.#jobLocks.get(jobId);
+        if (!lock) {
+            lock = new Semaphore(1);
+            this.#jobLocks.set(jobId, lock);
+        }
+        await lock.acquire();
+        try {
+            return await fn();
+        } finally{
+            lock.release();
+        }
+    }
+}

package/dest/storage/fact_store/fact_store_keys.d.ts

@@ -0,0 +1,34 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { FieldsOf } from '@aztec/foundation/types';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+/**
+ * The block a retractable fact originates from.
+ */
+export type OriginBlock = {
+    blockNumber: number;
+    blockHash: Fr;
+};
+/** Identifies all fact collections of one type within a contract, for one scope. */
+export declare class FactCollectionTypeKey {
+    readonly contractAddress: AztecAddress;
+    readonly scope: AztecAddress;
+    readonly factCollectionTypeId: Fr;
+    constructor(contractAddress: AztecAddress, scope: AztecAddress, factCollectionTypeId: Fr);
+    static from(fields: FieldsOf<FactCollectionTypeKey>): FactCollectionTypeKey;
+    toString(): string;
+}
+/** Uniquely identifies a single fact collection, isolated by scope; all its facts share this key. */
+export declare class FactCollectionKey {
+    readonly contractAddress: AztecAddress;
+    readonly scope: AztecAddress;
+    readonly factCollectionTypeId: Fr;
+    readonly factCollectionId: Fr;
+    constructor(contractAddress: AztecAddress, scope: AztecAddress, factCollectionTypeId: Fr, factCollectionId: Fr);
+    static from(fields: FieldsOf<FactCollectionKey>): FactCollectionKey;
+    /** Inverse of toString */
+    static fromString(str: string): FactCollectionKey;
+    /** The key grouping this collection with the other collections of its type within the same contract and scope. */
+    factCollectionTypeKey(): FactCollectionTypeKey;
+    toString(): string;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmFjdF9zdG9yZV9rZXlzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3RvcmFnZS9mYWN0X3N0b3JlL2ZhY3Rfc3RvcmVfa2V5cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsRUFBRSxFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFDcEQsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFDeEQsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBRTNEOztHQUVHO0FBQ0gsTUFBTSxNQUFNLFdBQVcsR0FBRztJQUFFLFdBQVcsRUFBRSxNQUFNLENBQUM7SUFBQyxTQUFTLEVBQUUsRUFBRSxDQUFBO0NBQUUsQ0FBQztBQVNqRSxvRkFBb0Y7QUFDcEYscUJBQWEscUJBQXFCO2FBRWQsZUFBZSxFQUFFLFlBQVk7YUFDN0IsS0FBSyxFQUFFLFlBQVk7YUFDbkIsb0JBQW9CLEVBQUUsRUFBRTtJQUgxQyxZQUNrQixlQUFlLEVBQUUsWUFBWSxFQUM3QixLQUFLLEVBQUUsWUFBWSxFQUNuQixvQkFBb0IsRUFBRSxFQUFFLEVBR3pDO0lBRUQsTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLHFCQUFxQixDQUFDLEdBQUcscUJBQXFCLENBRTFFO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FFakI7Q0FDRjtBQUVELHFHQUFxRztBQUNyRyxxQkFBYSxpQkFBaUI7YUFFVixlQUFlLEVBQUUsWUFBWTthQUM3QixLQUFLLEVBQUUsWUFBWTthQUNuQixvQkFBb0IsRUFBRSxFQUFFO2FBQ3hCLGdCQUFnQixFQUFFLEVBQUU7SUFKdEMsWUFDa0IsZUFBZSxFQUFFLFlBQVksRUFDN0IsS0FBSyxFQUFFLFlBQVksRUFDbkIsb0JBQW9CLEVBQUUsRUFBRSxFQUN4QixnQkFBZ0IsRUFBRSxFQUFFLEVBR3JDO0lBRUQsTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLGlCQUFpQixDQUFDLEdBQUcsaUJBQWlCLENBT2xFO0lBRUQsMEJBQTBCO0lBQzFCLE1BQU0sQ0FBQyxVQUFVLENBQUMsR0FBRyxFQUFFLE1BQU0sR0FBRyxpQkFBaUIsQ0FRaEQ7SUFFRCxrSEFBa0g7SUFDbEgscUJBQXFCLElBQUkscUJBQXFCLENBRTdDO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FFakI7Q0FDRiJ9

package/dest/storage/fact_store/fact_store_keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store_keys.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/fact_store_keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,EAAE,CAAA;CAAE,CAAC;AASjE,oFAAoF;AACpF,qBAAa,qBAAqB;aAEd,eAAe,EAAE,YAAY;aAC7B,KAAK,EAAE,YAAY;aACnB,oBAAoB,EAAE,EAAE;IAH1C,YACkB,eAAe,EAAE,YAAY,EAC7B,KAAK,EAAE,YAAY,EACnB,oBAAoB,EAAE,EAAE,EAGzC;IAED,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAE1E;IAED,QAAQ,IAAI,MAAM,CAEjB;CACF;AAED,qGAAqG;AACrG,qBAAa,iBAAiB;aAEV,eAAe,EAAE,YAAY;aAC7B,KAAK,EAAE,YAAY;aACnB,oBAAoB,EAAE,EAAE;aACxB,gBAAgB,EAAE,EAAE;IAJtC,YACkB,eAAe,EAAE,YAAY,EAC7B,KAAK,EAAE,YAAY,EACnB,oBAAoB,EAAE,EAAE,EACxB,gBAAgB,EAAE,EAAE,EAGrC;IAED,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAOlE;IAED,0BAA0B;IAC1B,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAQhD;IAED,kHAAkH;IAClH,qBAAqB,IAAI,qBAAqB,CAE7C;IAED,QAAQ,IAAI,MAAM,CAEjB;CACF"}

package/dest/storage/fact_store/fact_store_keys.js

@@ -0,0 +1,50 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+/** Facts are always tied to a real scope; the zero address is not a valid fact scope. */ function assertNonZeroScope(scope) {
+    if (scope.equals(AztecAddress.ZERO)) {
+        throw new Error('scope must not be the zero address');
+    }
+}
+/** Identifies all fact collections of one type within a contract, for one scope. */ export class FactCollectionTypeKey {
+    contractAddress;
+    scope;
+    factCollectionTypeId;
+    constructor(contractAddress, scope, factCollectionTypeId){
+        this.contractAddress = contractAddress;
+        this.scope = scope;
+        this.factCollectionTypeId = factCollectionTypeId;
+        assertNonZeroScope(scope);
+    }
+    static from(fields) {
+        return new FactCollectionTypeKey(fields.contractAddress, fields.scope, fields.factCollectionTypeId);
+    }
+    toString() {
+        return `${this.contractAddress}:${this.scope}:${this.factCollectionTypeId}`;
+    }
+}
+/** Uniquely identifies a single fact collection, isolated by scope; all its facts share this key. */ export class FactCollectionKey {
+    contractAddress;
+    scope;
+    factCollectionTypeId;
+    factCollectionId;
+    constructor(contractAddress, scope, factCollectionTypeId, factCollectionId){
+        this.contractAddress = contractAddress;
+        this.scope = scope;
+        this.factCollectionTypeId = factCollectionTypeId;
+        this.factCollectionId = factCollectionId;
+        assertNonZeroScope(scope);
+    }
+    static from(fields) {
+        return new FactCollectionKey(fields.contractAddress, fields.scope, fields.factCollectionTypeId, fields.factCollectionId);
+    }
+    /** Inverse of toString */ static fromString(str) {
+        const [contractAddress, scope, factCollectionTypeId, factCollectionId] = str.split(':');
+        return new FactCollectionKey(AztecAddress.fromStringUnsafe(contractAddress), AztecAddress.fromStringUnsafe(scope), Fr.fromString(factCollectionTypeId), Fr.fromString(factCollectionId));
+    }
+    /** The key grouping this collection with the other collections of its type within the same contract and scope. */ factCollectionTypeKey() {
+        return new FactCollectionTypeKey(this.contractAddress, this.scope, this.factCollectionTypeId);
+    }
+    toString() {
+        return `${this.contractAddress}:${this.scope}:${this.factCollectionTypeId}:${this.factCollectionId}`;
+    }
+}

package/dest/storage/fact_store/index.d.ts

@@ -0,0 +1,5 @@
+export { FactStore, type FactCollection } from './fact_store.js';
+export { FactService } from './fact_service.js';
+export { FactCollectionKey, FactCollectionTypeKey, type OriginBlock } from './fact_store_keys.js';
+export type { Fact } from './stored_fact.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2ZhY3Rfc3RvcmUvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFNBQVMsRUFBRSxLQUFLLGNBQWMsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQ2pFLE9BQU8sRUFBRSxXQUFXLEVBQUUsTUFBTSxtQkFBbUIsQ0FBQztBQUNoRCxPQUFPLEVBQUUsaUJBQWlCLEVBQUUscUJBQXFCLEVBQUUsS0FBSyxXQUFXLEVBQUUsTUFBTSxzQkFBc0IsQ0FBQztBQUNsRyxZQUFZLEVBQUUsSUFBSSxFQUFFLE1BQU0sa0JBQWtCLENBQUMifQ==

package/dest/storage/fact_store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClG,YAAY,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}

package/dest/storage/fact_store/index.js

@@ -0,0 +1,3 @@
+export { FactStore } from './fact_store.js';
+export { FactService } from './fact_service.js';
+export { FactCollectionKey, FactCollectionTypeKey } from './fact_store_keys.js';

package/dest/storage/fact_store/stored_fact.d.ts

@@ -0,0 +1,32 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader } from '@aztec/foundation/serialize';
+import { FactCollectionKey, type OriginBlock } from './fact_store_keys.js';
+/** A fact as returned by the fact store. */
+export type Fact = {
+    factTypeId: Fr;
+    payload: Fr[];
+    originBlock: OriginBlock | undefined;
+};
+/**
+ * A single immutable fact belonging to a fact collection.
+ */
+export declare class StoredFact {
+    readonly factCollectionKey: FactCollectionKey;
+    readonly factTypeId: Fr;
+    readonly payload: Fr[];
+    readonly originBlock: OriginBlock | undefined;
+    constructor(factCollectionKey: FactCollectionKey, factTypeId: Fr, payload: Fr[], originBlock: OriginBlock | undefined);
+    /** Whether this fact is deleted on block pruning (true) or survives reorgs (false). */
+    get isRetractable(): boolean;
+    /** Stable digest of the payload, used for fact idempotency. */
+    payloadHash(): Fr;
+    /** Returns the externally facing view of this fact. */
+    toFact(): Fact;
+    toBuffer(): Buffer;
+    static fromBuffer(buffer: Buffer | BufferReader): StoredFact;
+}
+/**
+ * Builds the serialized key that identifies a fact in the store.
+ */
+export declare function factKeyStrOf(fact: StoredFact): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmVkX2ZhY3QuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL3NyYy9zdG9yYWdlL2ZhY3Rfc3RvcmUvc3RvcmVkX2ZhY3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3BELE9BQU8sRUFBRSxZQUFZLEVBQXFCLE1BQU0sNkJBQTZCLENBQUM7QUFHOUUsT0FBTyxFQUFFLGlCQUFpQixFQUFFLEtBQUssV0FBVyxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFFM0UsNENBQTRDO0FBQzVDLE1BQU0sTUFBTSxJQUFJLEdBQUc7SUFBRSxVQUFVLEVBQUUsRUFBRSxDQUFDO0lBQUMsT0FBTyxFQUFFLEVBQUUsRUFBRSxDQUFDO0lBQUMsV0FBVyxFQUFFLFdBQVcsR0FBRyxTQUFTLENBQUE7Q0FBRSxDQUFDO0FBRTNGOztHQUVHO0FBQ0gscUJBQWEsVUFBVTthQUVILGlCQUFpQixFQUFFLGlCQUFpQjthQUNwQyxVQUFVLEVBQUUsRUFBRTthQUNkLE9BQU8sRUFBRSxFQUFFLEVBQUU7YUFDYixXQUFXLEVBQUUsV0FBVyxHQUFHLFNBQVM7SUFKdEQsWUFDa0IsaUJBQWlCLEVBQUUsaUJBQWlCLEVBQ3BDLFVBQVUsRUFBRSxFQUFFLEVBQ2QsT0FBTyxFQUFFLEVBQUUsRUFBRSxFQUNiLFdBQVcsRUFBRSxXQUFXLEdBQUcsU0FBUyxFQUNsRDtJQUVKLHVGQUF1RjtJQUN2RixJQUFJLGFBQWEsSUFBSSxPQUFPLENBRTNCO0lBRUQsK0RBQStEO0lBQy9ELFdBQVcsSUFBSSxFQUFFLENBRWhCO0lBRUQsdURBQXVEO0lBQ3ZELE1BQU0sSUFBSSxJQUFJLENBRWI7SUFFRCxRQUFRLElBQUksTUFBTSxDQWFqQjtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLE1BQU0sR0FBRyxZQUFZLEdBQUcsVUFBVSxDQW1CM0Q7Q0FDRjtBQUVEOztHQUVHO0FBQ0gsd0JBQWdCLFlBQVksQ0FBQyxJQUFJLEVBQUUsVUFBVSxHQUFHLE1BQU0sQ0FHckQifQ==

package/dest/storage/fact_store/stored_fact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored_fact.d.ts","sourceRoot":"","sources":["../../../src/storage/fact_store/stored_fact.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,EAAE,YAAY,EAAqB,MAAM,6BAA6B,CAAC;AAG9E,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,MAAM,IAAI,GAAG;IAAE,UAAU,EAAE,EAAE,CAAC;IAAC,OAAO,EAAE,EAAE,EAAE,CAAC;IAAC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,CAAC;AAE3F;;GAEG;AACH,qBAAa,UAAU;aAEH,iBAAiB,EAAE,iBAAiB;aACpC,UAAU,EAAE,EAAE;aACd,OAAO,EAAE,EAAE,EAAE;aACb,WAAW,EAAE,WAAW,GAAG,SAAS;IAJtD,YACkB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,EAAE,EACd,OAAO,EAAE,EAAE,EAAE,EACb,WAAW,EAAE,WAAW,GAAG,SAAS,EAClD;IAEJ,uFAAuF;IACvF,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,+DAA+D;IAC/D,WAAW,IAAI,EAAE,CAEhB;IAED,uDAAuD;IACvD,MAAM,IAAI,IAAI,CAEb;IAED,QAAQ,IAAI,MAAM,CAajB;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAmB3D;CACF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAGrD"}