@degenerate/generic 0.4.0 → 0.7.0

package/dist/library/build-library.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendLibraryVersion = exports.addLibraryDelegate = exports.createLibraryEntity = void 0;
+const create_ed25519_signature_1 = require("../crypto/signature/create-ed25519-signature");
+const get_ed25519_public_key_from_private_key_1 = require("../crypto/private-public-keys/get-ed25519-public-key-from-private-key");
+const library_errors_1 = require("../errors/library/library-errors");
+const authorize_library_1 = require("./authorize-library");
+const library_hash_1 = require("./library-hash");
+const library_models_1 = require("./library-models");
+const library_proof_1 = require("./library-proof");
+const assertGasLimit = (gasLimit) => {
+    if (!Number.isInteger(gasLimit) || gasLimit < 1 || gasLimit > library_models_1.MAX_GAS_UNITS) {
+        throw new library_errors_1.LibraryEntityInvalidError(`gasLimit must be an integer in [1, ${library_models_1.MAX_GAS_UNITS}] (got ${gasLimit})`);
+    }
+};
+const signVersion = (kind, id, source, previousHash, createdAt, privateKey, publicKey) => {
+    const currentHash = (0, library_hash_1.computeVersionHash)(source, previousHash);
+    const payload = (0, library_proof_1.buildVersionProofPayload)({
+        id,
+        currentHash,
+        previousHash,
+        createdAt,
+        purpose: (0, library_proof_1.versionPurpose)(kind),
+        publicKey,
+    });
+    return {
+        createdAt,
+        previousHash,
+        source,
+        currentHash,
+        proof: { publicKey, signature: (0, create_ed25519_signature_1.createEd25519Signature)(privateKey, payload) },
+        proofType: library_models_1.LibraryProofType.CRYPTOGRAPHIC_SIGNATURE,
+    };
+};
+const signHead = (kind, id, head, privateKey, publicKey) => {
+    const payload = (0, library_proof_1.buildHeadProofPayload)({ id, head, purpose: (0, library_proof_1.headPurpose)(kind), publicKey });
+    return { currentHash: head, proof: { publicKey, signature: (0, create_ed25519_signature_1.createEd25519Signature)(privateKey, payload) } };
+};
+/**
+ * Creates a new library entity from its first version. The entity `id` is the
+ * first version's `currentHash` (content-addressed identity); the signing key
+ * becomes the entity owner.
+ */
+const createLibraryEntity = (args) => {
+    assertGasLimit(args.gasLimit);
+    const publicKey = (0, get_ed25519_public_key_from_private_key_1.getEd25519PublicKeyFromPrivateKey)(args.privateKey);
+    const createdAt = args.createdAt ?? Date.now();
+    // Identity is content-addressed: the first version's hash (seeded with an
+    // empty previousHash) IS the entity id. The hash does not depend on id, so
+    // it can be computed before signing the proof (which does bind id).
+    const previousHash = '';
+    const id = (0, library_hash_1.computeVersionHash)(args.source, previousHash);
+    const firstVersion = signVersion(args.kind, id, args.source, previousHash, createdAt, args.privateKey, publicKey);
+    return {
+        kind: args.kind,
+        id,
+        name: args.name,
+        description: args.description,
+        gasLimit: args.gasLimit,
+        owner: { publicKey },
+        delegations: [],
+        versions: [firstVersion],
+        head: signHead(args.kind, id, id, args.privateKey, publicKey),
+    };
+};
+exports.createLibraryEntity = createLibraryEntity;
+/**
+ * Grants `signerPublicKey` the right to append versions, signed by the owner.
+ * Returns a new entity (the input is not mutated). Rejects with
+ * {@link LibraryDelegationNotAuthorizedError} if the signing key is not the
+ * owner (which also blocks a delegate from re-delegating — a delegate's key is
+ * never the owner key) or if the grant targets the owner itself.
+ */
+const addLibraryDelegate = (entity, args) => {
+    const ownerPublicKey = (0, get_ed25519_public_key_from_private_key_1.getEd25519PublicKeyFromPrivateKey)(args.ownerPrivateKey);
+    if (ownerPublicKey !== entity.owner.publicKey) {
+        throw new library_errors_1.LibraryDelegationNotAuthorizedError(entity.id, ownerPublicKey, 'only the owner may delegate');
+    }
+    if (args.signerPublicKey === entity.owner.publicKey) {
+        throw new library_errors_1.LibraryDelegationNotAuthorizedError(entity.id, ownerPublicKey, 'the owner is already authorized');
+    }
+    const createdAt = args.createdAt ?? Date.now();
+    const payload = (0, library_proof_1.buildDelegationProofPayload)({
+        id: entity.id,
+        signerPublicKey: args.signerPublicKey,
+        purpose: (0, library_proof_1.delegatePurpose)(entity.kind),
+        publicKey: ownerPublicKey,
+    });
+    const delegation = {
+        signerPublicKey: args.signerPublicKey,
+        createdAt,
+        proof: { publicKey: ownerPublicKey, signature: (0, create_ed25519_signature_1.createEd25519Signature)(args.ownerPrivateKey, payload) },
+    };
+    return { ...entity, delegations: [...entity.delegations, delegation] };
+};
+exports.addLibraryDelegate = addLibraryDelegate;
+/**
+ * Appends a new signed version to an entity's ledger and returns a new entity
+ * (the input is not mutated). The new version chains to the prior tip via
+ * `previousHash`, and a fresh head proof is minted over the new tip.
+ *
+ * Gated: the signer must be the owner or a verified delegate
+ * ({@link isLibraryAuthorizedSigner}), else {@link LibraryVersionNotAuthorizedError}.
+ */
+const appendLibraryVersion = (entity, args) => {
+    const publicKey = (0, get_ed25519_public_key_from_private_key_1.getEd25519PublicKeyFromPrivateKey)(args.privateKey);
+    if (!(0, authorize_library_1.isLibraryAuthorizedSigner)(entity, publicKey)) {
+        throw new library_errors_1.LibraryVersionNotAuthorizedError(entity.id, publicKey);
+    }
+    const createdAt = args.createdAt ?? Date.now();
+    const previousHash = entity.versions[entity.versions.length - 1].currentHash;
+    const version = signVersion(entity.kind, entity.id, args.source, previousHash, createdAt, args.privateKey, publicKey);
+    return {
+        ...entity,
+        versions: [...entity.versions, version],
+        head: signHead(entity.kind, entity.id, version.currentHash, args.privateKey, publicKey),
+    };
+};
+exports.appendLibraryVersion = appendLibraryVersion;

package/dist/library/caching-library-store.d.ts

@@ -0,0 +1,19 @@
+import { LibraryStore } from './library-store';
+/**
+ * A read-through in-memory cache over a {@link LibraryStore} — the "resolve
+ * once, retain in memory" hydration cache. When a reference is resolved, the
+ * entity is fetched (and re-verified) from the underlying store once and kept;
+ * later resolutions of the same id are served from memory.
+ *
+ * Safe with no invalidation logic: library ids are content-addressed and a
+ * reference pins an immutable `currentHash`, and version ledgers are
+ * append-only — so a cached entity always still contains the pinned version. We
+ * cache the underlying store's already-verified entity and deep-clone on the way
+ * in and out, so a caller cannot corrupt the cache by mutating a returned
+ * object. Writes through this wrapper keep the cache coherent.
+ *
+ * It is itself a `LibraryStore`, so it is a drop-in anywhere a store is taken
+ * (`resolveLibraryReference`, `executeFunctionReference`, the apply path).
+ */
+export declare const createCachingLibraryStore: (store: LibraryStore) => LibraryStore;
+//# sourceMappingURL=caching-library-store.d.ts.map

package/dist/library/caching-library-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caching-library-store.d.ts","sourceRoot":"","sources":["../../src/library/caching-library-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAyC,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAItF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB,GAAI,OAAO,YAAY,KAAG,YAoC/D,CAAC"}

package/dist/library/caching-library-store.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCachingLibraryStore = void 0;
+const clone = (value) => JSON.parse(JSON.stringify(value));
+/**
+ * A read-through in-memory cache over a {@link LibraryStore} — the "resolve
+ * once, retain in memory" hydration cache. When a reference is resolved, the
+ * entity is fetched (and re-verified) from the underlying store once and kept;
+ * later resolutions of the same id are served from memory.
+ *
+ * Safe with no invalidation logic: library ids are content-addressed and a
+ * reference pins an immutable `currentHash`, and version ledgers are
+ * append-only — so a cached entity always still contains the pinned version. We
+ * cache the underlying store's already-verified entity and deep-clone on the way
+ * in and out, so a caller cannot corrupt the cache by mutating a returned
+ * object. Writes through this wrapper keep the cache coherent.
+ *
+ * It is itself a `LibraryStore`, so it is a drop-in anywhere a store is taken
+ * (`resolveLibraryReference`, `executeFunctionReference`, the apply path).
+ */
+const createCachingLibraryStore = (store) => {
+    const cache = new Map();
+    const get = async (id) => {
+        const cached = cache.get(id);
+        if (cached) {
+            return clone(cached);
+        }
+        const entity = await store.get(id); // underlying store re-verifies on read
+        if (entity) {
+            cache.set(id, clone(entity));
+            return clone(entity);
+        }
+        return undefined;
+    };
+    return {
+        get,
+        async getVersion(id, currentHash) {
+            const entity = await get(id);
+            return entity?.versions.find((version) => version.currentHash === currentHash);
+        },
+        async has(id) {
+            return cache.has(id) || store.has(id);
+        },
+        list: (filter) => store.list(filter),
+        search: (query) => store.search(query),
+        async save(entity) {
+            await store.save(entity);
+            cache.set(entity.id, clone(entity)); // keep the cache fresh after an append
+        },
+        async delete(id) {
+            await store.delete(id);
+            cache.delete(id);
+        },
+    };
+};
+exports.createCachingLibraryStore = createCachingLibraryStore;

package/dist/library/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Deterministic JSON serialization: object keys are sorted recursively so the
+ * same logical value always produces byte-identical output regardless of key
+ * insertion order. Array order is preserved (it is significant).
+ *
+ * This is the preimage builder for every library hash and signed payload. It is
+ * deliberately NOT raw string concatenation — concatenating `source +
+ * previousHash` is ambiguous (`"ab"+"c"` collides with `"a"+"bc"`), which a
+ * canonical JSON object avoids.
+ */
+export declare const canonicalJsonStringify: (value: unknown) => string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/library/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/library/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,MACpB,CAAC"}

package/dist/library/canonical-json.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalJsonStringify = void 0;
+/**
+ * Deterministic JSON serialization: object keys are sorted recursively so the
+ * same logical value always produces byte-identical output regardless of key
+ * insertion order. Array order is preserved (it is significant).
+ *
+ * This is the preimage builder for every library hash and signed payload. It is
+ * deliberately NOT raw string concatenation — concatenating `source +
+ * previousHash` is ambiguous (`"ab"+"c"` collides with `"a"+"bc"`), which a
+ * canonical JSON object avoids.
+ */
+const canonicalJsonStringify = (value) => JSON.stringify(sortValue(value));
+exports.canonicalJsonStringify = canonicalJsonStringify;
+const sortValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        return Object.keys(source)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortValue(source[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+};

package/dist/library/compile-rule-source.d.ts

@@ -0,0 +1,21 @@
+import { IShareRule } from '../models/rules/share-rule-models';
+/**
+ * Compiles a rule defined with the existing `@degenerate/rules` model into a
+ * SELF-CONTAINED predicate source — `({ current, proposed }) => boolean` — that
+ * runs in the bare sandbox (no `require`, no ambient `Date`/`Math.random`).
+ *
+ * The compiled source embeds the rule's conditions as data and inlines an
+ * interpreter that mirrors the engine's `evaluateRule` semantics exactly:
+ *   - a rule passes iff EVERY `currentDataConditions` holds against `current`
+ *     AND EVERY `proposedDataConditions` holds against `proposed`;
+ *   - if either condition array is empty the rule fails (matches the engine's
+ *     `currentResult/proposedResult` short-circuit);
+ *   - each condition resolves its dot-path property, evaluates by type, then
+ *     applies the IS/IS_NOT qualifier (booleans are special-cased: a non-boolean
+ *     value fails outright, before the qualifier).
+ *
+ * Faithfulness to the engine is verified by a cross-check test in
+ * `@degenerate/rules` (compiled verdict === `evaluateRule(...)`).
+ */
+export declare const compileRuleToSource: (rule: IShareRule) => string;
+//# sourceMappingURL=compile-rule-source.d.ts.map

package/dist/library/compile-rule-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile-rule-source.d.ts","sourceRoot":"","sources":["../../src/library/compile-rule-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,UAAU,KAAG,MAMtD,CAAC"}

package/dist/library/compile-rule-source.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileRuleToSource = void 0;
+/**
+ * Compiles a rule defined with the existing `@degenerate/rules` model into a
+ * SELF-CONTAINED predicate source — `({ current, proposed }) => boolean` — that
+ * runs in the bare sandbox (no `require`, no ambient `Date`/`Math.random`).
+ *
+ * The compiled source embeds the rule's conditions as data and inlines an
+ * interpreter that mirrors the engine's `evaluateRule` semantics exactly:
+ *   - a rule passes iff EVERY `currentDataConditions` holds against `current`
+ *     AND EVERY `proposedDataConditions` holds against `proposed`;
+ *   - if either condition array is empty the rule fails (matches the engine's
+ *     `currentResult/proposedResult` short-circuit);
+ *   - each condition resolves its dot-path property, evaluates by type, then
+ *     applies the IS/IS_NOT qualifier (booleans are special-cased: a non-boolean
+ *     value fails outright, before the qualifier).
+ *
+ * Faithfulness to the engine is verified by a cross-check test in
+ * `@degenerate/rules` (compiled verdict === `evaluateRule(...)`).
+ */
+const compileRuleToSource = (rule) => {
+    const data = JSON.stringify({
+        currentDataConditions: rule.currentDataConditions ?? [],
+        proposedDataConditions: rule.proposedDataConditions ?? [],
+    });
+    return `({ current, proposed }) => { var R = ${data}; ${INTERPRETER} }`;
+};
+exports.compileRuleToSource = compileRuleToSource;
+// The inlined interpreter. Kept as plain ES5-ish JS so it runs verbatim in the
+// sandbox. Mirrors packages/rules/src/evaluation/* condition logic.
+const INTERPRETER = `
+var get = function (o, path) {
+    return String(path).split('.').reduce(function (acc, key) {
+        return (acc && acc[key] !== undefined) ? acc[key] : undefined;
+    }, o);
+};
+var checkType = function (v, t) {
+    switch (t) {
+        case 'STRING': return typeof v === 'string';
+        case 'NUMBER': return typeof v === 'number';
+        case 'INTEGER': return Number.isInteger(v);
+        case 'BOOLEAN': return typeof v === 'boolean';
+        case 'OBJECT': return typeof v === 'object' && v !== null;
+        case 'ARRAY': return Array.isArray(v);
+        case 'NULL': return v === null;
+        case 'UNDEFINED': return typeof v === 'undefined';
+        case 'FUNCTION': return typeof v === 'function';
+        case 'BIGINT': return typeof v === 'bigint';
+        default: return false;
+    }
+};
+var evalCond = function (obj, c) {
+    var v = get(obj, c.targettedProperty);
+    var base;
+    switch (c.conditionType) {
+        case 'TYPEOF': base = checkType(v, c.conditionValue); break;
+        case 'EQUAL': base = v === c.conditionValue; break;
+        case 'GREATER_THAN': base = v > c.conditionValue; break;
+        case 'LESS_THAN': base = v < c.conditionValue; break;
+        case 'GREATER_THAN_OR_EQUAL': base = v >= c.conditionValue; break;
+        case 'LESS_THAN_OR_EQUAL': base = v <= c.conditionValue; break;
+        case 'CONTAINS':
+            base = (typeof c.conditionValue === 'string')
+                ? c.conditionValue.includes(v.toString())
+                : c.conditionValue.includes(v);
+            break;
+        case 'STARTS_WITH': base = v.toString().startsWith(c.conditionValue.toString()); break;
+        case 'ENDS_WITH': base = v.toString().endsWith(c.conditionValue.toString()); break;
+        case 'NULL': base = v === null; break;
+        case 'EMPTY':
+            base = Array.isArray(v) ? (v.length === 0) : (v === null || v === undefined || v === '');
+            break;
+        case 'PATTERN': base = new RegExp(c.conditionValue).test(v); break;
+        case 'TRUE':
+        case 'FALSE': {
+            if (typeof v !== 'boolean') { return false; }
+            var want = (c.conditionType === 'TRUE');
+            return c.conditionTypeQualifier === 'IS_NOT' ? (v !== want) : (v === want);
+        }
+        default: return false;
+    }
+    return c.conditionTypeQualifier === 'IS_NOT' ? !base : base;
+};
+if (R.currentDataConditions.length === 0 || R.proposedDataConditions.length === 0) {
+    return R.currentDataConditions.length !== 0 && R.proposedDataConditions.length !== 0;
+}
+var currentOk = R.currentDataConditions.every(function (c) { return evalCond(current, c); });
+var proposedOk = R.proposedDataConditions.every(function (c) { return evalCond(proposed, c); });
+return currentOk && proposedOk;
+`;

package/dist/library/evaluate-library-rules.d.ts

@@ -0,0 +1,36 @@
+import { IShareData } from '../models/share-data/share-data-models';
+import { RuleEvaluator } from '../sandbox/rule-evaluator';
+import { LibraryReference } from './library-reference';
+import { LibraryStore } from './library-store';
+/** Why a rule reference did not pass. `unresolved` = the rule could not be loaded/verified. */
+export type LibraryRuleFailureReason = 'rejected' | 'gas-exceeded' | 'threw' | 'invalid-output' | 'unresolved';
+export interface LibraryRuleReferenceResult {
+    reference: LibraryReference;
+    passed: boolean;
+    reason?: LibraryRuleFailureReason;
+    error?: string;
+}
+export interface LibraryRulesVerdict {
+    /** True only if every rule reference passed. Empty input passes (vacuously). */
+    passed: boolean;
+    results: LibraryRuleReferenceResult[];
+    /** The subset that did not pass (the diagnostics). */
+    failures: LibraryRuleReferenceResult[];
+}
+export interface EvaluateLibraryRuleReferencesOptions {
+    current: IShareData;
+    proposed: IShareData;
+    store: LibraryStore;
+    evaluator?: RuleEvaluator;
+}
+/**
+ * Resolves a set of rule references from the library and sandbox-evaluates each
+ * against the proposed transition, combining the verdicts: the set passes only
+ * if every rule passes. Per-reference diagnostics say which rule failed and why.
+ *
+ * Fail-closed: a rule that cannot be resolved/verified (a dangling or tampered
+ * reference) counts as a failure (`reason: 'unresolved'`), so a transition is
+ * never let through because a governing rule could not be loaded.
+ */
+export declare const evaluateLibraryRuleReferences: (references: LibraryReference[], options: EvaluateLibraryRuleReferencesOptions) => Promise<LibraryRulesVerdict>;
+//# sourceMappingURL=evaluate-library-rules.d.ts.map

package/dist/library/evaluate-library-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-library-rules.d.ts","sourceRoot":"","sources":["../../src/library/evaluate-library-rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAgC,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACxF,OAAO,EAAyB,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,+FAA+F;AAC/F,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,GAAG,gBAAgB,GAAG,YAAY,CAAC;AAE/G,MAAM,WAAW,0BAA0B;IACvC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAChC,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,0BAA0B,EAAE,CAAC;IACtC,sDAAsD;IACtD,QAAQ,EAAE,0BAA0B,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oCAAoC;IACjD,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACtC,YAAY,gBAAgB,EAAE,EAC9B,SAAS,oCAAoC,KAC9C,OAAO,CAAC,mBAAmB,CA8B7B,CAAC"}

package/dist/library/evaluate-library-rules.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateLibraryRuleReferences = void 0;
+const rule_evaluator_1 = require("../sandbox/rule-evaluator");
+const library_reference_1 = require("./library-reference");
+/**
+ * Resolves a set of rule references from the library and sandbox-evaluates each
+ * against the proposed transition, combining the verdicts: the set passes only
+ * if every rule passes. Per-reference diagnostics say which rule failed and why.
+ *
+ * Fail-closed: a rule that cannot be resolved/verified (a dangling or tampered
+ * reference) counts as a failure (`reason: 'unresolved'`), so a transition is
+ * never let through because a governing rule could not be loaded.
+ */
+const evaluateLibraryRuleReferences = async (references, options) => {
+    const evaluator = options.evaluator ?? (0, rule_evaluator_1.createInProcessRuleEvaluator)();
+    const results = [];
+    for (const reference of references) {
+        try {
+            const evaluation = await (0, library_reference_1.evaluateRuleReference)(reference, options.store, {
+                current: options.current,
+                proposed: options.proposed,
+                evaluator,
+            });
+            if (!evaluation.ok) {
+                results.push({ reference, passed: false, reason: evaluation.failure, error: evaluation.error });
+            }
+            else if (evaluation.passed !== true) {
+                results.push({ reference, passed: false, reason: 'rejected' });
+            }
+            else {
+                results.push({ reference, passed: true });
+            }
+        }
+        catch (err) {
+            results.push({
+                reference,
+                passed: false,
+                reason: 'unresolved',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const failures = results.filter((result) => !result.passed);
+    return { passed: failures.length === 0, results, failures };
+};
+exports.evaluateLibraryRuleReferences = evaluateLibraryRuleReferences;

package/dist/library/evaluate-library.d.ts

@@ -0,0 +1,34 @@
+import { RuleEvaluationResult, RuleEvaluator } from '../sandbox/rule-evaluator';
+import { FunctionExecutionResult, FunctionExecutor } from '../sandbox/sandbox-models';
+import { IShareData } from '../models/share-data/share-data-models';
+import { ILibraryEntity } from './library-models';
+export interface EvaluateLibraryFunctionOptions {
+    current: IShareData;
+    input: unknown;
+    /** Defaults to the entity's declared `gasLimit`. */
+    gasLimit?: number;
+    /** Evaluate a specific version; defaults to the head. */
+    versionHash?: string;
+    /** Defaults to a fresh in-process executor. */
+    executor?: FunctionExecutor;
+}
+/**
+ * Runs a library FUNCTION in isolation against sample `current` state + `input`,
+ * so a function can be tested independently of any ShareData. Verifies the
+ * entity first and rejects a non-function with {@link LibraryKindMismatchError}.
+ */
+export declare const evaluateLibraryFunction: (entity: ILibraryEntity, options: EvaluateLibraryFunctionOptions) => Promise<FunctionExecutionResult>;
+export interface EvaluateLibraryRuleOptions {
+    current: IShareData;
+    proposed: IShareData;
+    gasLimit?: number;
+    versionHash?: string;
+    evaluator?: RuleEvaluator;
+}
+/**
+ * Runs a library RULE in isolation against a sample `current` → `proposed`
+ * transition, so a rule can be tested independently. Verifies the entity first
+ * and rejects a non-rule with {@link LibraryKindMismatchError}.
+ */
+export declare const evaluateLibraryRule: (entity: ILibraryEntity, options: EvaluateLibraryRuleOptions) => Promise<RuleEvaluationResult>;
+//# sourceMappingURL=evaluate-library.d.ts.map

package/dist/library/evaluate-library.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-library.d.ts","sourceRoot":"","sources":["../../src/library/evaluate-library.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,oBAAoB,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC9G,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAGpE,OAAO,EAAE,cAAc,EAAsC,MAAM,kBAAkB,CAAC;AAkBtF,MAAM,WAAW,8BAA8B;IAC3C,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAChC,QAAQ,cAAc,EACtB,SAAS,8BAA8B,KACxC,OAAO,CAAC,uBAAuB,CAajC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC5B,QAAQ,cAAc,EACtB,SAAS,0BAA0B,KACpC,OAAO,CAAC,oBAAoB,CAgB9B,CAAC"}

package/dist/library/evaluate-library.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateLibraryRule = exports.evaluateLibraryFunction = void 0;
+const library_errors_1 = require("../errors/library/library-errors");
+const in_process_executor_1 = require("../sandbox/in-process-executor");
+const rule_evaluator_1 = require("../sandbox/rule-evaluator");
+const compile_rule_source_1 = require("./compile-rule-source");
+const library_models_1 = require("./library-models");
+const verify_library_1 = require("./verify-library");
+/**
+ * Resolves which version to evaluate: a specific `versionHash`, or the head
+ * (latest) when omitted. Throws if a requested version is not present.
+ */
+const resolveVersion = (entity, versionHash) => {
+    if (versionHash === undefined) {
+        return entity.versions[entity.versions.length - 1];
+    }
+    const version = entity.versions.find((candidate) => candidate.currentHash === versionHash);
+    if (!version) {
+        throw new library_errors_1.LibraryEntityInvalidError(`no version ${versionHash} on entity ${entity.id}`);
+    }
+    return version;
+};
+/**
+ * Runs a library FUNCTION in isolation against sample `current` state + `input`,
+ * so a function can be tested independently of any ShareData. Verifies the
+ * entity first and rejects a non-function with {@link LibraryKindMismatchError}.
+ */
+const evaluateLibraryFunction = async (entity, options) => {
+    (0, verify_library_1.verifyLibraryEntity)(entity);
+    if (entity.kind !== library_models_1.LibraryEntityKind.FUNCTION) {
+        throw new library_errors_1.LibraryKindMismatchError(entity.id, library_models_1.LibraryEntityKind.FUNCTION, entity.kind);
+    }
+    const version = resolveVersion(entity, options.versionHash);
+    const executor = options.executor ?? (0, in_process_executor_1.createInProcessFunctionExecutor)();
+    return executor.execute({
+        source: version.source,
+        current: options.current,
+        input: options.input,
+        gasLimit: options.gasLimit ?? entity.gasLimit,
+    });
+};
+exports.evaluateLibraryFunction = evaluateLibraryFunction;
+/**
+ * Runs a library RULE in isolation against a sample `current` → `proposed`
+ * transition, so a rule can be tested independently. Verifies the entity first
+ * and rejects a non-rule with {@link LibraryKindMismatchError}.
+ */
+const evaluateLibraryRule = async (entity, options) => {
+    (0, verify_library_1.verifyLibraryEntity)(entity);
+    if (entity.kind !== library_models_1.LibraryEntityKind.RULE) {
+        throw new library_errors_1.LibraryKindMismatchError(entity.id, library_models_1.LibraryEntityKind.RULE, entity.kind);
+    }
+    const version = resolveVersion(entity, options.versionHash);
+    const evaluator = options.evaluator ?? (0, rule_evaluator_1.createInProcessRuleEvaluator)();
+    // B1: a rule entity's source is the canonical rule DEFINITION; derive the
+    // sandbox predicate from it via the (faithfulness-proven) compiler.
+    const definition = JSON.parse(version.source);
+    return evaluator.evaluate({
+        source: (0, compile_rule_source_1.compileRuleToSource)(definition),
+        current: options.current,
+        proposed: options.proposed,
+        gasLimit: options.gasLimit ?? entity.gasLimit,
+    });
+};
+exports.evaluateLibraryRule = evaluateLibraryRule;

package/dist/library/in-memory-library-store.d.ts

@@ -0,0 +1,22 @@
+import { ILibraryEntity, ILibraryVersion } from './library-models';
+import { LibraryListFilter, LibrarySearchQuery, LibraryStore } from './library-store';
+/**
+ * In-memory {@link LibraryStore}. Deep-copies on the way in and out so callers
+ * cannot mutate stored state by reference, and re-verifies on every read.
+ *
+ * The optional `seed` models data already present in a backend: it is stored
+ * WITHOUT verification, precisely so that the re-verify-on-read contract is what
+ * catches a tampered backing record.
+ */
+export declare class InMemoryLibraryStore implements LibraryStore {
+    private readonly entities;
+    constructor(seed?: ILibraryEntity[]);
+    get(id: string): Promise<ILibraryEntity | undefined>;
+    getVersion(id: string, currentHash: string): Promise<ILibraryVersion | undefined>;
+    has(id: string): Promise<boolean>;
+    list(filter?: LibraryListFilter): Promise<ILibraryEntity[]>;
+    search(query: LibrarySearchQuery): Promise<ILibraryEntity[]>;
+    save(entity: ILibraryEntity): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+//# sourceMappingURL=in-memory-library-store.d.ts.map

package/dist/library/in-memory-library-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-library-store.d.ts","sourceRoot":"","sources":["../../src/library/in-memory-library-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAqBtF;;;;;;;GAOG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;gBAElD,IAAI,GAAE,cAAc,EAAO;IAMjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IASpD,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAKjF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjC,IAAI,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAI3D,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmB5D,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG1C"}