@degenerate/sharedata 0.2.7 → 0.3.1

package/README.md

@@ -8,6 +8,7 @@ The `@degenerate/sharedata` package is a core component of the SAFE system, resp
 ## Contents
 
 1. [Installation](#installation)
+2. [Persistence](#persistence)
 
 
 ## Installation
@@ -17,3 +18,33 @@ To install the `@degenerate/sharedata` package, use the following command:
 ```bash
 npm install @degenerate/sharedata
 ```
+
+## Persistence
+
+`ShareData` state is **durable** — it survives a process restart. A
+`ShareDataManager` constructed with a `ShareDataRepository` hydrates its blocks
+on `await manager.hydrate()` and write-through-persists every `addShareData` /
+`applyTransaction` / `removeShareDataById`. Constructed with no repository it
+behaves exactly as before (in-memory only), so existing callers are untouched.
+
+Loads are a **trust gate**, never a passthrough: each snapshot is replayed
+through `deserializeShareData`, which re-verifies the creation signature, the
+full structural-proof chain, and an integrity cross-check against the stored
+`expected*` values. A snapshot edited out-of-band fails loudly instead of
+loading silently. Reconstruction needs the block-type builders registered
+first — call `registerShareBlockFactories()` from `@degenerate/shareblock`
+during start-up.
+
+Three interchangeable implementations of the `ShareDataRepository` interface
+ship here:
+
+| Repository | Backing store | Typical use |
+|---|---|---|
+| `FileShareDataRepository` | one JSON file per block (atomic temp-file + rename writes) | single-node durability with no external service |
+| `FirestoreShareDataRepository` | one Firestore document per block | hosted/multi-node deployments |
+| `InMemoryShareDataRepository` | an in-process `Map` | tests and parity (still round-trips the trust gate) |
+
+`firebase-admin` is an **optional peer dependency** — only install it if you
+use `FirestoreShareDataRepository`. The repository takes an injected
+`firestore.Firestore` instance (the host initializes its own app); the package
+never references `firebase-admin` at runtime.

package/dist/index.d.ts

@@ -1,2 +1,18 @@
+export * from './manager/share-data-manager';
+export * from './manager/share-data-manager-events';
+export * from './persistence/block-factory-registry';
+export * from './persistence/serialize-share-data';
+export * from './persistence/deserialize-share-data';
+export * from './persistence/share-data-repository';
+export * from './persistence/file-share-data-repository';
+export * from './persistence/firestore-share-data-repository';
+export * from './persistence/in-memory-share-data-repository';
 export * from './share-data/share-data';
+export * from './share-data/creation/create-share-data-initial-crypto';
+export * from './share-data/proofs/creation/create-share-data-proposal-proof';
+export * from './share-data/proofs/creation/create-transaction-proposal-proof';
+export * from './share-data/proofs/creation/build-transaction-proposal-signer';
+export * from './share-data/proofs/verification/verify-share-data-proposal-proof';
+export * from './share-data/proofs/verification/verify-transaction-proposal-proof';
+export * from './share-data/proofs/testing/test-proof-signer';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sCAAsC,CAAC;AACrD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+CAA+C,CAAC;AAC9D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,yBAAyB,CAAC;AACxC,cAAc,wDAAwD,CAAC;AACvE,cAAc,+DAA+D,CAAC;AAC9E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,gEAAgE,CAAC;AAC/E,cAAc,mEAAmE,CAAC;AAClF,cAAc,oEAAoE,CAAC;AAKnF,cAAc,+CAA+C,CAAC"}

package/dist/index.js

@@ -14,4 +14,24 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./manager/share-data-manager"), exports);
+__exportStar(require("./manager/share-data-manager-events"), exports);
+__exportStar(require("./persistence/block-factory-registry"), exports);
+__exportStar(require("./persistence/serialize-share-data"), exports);
+__exportStar(require("./persistence/deserialize-share-data"), exports);
+__exportStar(require("./persistence/share-data-repository"), exports);
+__exportStar(require("./persistence/file-share-data-repository"), exports);
+__exportStar(require("./persistence/firestore-share-data-repository"), exports);
+__exportStar(require("./persistence/in-memory-share-data-repository"), exports);
 __exportStar(require("./share-data/share-data"), exports);
+__exportStar(require("./share-data/creation/create-share-data-initial-crypto"), exports);
+__exportStar(require("./share-data/proofs/creation/create-share-data-proposal-proof"), exports);
+__exportStar(require("./share-data/proofs/creation/create-transaction-proposal-proof"), exports);
+__exportStar(require("./share-data/proofs/creation/build-transaction-proposal-signer"), exports);
+__exportStar(require("./share-data/proofs/verification/verify-share-data-proposal-proof"), exports);
+__exportStar(require("./share-data/proofs/verification/verify-transaction-proposal-proof"), exports);
+// Test-only signing helpers. Naming convention (`generateTest*`,
+// `createTestProofFor`) is the documentation — these are not for
+// production use. Production wiring lives in
+// `buildEllipticalCurvesProofFor` from `@degenerate/shareblock`.
+__exportStar(require("./share-data/proofs/testing/test-proof-signer"), exports);

package/dist/manager/share-data-manager-events.d.ts

@@ -0,0 +1,27 @@
+import { IShareData, IShareFunction } from '@degenerate/generic';
+export type ShareDataManagerEventType = 'share-data:added' | 'share-data:updated' | 'share-data:removed' | 'share-data:transaction';
+export interface ShareDataAddedEvent {
+    type: 'share-data:added';
+    shareDataId: string;
+    currentState: IShareData;
+}
+export interface ShareDataUpdatedEvent {
+    type: 'share-data:updated';
+    shareDataId: string;
+    currentState: IShareData;
+}
+export interface ShareDataRemovedEvent {
+    type: 'share-data:removed';
+    shareDataId: string;
+}
+export interface ShareDataTransactionEvent {
+    type: 'share-data:transaction';
+    shareDataId: string;
+    transactionId: string;
+    accepted: boolean;
+    currentState: IShareData;
+    transactionFunction: IShareFunction<any, (...args: any[]) => any, any>;
+}
+export type ShareDataManagerEvent = ShareDataAddedEvent | ShareDataUpdatedEvent | ShareDataRemovedEvent | ShareDataTransactionEvent;
+export type ShareDataManagerListener<E extends ShareDataManagerEvent = ShareDataManagerEvent> = (event: E) => void;
+//# sourceMappingURL=share-data-manager-events.d.ts.map

package/dist/manager/share-data-manager-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-data-manager-events.d.ts","sourceRoot":"","sources":["../../src/manager/share-data-manager-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,MAAM,yBAAyB,GAC/B,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,wBAAwB,CAAC;AAE/B,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,kBAAkB,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACtC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,UAAU,CAAC;IACzB,mBAAmB,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC;CAC1E;AAED,MAAM,MAAM,qBAAqB,GAC3B,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,yBAAyB,CAAC;AAEhC,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC"}

package/dist/manager/share-data-manager-events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/manager/share-data-manager.d.ts

@@ -0,0 +1,84 @@
+import { IShareData, IShareDataCryptoProof, IShareFunction, ShareDataCreationRecord } from '@degenerate/generic';
+import { ShareData } from '../share-data/share-data';
+import { ShareDataRepository } from '../persistence/share-data-repository';
+import { ShareDataManagerEventType, ShareDataManagerListener } from './share-data-manager-events';
+export declare class ShareDataManager {
+    private _shareDataObjects;
+    private _emitter;
+    private readonly _repository?;
+    private _persistence;
+    /**
+     * @param repository optional durable store. When supplied, blocks added
+     *   with a creation record are persisted and every subsequent mutation
+     *   writes through; call {@link hydrate} once at startup to reload them.
+     *   The no-arg form stays purely in-memory, so existing callers/tests are
+     *   untouched.
+     */
+    constructor(repository?: ShareDataRepository);
+    /**
+     * Loads every durably-stored block into memory, re-verifying each through
+     * the trust gate, and recovers its per-block persistence state so later
+     * transactions keep writing through. A no-op when no repository was
+     * supplied. Call once at startup, before serving traffic. Throws if a
+     * stored snapshot fails verification or collides with an already-registered
+     * id.
+     */
+    hydrate(): Promise<void>;
+    /**
+     * Registers a block and, when a {@link ShareDataCreationRecord} is supplied
+     * and a repository is configured, durably persists it. The record carries
+     * the two things a live block cannot reproduce on its own — the block type
+     * and the factory creation config — which the manager needs to keep
+     * re-serializing the block as transactions accrue. Without a record (or
+     * without a repository) the block is in-memory only.
+     *
+     * Persists before registering: a durable-write failure rejects and the
+     * block never enters the in-memory set, so memory and store cannot diverge.
+     */
+    addShareData(shareData: ShareData, creationRecord?: ShareDataCreationRecord): Promise<void>;
+    getShareDataById(id: string): ShareData | undefined;
+    updateShareData(shareData: ShareData): void;
+    /**
+     * Removes a block and, when it was persisted, deletes its durable snapshot
+     * first so a delete that cannot be recorded rejects before memory changes.
+     */
+    removeShareDataById(id: string): Promise<void>;
+    getShareData(): ShareData[];
+    getShareDataData(): IShareData[];
+    /**
+     * Returns the current state of the ShareData with the given id. Throws
+     * {@link ShareDataNotFoundError} when no ShareData is registered under
+     * that id — i.e., the return is never `undefined`. Callers that need a
+     * "lookup or null" shape should use {@link getShareDataById} instead.
+     */
+    getCurrentShareDataState(id: string): IShareData;
+    /**
+     * Proposes a transaction against the ShareData identified by `id`. The
+     * `proof` must cryptographically authorize moving the block to exactly
+     * `proposedData` via `transactionFunction` — it is verified by
+     * `ShareData.addTransaction` before the rule engine runs, so an unsigned or
+     * mis-signed proposal never reaches the rules or mutates state. `proof`
+     * is required precisely so nothing gets in without a signature: this is the
+     * canonical mutation entry point (the realtime propose handler routes
+     * here), and there is deliberately no unsigned variant on it.
+     *
+     * Once authorized, the proposal is judged by `startRuleEvaluation`;
+     * `_currentState` is replaced only if accepted. When the block is
+     * persisted, the appended transaction is written through before the event
+     * is emitted — a durable-write failure rejects rather than silently
+     * advancing only memory. Either way a transaction event is emitted with the
+     * outcome so observers can react.
+     *
+     * Library-internal callers that operate before the signing boundary (replay,
+     * seeding) use `ShareData.addTransactionNotValidated` directly; that path
+     * bypasses both the proof check and the emitter.
+     */
+    applyTransaction(id: string, proposedData: IShareData, transactionFunction: IShareFunction<any, (...args: any[]) => any, any>, proof: IShareDataCryptoProof): Promise<{
+        accepted: boolean;
+        transactionId: string;
+    }>;
+    on(type: ShareDataManagerEventType, listener: ShareDataManagerListener): void;
+    off(type: ShareDataManagerEventType, listener: ShareDataManagerListener): void;
+    private _emit;
+}
+//# sourceMappingURL=share-data-manager.d.ts.map

package/dist/manager/share-data-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-data-manager.d.ts","sourceRoot":"","sources":["../../src/manager/share-data-manager.ts"],"names":[],"mappings":"AACA,OAAO,EACH,UAAU,EACV,qBAAqB,EACrB,cAAc,EAGd,uBAAuB,EAG1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAEH,yBAAyB,EACzB,wBAAwB,EAC3B,MAAM,6BAA6B,CAAC;AAmBrC,qBAAa,gBAAgB;IACzB,OAAO,CAAC,iBAAiB,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAsB;IACnD,OAAO,CAAC,YAAY,CAAgC;IAEpD;;;;;;OAMG;gBACS,UAAU,CAAC,EAAE,mBAAmB;IAO5C;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B;;;;;;;;;;OAUG;IACG,YAAY,CACd,SAAS,EAAE,SAAS,EACpB,cAAc,CAAC,EAAE,uBAAuB,GACzC,OAAO,CAAC,IAAI,CAAC;IA+BhB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAInD,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAkB3C;;;OAGG;IACG,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpD,YAAY,IAAI,SAAS,EAAE;IAI3B,gBAAgB,IAAI,UAAU,EAAE;IAIhC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU;IAQhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,gBAAgB,CAClB,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,UAAU,EACxB,mBAAmB,EAAE,cAAc,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,GAAG,CAAC,EACtE,KAAK,EAAE,qBAAqB,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IAmDxD,EAAE,CAAC,IAAI,EAAE,yBAAyB,EAAE,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI7E,GAAG,CAAC,IAAI,EAAE,yBAAyB,EAAE,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI9E,OAAO,CAAC,KAAK;CAGhB"}

package/dist/manager/share-data-manager.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShareDataManager = void 0;
+const events_1 = require("events");
+const generic_1 = require("@degenerate/generic");
+const deserialize_share_data_1 = require("../persistence/deserialize-share-data");
+const serialize_share_data_1 = require("../persistence/serialize-share-data");
+class ShareDataManager {
+    /**
+     * @param repository optional durable store. When supplied, blocks added
+     *   with a creation record are persisted and every subsequent mutation
+     *   writes through; call {@link hydrate} once at startup to reload them.
+     *   The no-arg form stays purely in-memory, so existing callers/tests are
+     *   untouched.
+     */
+    constructor(repository) {
+        this._shareDataObjects = [];
+        this._emitter = new events_1.EventEmitter();
+        this._repository = repository;
+        this._persistence = new Map();
+    }
+    /**
+     * Loads every durably-stored block into memory, re-verifying each through
+     * the trust gate, and recovers its per-block persistence state so later
+     * transactions keep writing through. A no-op when no repository was
+     * supplied. Call once at startup, before serving traffic. Throws if a
+     * stored snapshot fails verification or collides with an already-registered
+     * id.
+     */
+    async hydrate() {
+        if (!this._repository) {
+            return;
+        }
+        const snapshots = await this._repository.loadAllSnapshots();
+        for (const snapshot of snapshots) {
+            // The trust gate: a tampered snapshot throws here rather than being
+            // loaded. The executable block and the recovered persistence state
+            // are rebuilt from the same bytes.
+            const block = (0, deserialize_share_data_1.deserializeShareData)(snapshot);
+            if (this.getShareDataById(block.id)) {
+                throw new generic_1.ShareDataAlreadyExistsError(block.id);
+            }
+            this._shareDataObjects.push(block);
+            this._persistence.set(block.id, {
+                blockType: snapshot.blockType,
+                creationConfig: snapshot.creationConfig,
+                transactionLog: [...snapshot.transactionLog],
+            });
+        }
+    }
+    /**
+     * Registers a block and, when a {@link ShareDataCreationRecord} is supplied
+     * and a repository is configured, durably persists it. The record carries
+     * the two things a live block cannot reproduce on its own — the block type
+     * and the factory creation config — which the manager needs to keep
+     * re-serializing the block as transactions accrue. Without a record (or
+     * without a repository) the block is in-memory only.
+     *
+     * Persists before registering: a durable-write failure rejects and the
+     * block never enters the in-memory set, so memory and store cannot diverge.
+     */
+    async addShareData(shareData, creationRecord) {
+        const existingShareData = this.getShareDataById(shareData.id);
+        if (existingShareData) {
+            throw new generic_1.ShareDataAlreadyExistsError(shareData.id);
+        }
+        if (this._repository && creationRecord) {
+            const persistence = {
+                blockType: creationRecord.blockType,
+                creationConfig: creationRecord.creationConfig,
+                transactionLog: [],
+            };
+            await this._repository.save((0, serialize_share_data_1.serializeShareData)(persistence.blockType, persistence.creationConfig, shareData, persistence.transactionLog));
+            this._persistence.set(shareData.id, persistence);
+        }
+        this._shareDataObjects.push(shareData);
+        this._emit({
+            type: 'share-data:added',
+            shareDataId: shareData.id,
+            currentState: shareData.currentState,
+        });
+    }
+    getShareDataById(id) {
+        return this._shareDataObjects.find((shareData) => shareData.id === id);
+    }
+    updateShareData(shareData) {
+        const existingShareData = this.getShareDataById(shareData.id);
+        if (!existingShareData) {
+            throw new generic_1.ShareDataNotFoundError(shareData.id);
+        }
+        this._shareDataObjects = this._shareDataObjects.map((sd) => {
+            if (sd.id === shareData.id) {
+                return shareData;
+            }
+            return sd;
+        });
+        this._emit({
+            type: 'share-data:updated',
+            shareDataId: shareData.id,
+            currentState: shareData.currentState,
+        });
+    }
+    /**
+     * Removes a block and, when it was persisted, deletes its durable snapshot
+     * first so a delete that cannot be recorded rejects before memory changes.
+     */
+    async removeShareDataById(id) {
+        const existingShareData = this.getShareDataById(id);
+        if (!existingShareData) {
+            throw new generic_1.ShareDataNotFoundError(id);
+        }
+        if (this._repository && this._persistence.has(id)) {
+            await this._repository.remove(id);
+        }
+        this._persistence.delete(id);
+        this._shareDataObjects = this._shareDataObjects.filter((shareData) => shareData.id !== id);
+        this._emit({
+            type: 'share-data:removed',
+            shareDataId: id,
+        });
+    }
+    getShareData() {
+        return this._shareDataObjects;
+    }
+    getShareDataData() {
+        return this._shareDataObjects.map((shareData) => shareData.currentState);
+    }
+    /**
+     * Returns the current state of the ShareData with the given id. Throws
+     * {@link ShareDataNotFoundError} when no ShareData is registered under
+     * that id — i.e., the return is never `undefined`. Callers that need a
+     * "lookup or null" shape should use {@link getShareDataById} instead.
+     */
+    getCurrentShareDataState(id) {
+        const shareData = this.getShareDataById(id);
+        if (!shareData) {
+            throw new generic_1.ShareDataNotFoundError(id);
+        }
+        return shareData.currentState;
+    }
+    /**
+     * Proposes a transaction against the ShareData identified by `id`. The
+     * `proof` must cryptographically authorize moving the block to exactly
+     * `proposedData` via `transactionFunction` — it is verified by
+     * `ShareData.addTransaction` before the rule engine runs, so an unsigned or
+     * mis-signed proposal never reaches the rules or mutates state. `proof`
+     * is required precisely so nothing gets in without a signature: this is the
+     * canonical mutation entry point (the realtime propose handler routes
+     * here), and there is deliberately no unsigned variant on it.
+     *
+     * Once authorized, the proposal is judged by `startRuleEvaluation`;
+     * `_currentState` is replaced only if accepted. When the block is
+     * persisted, the appended transaction is written through before the event
+     * is emitted — a durable-write failure rejects rather than silently
+     * advancing only memory. Either way a transaction event is emitted with the
+     * outcome so observers can react.
+     *
+     * Library-internal callers that operate before the signing boundary (replay,
+     * seeding) use `ShareData.addTransactionNotValidated` directly; that path
+     * bypasses both the proof check and the emitter.
+     */
+    async applyTransaction(id, proposedData, transactionFunction, proof) {
+        const shareData = this.getShareDataById(id);
+        if (!shareData) {
+            throw new generic_1.ShareDataNotFoundError(id);
+        }
+        const outcome = shareData.addTransaction(proposedData, transactionFunction, proof);
+        const persistence = this._persistence.get(id);
+        if (this._repository && persistence) {
+            if (transactionFunction.id === undefined) {
+                throw new generic_1.ShareDataPersistenceError(id, 'cannot persist a transaction for a function without an id');
+            }
+            // Read the just-appended history entry for the deterministic time
+            // and recorded outcome so a reload replays an identical hash chain.
+            const latest = shareData.transactionHistory[shareData.transactionHistory.length - 1];
+            const appended = {
+                functionId: transactionFunction.id,
+                proposedState: proposedData,
+                proof,
+                transactionTime: latest.transactionTime,
+                ruleOutcome: latest.ruleOutcome,
+            };
+            // Build the next log locally and only commit it after the durable
+            // write succeeds, so the manager's record never claims a
+            // transaction the store rejected.
+            const nextLog = [...persistence.transactionLog, appended];
+            await this._repository.save((0, serialize_share_data_1.serializeShareData)(persistence.blockType, persistence.creationConfig, shareData, nextLog));
+            persistence.transactionLog = nextLog;
+        }
+        this._emit({
+            type: 'share-data:transaction',
+            shareDataId: id,
+            transactionId: outcome.transactionId,
+            accepted: outcome.accepted,
+            currentState: shareData.currentState,
+            transactionFunction,
+        });
+        return outcome;
+    }
+    on(type, listener) {
+        this._emitter.on(type, listener);
+    }
+    off(type, listener) {
+        this._emitter.off(type, listener);
+    }
+    _emit(event) {
+        this._emitter.emit(event.type, event);
+    }
+}
+exports.ShareDataManager = ShareDataManager;

package/dist/persistence/block-factory-registry.d.ts

@@ -0,0 +1,51 @@
+import { IShareDataInitialCryptoData, PersistedCreationConfig, ShareBlockType, ShareDataProofs } from '@degenerate/generic';
+import { ShareData } from '../share-data/share-data';
+/**
+ * The inputs a block builder needs to replay construction of a persisted
+ * ShareData. These are exactly the fields a factory consumes once the
+ * `proofFor` callback is reconstructed from the stored proofs:
+ *
+ *   - `creationConfig` — the factory options minus `proofFor`
+ *     (`metadata`, `creationPublicKey`, `initialState`).
+ *   - `initialCrypto` — the client-computed creation crypto, applied to the
+ *     in-construction block on the first proof lookup.
+ *   - `structuralProofs` — the per-purpose proof bundle, replayed in place of
+ *     a live signer so the rebuilt block carries byte-identical proofs.
+ */
+export interface ShareBlockBuilderInput {
+    creationConfig: PersistedCreationConfig;
+    initialCrypto: IShareDataInitialCryptoData;
+    structuralProofs: ShareDataProofs;
+}
+/**
+ * Rebuilds a ShareData of a single block type from its persisted recipe.
+ * Implementations live in `@degenerate/shareblock` (one per
+ * {@link ShareBlockType}) and are wired in via
+ * {@link registerShareBlockBuilder}. A builder must replay the *same* factory
+ * the block was created with so the structural-proof chain re-verifies; it
+ * must not mutate or trust any `expected*` integrity values (those are
+ * cross-checked separately after replay).
+ */
+export type ShareBlockBuilder = (input: ShareBlockBuilderInput) => ShareData;
+/**
+ * Registers the builder used to rehydrate snapshots of a given block type.
+ * Idempotent-by-overwrite: re-registering replaces the prior builder, which
+ * keeps test setup and repeated module loads stable.
+ */
+export declare const registerShareBlockBuilder: (blockType: ShareBlockType, builder: ShareBlockBuilder) => void;
+/**
+ * Returns the registered builder for a block type, or `undefined` if none has
+ * been registered. The deserialize engine treats `undefined` as an
+ * unreconstructable snapshot and throws `ShareDataPersistenceError` with the
+ * offending id — resolution stays decoupled from error-with-id semantics.
+ */
+export declare const getShareBlockBuilder: (blockType: ShareBlockType) => ShareBlockBuilder | undefined;
+/** Whether a builder is registered for the given block type. */
+export declare const hasShareBlockBuilder: (blockType: ShareBlockType) => boolean;
+/**
+ * Clears all registered builders. Intended for test isolation so one suite's
+ * registrations do not leak into another; production code registers once at
+ * import time and never clears.
+ */
+export declare const clearShareBlockBuilders: () => void;
+//# sourceMappingURL=block-factory-registry.d.ts.map

package/dist/persistence/block-factory-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-factory-registry.d.ts","sourceRoot":"","sources":["../../src/persistence/block-factory-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,2BAA2B,EAC3B,uBAAuB,EACvB,cAAc,EACd,eAAe,EAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAgBrD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACnC,cAAc,EAAE,uBAAuB,CAAC;IACxC,aAAa,EAAE,2BAA2B,CAAC;IAC3C,gBAAgB,EAAE,eAAe,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,SAAS,CAAC;AAQ7E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAClC,WAAW,cAAc,EACzB,SAAS,iBAAiB,KAC3B,IAEF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC7B,WAAW,cAAc,KAC1B,iBAAiB,GAAG,SAAoC,CAAC;AAE5D,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,GAAI,WAAW,cAAc,KAAG,OACtC,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAO,IAE1C,CAAC"}

package/dist/persistence/block-factory-registry.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearShareBlockBuilders = exports.hasShareBlockBuilder = exports.getShareBlockBuilder = exports.registerShareBlockBuilder = void 0;
+//#endregion Builder contract
+//#region Registry
+const builders = new Map();
+/**
+ * Registers the builder used to rehydrate snapshots of a given block type.
+ * Idempotent-by-overwrite: re-registering replaces the prior builder, which
+ * keeps test setup and repeated module loads stable.
+ */
+const registerShareBlockBuilder = (blockType, builder) => {
+    builders.set(blockType, builder);
+};
+exports.registerShareBlockBuilder = registerShareBlockBuilder;
+/**
+ * Returns the registered builder for a block type, or `undefined` if none has
+ * been registered. The deserialize engine treats `undefined` as an
+ * unreconstructable snapshot and throws `ShareDataPersistenceError` with the
+ * offending id — resolution stays decoupled from error-with-id semantics.
+ */
+const getShareBlockBuilder = (blockType) => builders.get(blockType);
+exports.getShareBlockBuilder = getShareBlockBuilder;
+/** Whether a builder is registered for the given block type. */
+const hasShareBlockBuilder = (blockType) => builders.has(blockType);
+exports.hasShareBlockBuilder = hasShareBlockBuilder;
+/**
+ * Clears all registered builders. Intended for test isolation so one suite's
+ * registrations do not leak into another; production code registers once at
+ * import time and never clears.
+ */
+const clearShareBlockBuilders = () => {
+    builders.clear();
+};
+exports.clearShareBlockBuilders = clearShareBlockBuilders;
+//#endregion Registry

package/dist/persistence/deserialize-share-data.d.ts

@@ -0,0 +1,18 @@
+import { ShareData } from '../share-data/share-data';
+/**
+ * Replays a {@link PersistedShareData} snapshot back into a live, executable
+ * ShareData. The rebuilt block re-binds real function closures (via the
+ * registered builder for its block type), so it accepts new proposals just
+ * like a freshly-created block.
+ *
+ * Throws:
+ *   - {@link ShareDataPersistenceError} for an unsupported schema version, an
+ *     unregistered block type, or a transaction referencing an unknown
+ *     `functionId`.
+ *   - {@link ShareDataStructuralProofFailedError} (from the replayed factory)
+ *     if the structural-proof chain does not verify.
+ *   - {@link ShareDataIntegrityError} if the replayed block diverges from the
+ *     snapshot's `expected*` cross-checks.
+ */
+export declare const deserializeShareData: (snapshot: unknown) => ShareData;
+//# sourceMappingURL=deserialize-share-data.d.ts.map

package/dist/persistence/deserialize-share-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize-share-data.d.ts","sourceRoot":"","sources":["../../src/persistence/deserialize-share-data.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAYrD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,OAAO,KAAG,SAgHxD,CAAC"}