@proposit/proposit-core 0.8.9

package/dist/lib/core/argument-engine.js

@@ -0,0 +1,1294 @@
+import { isClaimBound, isPremiseBound, } from "../schemata/index.js";
+import { DEFAULT_GRAMMAR_CONFIG, PERMISSIVE_GRAMMAR_CONFIG, } from "../types/grammar.js";
+import { DEFAULT_CHECKSUM_CONFIG, normalizeChecksumConfig, serializeChecksumConfig, } from "../consts.js";
+import { ChangeCollector } from "./change-collector.js";
+import { canonicalSerialize, computeHash, entityChecksum } from "./checksum.js";
+import { evaluateArgument as evaluateArgumentStandalone, checkArgumentValidity as checkArgumentValidityStandalone, } from "./evaluation/argument-evaluation.js";
+import { validateArgument as validateArgumentStandalone, validateArgumentAfterPremiseMutation as validateAfterPremiseMutationStandalone, validateArgumentEvaluability as validateArgumentEvaluabilityStandalone, collectArgumentReferencedVariables as collectArgumentReferencedVariablesStandalone, } from "./argument-validation.js";
+import { InvariantViolationError } from "./invariant-violation-error.js";
+import { PremiseEngine } from "./premise-engine.js";
+import { VariableManager } from "./variable-manager.js";
+/** Default ID generator using the Web Crypto API (Node.js 20+, all modern browsers). */
+export const defaultGenerateId = () => globalThis.crypto.randomUUID();
+/**
+ * Manages a propositional logic argument composed of premises, variable
+ * assignments, and logical roles (supporting premises and a conclusion).
+ *
+ * Provides premise CRUD, role management, evaluation of individual
+ * assignments, and exhaustive validity checking via truth-table enumeration.
+ */
+export class ArgumentEngine {
+    argument;
+    premises;
+    variables;
+    claimLibrary;
+    sourceLibrary;
+    claimSourceLibrary;
+    conclusionPremiseId;
+    checksumConfig;
+    positionConfig;
+    grammarConfig;
+    generateId;
+    restoringFromSnapshot = false;
+    checksumDirty = true;
+    cachedMetaChecksum;
+    cachedDescendantChecksum;
+    cachedCombinedChecksum;
+    cachedPremisesCollectionChecksum;
+    cachedVariablesCollectionChecksum;
+    expressionIndex;
+    listeners = new Set();
+    reactiveDirty = {
+        argument: true,
+        variables: true,
+        roles: true,
+        premiseIds: new Set(),
+        allPremises: true,
+    };
+    cachedReactiveSnapshot;
+    constructor(argument, claimLibrary, sourceLibrary, claimSourceLibrary, options) {
+        this.argument = { ...argument };
+        this.claimLibrary = claimLibrary;
+        this.sourceLibrary = sourceLibrary;
+        this.claimSourceLibrary = claimSourceLibrary;
+        this.premises = new Map();
+        this.checksumConfig = options?.checksumConfig;
+        this.positionConfig = options?.positionConfig;
+        this.grammarConfig = options?.grammarConfig;
+        this.generateId = options?.generateId ?? defaultGenerateId;
+        this.variables = new VariableManager({
+            checksumConfig: this.checksumConfig,
+            positionConfig: this.positionConfig,
+            generateId: this.generateId,
+        });
+        this.expressionIndex = new Map();
+        this.conclusionPremiseId = undefined;
+    }
+    createCircularityCheck() {
+        return (variableId, targetPremiseId) => {
+            return this.wouldCreateCycle(variableId, targetPremiseId, new Set());
+        };
+    }
+    wouldCreateCycle(variableId, targetPremiseId, visited) {
+        const variable = this.variables.getVariable(variableId);
+        if (!variable)
+            return false;
+        if (!isPremiseBound(variable))
+            return false;
+        const bound = variable;
+        if (bound.boundPremiseId === targetPremiseId)
+            return true;
+        if (visited.size >= this.premises.size) {
+            throw new Error(`Circularity check depth limit exceeded (visited ${visited.size} premises).`);
+        }
+        if (visited.has(bound.boundPremiseId))
+            return false;
+        visited.add(bound.boundPremiseId);
+        const boundPremise = this.premises.get(bound.boundPremiseId);
+        if (!boundPremise)
+            return false;
+        for (const expr of boundPremise.getExpressions()) {
+            if (expr.type === "variable") {
+                if (this.wouldCreateCycle(expr.variableId, targetPremiseId, visited)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    wireCircularityCheck(pm) {
+        pm.setCircularityCheck(this.createCircularityCheck());
+    }
+    wireEmptyBoundPremiseCheck(pm) {
+        pm.setEmptyBoundPremiseCheck((variableId) => {
+            const v = this.variables.getVariable(variableId);
+            if (!v ||
+                !isPremiseBound(v))
+                return false;
+            const boundPremise = this.premises.get(v.boundPremiseId);
+            return !boundPremise?.getRootExpressionId();
+        });
+    }
+    generateUniqueSymbol() {
+        let n = this.premises.size - 1;
+        let candidate = `P${n}`;
+        while (this.variables.getVariableBySymbol(candidate) !== undefined) {
+            n++;
+            candidate = `P${n}`;
+        }
+        return candidate;
+    }
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    notifySubscribers() {
+        for (const listener of this.listeners) {
+            listener();
+        }
+    }
+    finalizeChanges(collector) {
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return changes;
+    }
+    static skipValidationResult = {
+        ok: true,
+        violations: [],
+    };
+    suppressPremiseValidation() {
+        for (const pe of this.premises.values()) {
+            pe.setArgumentValidateCallback(() => ArgumentEngine.skipValidationResult);
+        }
+    }
+    restorePremiseValidation() {
+        for (const pe of this.premises.values()) {
+            pe.setArgumentValidateCallback(() => this.validateAfterPremiseMutation());
+        }
+    }
+    withValidation(fn) {
+        if (this.restoringFromSnapshot) {
+            return fn();
+        }
+        const snap = this.snapshot();
+        // Suppress PremiseEngine-level validation during ArgumentEngine
+        // mutations. The ArgumentEngine will do its own validation at the end.
+        this.suppressPremiseValidation();
+        try {
+            const result = fn();
+            const validation = this.validate();
+            if (!validation.ok) {
+                this.rollbackInternal(snap);
+                throw new InvariantViolationError(validation.violations);
+            }
+            return result;
+        }
+        catch (e) {
+            if (!(e instanceof InvariantViolationError)) {
+                this.rollbackInternal(snap);
+            }
+            throw e;
+        }
+        finally {
+            this.restorePremiseValidation();
+        }
+    }
+    getSnapshot = () => {
+        return this.buildReactiveSnapshot();
+    };
+    buildReactiveSnapshot() {
+        const dirty = this.reactiveDirty;
+        const prev = this.cachedReactiveSnapshot;
+        if (prev &&
+            !dirty.argument &&
+            !dirty.variables &&
+            !dirty.roles &&
+            dirty.premiseIds.size === 0 &&
+            !dirty.allPremises) {
+            return prev;
+        }
+        const argument = dirty.argument || !prev ? this.getArgument() : prev.argument;
+        const variables = dirty.variables || !prev
+            ? this.buildVariablesRecord()
+            : prev.variables;
+        const roles = dirty.roles || !prev ? { ...this.getRoleState() } : prev.roles;
+        let premises;
+        if (dirty.allPremises || !prev) {
+            premises = this.buildAllPremisesRecord();
+        }
+        else {
+            premises = { ...prev.premises };
+            // Remove premises that no longer exist
+            for (const id of Object.keys(premises)) {
+                if (!this.premises.has(id)) {
+                    delete premises[id];
+                }
+            }
+            // Rebuild dirty premises
+            for (const id of dirty.premiseIds) {
+                const pm = this.premises.get(id);
+                if (pm) {
+                    premises[id] = this.buildPremiseRecord(pm);
+                }
+                else {
+                    delete premises[id];
+                }
+            }
+            // Add any new premises not yet in snapshot
+            for (const [id, pm] of this.premises) {
+                if (!(id in premises)) {
+                    premises[id] = this.buildPremiseRecord(pm);
+                }
+            }
+        }
+        const snapshot = {
+            argument,
+            variables,
+            premises,
+            roles,
+        };
+        this.cachedReactiveSnapshot = snapshot;
+        this.reactiveDirty = {
+            argument: false,
+            variables: false,
+            roles: false,
+            premiseIds: new Set(),
+            allPremises: false,
+        };
+        return snapshot;
+    }
+    buildVariablesRecord() {
+        const result = {};
+        for (const v of this.variables.toArray()) {
+            result[v.id] = v;
+        }
+        return result;
+    }
+    buildAllPremisesRecord() {
+        const result = {};
+        for (const [id, pm] of this.premises) {
+            result[id] = this.buildPremiseRecord(pm);
+        }
+        return result;
+    }
+    buildPremiseRecord(pm) {
+        const expressions = {};
+        for (const expr of pm.getExpressions()) {
+            expressions[expr.id] = expr;
+        }
+        return {
+            premise: pm.toPremiseData(),
+            expressions,
+            rootExpressionId: pm.getRootExpressionId(),
+        };
+    }
+    markReactiveDirty(changes) {
+        if (changes.argument) {
+            this.reactiveDirty.argument = true;
+        }
+        if (changes.variables) {
+            this.reactiveDirty.variables = true;
+        }
+        if (changes.roles) {
+            this.reactiveDirty.roles = true;
+        }
+        if (changes.expressions) {
+            const allExprs = [
+                ...changes.expressions.added,
+                ...changes.expressions.modified,
+                ...changes.expressions.removed,
+            ];
+            for (const expr of allExprs) {
+                this.reactiveDirty.premiseIds.add(expr.premiseId);
+            }
+        }
+        if (changes.premises) {
+            for (const p of [
+                ...changes.premises.added,
+                ...changes.premises.modified,
+                ...changes.premises.removed,
+            ]) {
+                this.reactiveDirty.premiseIds.add(p.id);
+            }
+        }
+    }
+    getArgument() {
+        this.flushChecksums();
+        return {
+            ...this.argument,
+            checksum: this.cachedMetaChecksum,
+            descendantChecksum: this.cachedDescendantChecksum,
+            combinedChecksum: this.cachedCombinedChecksum,
+        };
+    }
+    toDisplayString() {
+        const lines = [];
+        const arg = this.getArgument();
+        lines.push(`Argument: ${arg.id} (v${arg.version})`);
+        lines.push("");
+        const supportingIds = new Set(this.listSupportingPremises().map((pe) => pe.getId()));
+        for (const pe of this.listPremises()) {
+            let role;
+            if (pe.getId() === this.conclusionPremiseId) {
+                role = "Conclusion";
+            }
+            else if (supportingIds.has(pe.getId())) {
+                role = "Supporting";
+            }
+            else {
+                role = "Constraint";
+            }
+            const display = pe.toDisplayString() || "(empty)";
+            lines.push(`[${role}] ${display}`);
+        }
+        return lines.join("\n");
+    }
+    createPremise(extras, symbol) {
+        return this.createPremiseWithId(this.generateId(), extras, symbol);
+    }
+    createPremiseWithId(id, extras, symbol) {
+        return this.withValidation(() => {
+            if (this.premises.has(id)) {
+                throw new Error(`Premise "${id}" already exists.`);
+            }
+            const premiseData = {
+                ...extras,
+                id,
+                argumentId: this.argument.id,
+                argumentVersion: this.argument.version,
+            };
+            const pm = new PremiseEngine(premiseData, {
+                argument: this.argument,
+                variables: this.variables,
+                expressionIndex: this.expressionIndex,
+            }, {
+                checksumConfig: this.checksumConfig,
+                positionConfig: this.positionConfig,
+                grammarConfig: this.grammarConfig,
+                generateId: this.generateId,
+            });
+            this.premises.set(id, pm);
+            this.wireCircularityCheck(pm);
+            this.wireEmptyBoundPremiseCheck(pm);
+            pm.setVariableIdsCallback(() => new Set(this.variables.toArray().map((v) => v.id)));
+            pm.setArgumentValidateCallback(() => this.validateAfterPremiseMutation());
+            pm.setOnMutate(() => {
+                this.markDirty();
+                this.reactiveDirty.premiseIds.add(id);
+                this.notifySubscribers();
+            });
+            const collector = new ChangeCollector();
+            collector.addedPremise(pm.toPremiseData());
+            this.markDirty();
+            if (this.conclusionPremiseId === undefined) {
+                this.conclusionPremiseId = id;
+                collector.setRoles(this.getRoleState());
+            }
+            // Auto-create a premise-bound variable for this premise
+            if (!this.restoringFromSnapshot) {
+                const autoSymbol = symbol ?? this.generateUniqueSymbol();
+                const autoVariable = {
+                    id: this.generateId(),
+                    argumentId: this.argument.id,
+                    argumentVersion: this.argument.version,
+                    symbol: autoSymbol,
+                    boundPremiseId: id,
+                    boundArgumentId: this.argument.id,
+                    boundArgumentVersion: this.argument.version,
+                };
+                const withChecksum = this.attachVariableChecksum({
+                    ...autoVariable,
+                });
+                this.variables.addVariable(withChecksum);
+                collector.addedVariable(withChecksum);
+                this.markAllPremisesDirty();
+            }
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: pm,
+                changes,
+            };
+        });
+    }
+    removePremise(premiseId) {
+        return this.withValidation(() => {
+            const pm = this.premises.get(premiseId);
+            if (!pm)
+                return { result: undefined, changes: {} };
+            const data = pm.toPremiseData();
+            const collector = new ChangeCollector();
+            // Clean up expression index for removed premise's expressions
+            for (const expr of pm.getExpressions()) {
+                this.expressionIndex.delete(expr.id);
+            }
+            this.premises.delete(premiseId);
+            collector.removedPremise(data);
+            if (this.conclusionPremiseId === premiseId) {
+                this.conclusionPremiseId = undefined;
+                collector.setRoles(this.getRoleState());
+            }
+            // Cascade: remove variables bound to the deleted premise
+            const boundVars = this.getVariablesBoundToPremise(premiseId);
+            for (const v of boundVars) {
+                const removeResult = this.removeVariableCore(v.id);
+                if (removeResult.changes.variables) {
+                    for (const rv of removeResult.changes.variables.removed) {
+                        collector.removedVariable(rv);
+                    }
+                }
+                if (removeResult.changes.expressions) {
+                    for (const re of removeResult.changes.expressions.removed) {
+                        collector.removedExpression(re);
+                    }
+                }
+            }
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: data,
+                changes,
+            };
+        });
+    }
+    getPremise(premiseId) {
+        return this.premises.get(premiseId);
+    }
+    hasPremise(premiseId) {
+        return this.premises.has(premiseId);
+    }
+    listPremiseIds() {
+        return Array.from(this.premises.keys()).sort((a, b) => a.localeCompare(b));
+    }
+    listPremises() {
+        return this.listPremiseIds()
+            .map((id) => this.premises.get(id))
+            .filter((pm) => pm !== undefined);
+    }
+    addVariable(variable) {
+        return this.withValidation(() => {
+            // Only claim-bound variables may be added via addVariable.
+            // Premise-bound variables must use bindVariableToPremise.
+            if (!isClaimBound(variable)) {
+                throw new Error("addVariable only accepts claim-bound variables. Use bindVariableToPremise for premise-bound variables.");
+            }
+            if (variable.argumentId !== this.argument.id) {
+                throw new Error(`Variable argumentId "${variable.argumentId}" does not match engine argument ID "${this.argument.id}".`);
+            }
+            if (variable.argumentVersion !== this.argument.version) {
+                throw new Error(`Variable argumentVersion "${variable.argumentVersion}" does not match engine argument version "${this.argument.version}".`);
+            }
+            // Validate claim reference
+            if (!this.claimLibrary.get(variable.claimId, variable.claimVersion)) {
+                throw new Error(`Claim "${variable.claimId}" version ${variable.claimVersion} does not exist in the claim library.`);
+            }
+            const withChecksum = this.attachVariableChecksum({
+                ...variable,
+            });
+            this.variables.addVariable(withChecksum);
+            const collector = new ChangeCollector();
+            collector.addedVariable(withChecksum);
+            this.markAllPremisesDirty();
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: withChecksum,
+                changes,
+            };
+        });
+    }
+    bindVariableToPremise(variable) {
+        return this.withValidation(() => {
+            if (variable.argumentId !== this.argument.id) {
+                throw new Error(`Variable argumentId "${variable.argumentId}" does not match engine argument ID "${this.argument.id}".`);
+            }
+            if (variable.argumentVersion !== this.argument.version) {
+                throw new Error(`Variable argumentVersion "${variable.argumentVersion}" does not match engine argument version "${this.argument.version}".`);
+            }
+            if (variable.boundArgumentId !== this.argument.id) {
+                throw new Error(`Cross-argument bindings are not supported. boundArgumentId "${variable.boundArgumentId}" does not match engine argument ID "${this.argument.id}".`);
+            }
+            if (!this.premises.has(variable.boundPremiseId)) {
+                throw new Error(`Bound premise "${variable.boundPremiseId}" does not exist in this argument.`);
+            }
+            const withChecksum = this.attachVariableChecksum({
+                ...variable,
+            });
+            this.variables.addVariable(withChecksum);
+            const collector = new ChangeCollector();
+            collector.addedVariable(withChecksum);
+            this.markAllPremisesDirty();
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: withChecksum,
+                changes,
+            };
+        });
+    }
+    /** Adds a premise-bound variable that references a premise in a different argument. */
+    bindVariableToExternalPremise(variable) {
+        return this.withValidation(() => {
+            if (variable.argumentId !== this.argument.id) {
+                throw new Error(`Variable argumentId "${variable.argumentId}" does not match engine argument ID "${this.argument.id}".`);
+            }
+            if (variable.argumentVersion !== this.argument.version) {
+                throw new Error(`Variable argumentVersion "${variable.argumentVersion}" does not match engine argument version "${this.argument.version}".`);
+            }
+            if (variable.boundArgumentId === this.argument.id) {
+                throw new Error(`boundArgumentId matches this engine's argument — use bindVariableToPremise for internal bindings.`);
+            }
+            if (!this.canBind(variable.boundArgumentId, variable.boundArgumentVersion)) {
+                throw new Error(`Binding to argument "${variable.boundArgumentId}" version ${variable.boundArgumentVersion} is not allowed.`);
+            }
+            const withChecksum = this.attachVariableChecksum({
+                ...variable,
+            });
+            this.variables.addVariable(withChecksum);
+            const collector = new ChangeCollector();
+            collector.addedVariable(withChecksum);
+            this.markAllPremisesDirty();
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: withChecksum,
+                changes,
+            };
+        });
+    }
+    /** Adds a premise-bound variable that references another argument's conclusion premise. */
+    bindVariableToArgument(variable, conclusionPremiseId) {
+        return this.bindVariableToExternalPremise({
+            ...variable,
+            boundPremiseId: conclusionPremiseId,
+        });
+    }
+    updateVariable(variableId, updates) {
+        return this.withValidation(() => {
+            const existing = this.variables.getVariable(variableId);
+            if (!existing) {
+                return { result: undefined, changes: {} };
+            }
+            const existingVar = existing;
+            const updatesObj = updates;
+            // Reject binding-type conversion
+            if (isClaimBound(existingVar)) {
+                const premiseBoundFields = [
+                    "boundPremiseId",
+                    "boundArgumentId",
+                    "boundArgumentVersion",
+                ];
+                for (const f of premiseBoundFields) {
+                    if (updatesObj[f] !== undefined) {
+                        throw new Error(`Cannot set "${f}" on a claim-bound variable. Delete and re-create to change binding type.`);
+                    }
+                }
+                // Validate: claimId and claimVersion must be provided together
+                const hasClaimId = updatesObj.claimId !== undefined;
+                const hasClaimVersion = updatesObj.claimVersion !== undefined;
+                if (hasClaimId !== hasClaimVersion) {
+                    throw new Error("claimId and claimVersion must be provided together.");
+                }
+                // Validate claim reference if provided
+                if (hasClaimId && hasClaimVersion) {
+                    if (!this.claimLibrary.get(updatesObj.claimId, updatesObj.claimVersion)) {
+                        throw new Error(`Claim "${String(updatesObj.claimId)}" version ${String(updatesObj.claimVersion)} does not exist in the claim library.`);
+                    }
+                }
+            }
+            else if (isPremiseBound(existingVar)) {
+                const claimBoundFields = ["claimId", "claimVersion"];
+                for (const f of claimBoundFields) {
+                    if (updatesObj[f] !== undefined) {
+                        throw new Error(`Cannot set "${f}" on a premise-bound variable. Delete and re-create to change binding type.`);
+                    }
+                }
+                // Validate boundPremiseId if provided
+                if (updatesObj.boundPremiseId !== undefined) {
+                    const newPremiseId = updatesObj.boundPremiseId;
+                    if (!this.premises.has(newPremiseId)) {
+                        throw new Error(`Bound premise "${newPremiseId}" does not exist in this argument.`);
+                    }
+                }
+            }
+            const updated = this.variables.updateVariable(variableId, updates);
+            const collector = new ChangeCollector();
+            if (updated) {
+                const withChecksum = this.attachVariableChecksum({
+                    ...updated,
+                });
+                // Re-store with updated checksum so VariableManager always holds
+                // variables with correct checksums.
+                this.variables.removeVariable(variableId);
+                this.variables.addVariable(withChecksum);
+                collector.modifiedVariable(withChecksum);
+                this.markAllPremisesDirty();
+                const changes = this.finalizeChanges(collector);
+                return {
+                    result: withChecksum,
+                    changes,
+                };
+            }
+            return {
+                result: undefined,
+                changes: collector.toChangeset(),
+            };
+        });
+    }
+    removeVariableCore(variableId) {
+        const variable = this.variables.getVariable(variableId);
+        if (!variable) {
+            return { result: undefined, changes: {} };
+        }
+        const collector = new ChangeCollector();
+        // Cascade: delete referencing expressions in every premise
+        for (const pm of this.listPremises()) {
+            const { changes } = pm.deleteExpressionsUsingVariable(variableId);
+            if (changes.expressions) {
+                for (const e of changes.expressions.removed) {
+                    collector.removedExpression(e);
+                }
+            }
+        }
+        this.variables.removeVariable(variableId);
+        collector.removedVariable(variable);
+        this.markAllPremisesDirty();
+        const changes = this.finalizeChanges(collector);
+        return {
+            result: variable,
+            changes,
+        };
+    }
+    removeVariable(variableId) {
+        return this.withValidation(() => {
+            return this.removeVariableCore(variableId);
+        });
+    }
+    getVariables() {
+        return this.variables.toArray();
+    }
+    getVariable(variableId) {
+        return this.variables.getVariable(variableId);
+    }
+    hasVariable(variableId) {
+        return this.variables.hasVariable(variableId);
+    }
+    getVariableBySymbol(symbol) {
+        return this.variables.getVariableBySymbol(symbol);
+    }
+    buildVariableIndex(keyFn) {
+        const map = new Map();
+        for (const v of this.variables.toArray()) {
+            map.set(keyFn(v), v);
+        }
+        return map;
+    }
+    getVariablesBoundToPremise(premiseId) {
+        return this.variables.toArray().filter((v) => {
+            const base = v;
+            return isPremiseBound(base) && base.boundPremiseId === premiseId;
+        });
+    }
+    getExpression(expressionId) {
+        const premiseId = this.expressionIndex.get(expressionId);
+        if (premiseId === undefined)
+            return undefined;
+        return this.premises.get(premiseId)?.getExpression(expressionId);
+    }
+    hasExpression(expressionId) {
+        return this.expressionIndex.has(expressionId);
+    }
+    getExpressionPremiseId(expressionId) {
+        return this.expressionIndex.get(expressionId);
+    }
+    findPremiseByExpressionId(expressionId) {
+        const premiseId = this.expressionIndex.get(expressionId);
+        if (premiseId === undefined)
+            return undefined;
+        return this.premises.get(premiseId);
+    }
+    getAllExpressions() {
+        const all = [];
+        for (const pe of this.listPremises()) {
+            all.push(...pe.getExpressions());
+        }
+        return all.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    getExpressionsByVariableId(variableId) {
+        const result = [];
+        for (const pe of this.listPremises()) {
+            const refIds = pe.getReferencedVariableIds();
+            if (!refIds.has(variableId))
+                continue;
+            for (const expr of pe.getExpressions()) {
+                if (expr.type === "variable" &&
+                    expr.variableId === variableId) {
+                    result.push(expr);
+                }
+            }
+        }
+        return result;
+    }
+    listRootExpressions() {
+        const roots = [];
+        for (const pe of this.listPremises()) {
+            const root = pe.getRootExpression();
+            if (root)
+                roots.push(root);
+        }
+        return roots;
+    }
+    /**
+     * Normalizes expression trees across all premises. Collapses unjustified
+     * formulas, operators with 0/1 children, and inserts formula buffers where
+     * needed. Works regardless of `autoNormalize` setting.
+     */
+    normalizeAllExpressions() {
+        const merged = {};
+        for (const pe of this.premises.values()) {
+            const { changes } = pe.normalizeExpressions();
+            if (changes.expressions) {
+                merged.expressions ??= { added: [], modified: [], removed: [] };
+                merged.expressions.added.push(...changes.expressions.added);
+                merged.expressions.modified.push(...changes.expressions.modified);
+                merged.expressions.removed.push(...changes.expressions.removed);
+            }
+            if (changes.premises) {
+                merged.premises ??= { added: [], modified: [], removed: [] };
+                merged.premises.modified.push(...changes.premises.modified);
+            }
+        }
+        return { result: undefined, changes: merged };
+    }
+    getRoleState() {
+        return {
+            ...(this.conclusionPremiseId !== undefined
+                ? { conclusionPremiseId: this.conclusionPremiseId }
+                : {}),
+        };
+    }
+    setConclusionPremise(premiseId) {
+        return this.withValidation(() => {
+            const premise = this.premises.get(premiseId);
+            if (!premise) {
+                throw new Error(`Premise "${premiseId}" does not exist.`);
+            }
+            this.conclusionPremiseId = premiseId;
+            const roles = this.getRoleState();
+            const collector = new ChangeCollector();
+            collector.setRoles(roles);
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: roles,
+                changes,
+            };
+        });
+    }
+    clearConclusionPremise() {
+        return this.withValidation(() => {
+            this.conclusionPremiseId = undefined;
+            const roles = this.getRoleState();
+            const collector = new ChangeCollector();
+            collector.setRoles(roles);
+            const changes = this.finalizeChanges(collector);
+            return {
+                result: roles,
+                changes,
+            };
+        });
+    }
+    getConclusionPremise() {
+        if (this.conclusionPremiseId === undefined) {
+            return undefined;
+        }
+        return this.premises.get(this.conclusionPremiseId);
+    }
+    listSupportingPremises() {
+        return this.listPremises().filter((pm) => pm.isInference() && pm.getId() !== this.conclusionPremiseId);
+    }
+    snapshot() {
+        this.flushChecksums();
+        return {
+            argument: {
+                ...this.argument,
+                checksum: this.cachedMetaChecksum,
+                descendantChecksum: this.cachedDescendantChecksum,
+                combinedChecksum: this.cachedCombinedChecksum,
+            },
+            variables: this.variables.snapshot(),
+            premises: this.listPremises().map((pe) => pe.snapshot()),
+            ...(this.conclusionPremiseId !== undefined
+                ? { conclusionPremiseId: this.conclusionPremiseId }
+                : {}),
+            config: {
+                checksumConfig: serializeChecksumConfig(this.checksumConfig),
+                positionConfig: this.positionConfig,
+                grammarConfig: this.grammarConfig,
+            },
+        };
+    }
+    /** Creates a new ArgumentEngine from a previously captured snapshot. */
+    static fromSnapshot(snapshot, claimLibrary, sourceLibrary, claimSourceLibrary, grammarConfig, checksumVerification, generateId) {
+        const engine = new ArgumentEngine(snapshot.argument, claimLibrary, sourceLibrary, claimSourceLibrary, snapshot.config
+            ? {
+                ...snapshot.config,
+                checksumConfig: normalizeChecksumConfig(snapshot.config.checksumConfig),
+                generateId: generateId ?? snapshot.config.generateId,
+            }
+            : generateId
+                ? { generateId }
+                : undefined);
+        engine.restoringFromSnapshot = true;
+        // Restore premises first (premise-bound variables reference them)
+        for (const premiseSnap of snapshot.premises) {
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, snapshot.argument, engine.variables, engine.expressionIndex, grammarConfig, generateId);
+            engine.premises.set(pe.getId(), pe);
+            engine.wireCircularityCheck(pe);
+            engine.wireEmptyBoundPremiseCheck(pe);
+            pe.setVariableIdsCallback(() => new Set(engine.variables.toArray().map((v) => v.id)));
+            pe.setArgumentValidateCallback(() => engine.validateAfterPremiseMutation());
+            const premiseId = pe.getId();
+            pe.setOnMutate(() => {
+                engine.markDirty();
+                engine.reactiveDirty.premiseIds.add(premiseId);
+                engine.notifySubscribers();
+            });
+        }
+        // Restore claim-bound variables first, then premise-bound variables
+        for (const v of snapshot.variables.variables) {
+            if (isClaimBound(v)) {
+                engine.addVariable(v);
+            }
+        }
+        for (const v of snapshot.variables.variables) {
+            if (isPremiseBound(v)) {
+                const pbv = v;
+                if (pbv.boundArgumentId === engine.argument.id) {
+                    engine.bindVariableToPremise(v);
+                }
+                else {
+                    engine.bindVariableToExternalPremise(v);
+                }
+            }
+        }
+        // Restore conclusion role (don't use setConclusionPremise to avoid auto-assign logic)
+        engine.conclusionPremiseId = snapshot.conclusionPremiseId;
+        engine.restoringFromSnapshot = false;
+        // Post-load normalization: collapse unjustified formulas if the
+        // caller's grammar config requests it.
+        const restoredGrammarConfig = grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
+        if (restoredGrammarConfig.autoNormalize) {
+            for (const pe of engine.premises.values()) {
+                pe.normalizeExpressions();
+            }
+        }
+        if (checksumVerification === "strict") {
+            engine.flushChecksums();
+            ArgumentEngine.verifySnapshotChecksums(engine, snapshot);
+        }
+        const validation = engine.validate();
+        if (!validation.ok) {
+            throw new InvariantViolationError(validation.violations);
+        }
+        return engine;
+    }
+    /**
+     * Creates a new ArgumentEngine from flat arrays of entities, as typically
+     * stored in a relational database. Expressions are grouped by their
+     * `premiseId` field and loaded in BFS order (roots first, then children
+     * of already-added nodes) to satisfy parent-existence requirements.
+     */
+    static fromData(argument, claimLibrary, sourceLibrary, claimSourceLibrary, variables, premises, expressions, roles, config, grammarConfig, checksumVerification) {
+        const loadingGrammarConfig = grammarConfig ?? config?.grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
+        const normalizedConfig = config
+            ? {
+                ...config,
+                checksumConfig: normalizeChecksumConfig(config.checksumConfig),
+            }
+            : undefined;
+        const loadingConfig = {
+            ...normalizedConfig,
+            grammarConfig: loadingGrammarConfig,
+        };
+        const engine = new ArgumentEngine(argument, claimLibrary, sourceLibrary, claimSourceLibrary, loadingConfig);
+        engine.restoringFromSnapshot = true;
+        // Register claim-bound variables first (no dependencies)
+        for (const v of variables) {
+            if (isClaimBound(v)) {
+                engine.addVariable(v);
+            }
+        }
+        // Create premises (premise-bound variables reference them)
+        const premiseEngines = new Map();
+        for (const premise of premises) {
+            const { id: _id, argumentId: _argumentId, argumentVersion: _argumentVersion, checksum: _checksum, ...extras } = premise;
+            const { result: pe } = engine.createPremiseWithId(premise.id, extras);
+            premiseEngines.set(premise.id, pe);
+        }
+        // Register premise-bound variables (depend on premises)
+        for (const v of variables) {
+            if (isPremiseBound(v)) {
+                const pbv = v;
+                if (pbv.boundArgumentId === engine.argument.id) {
+                    engine.bindVariableToPremise(v);
+                }
+                else {
+                    engine.bindVariableToExternalPremise(v);
+                }
+            }
+        }
+        // Group expressions by premiseId
+        const exprsByPremise = new Map();
+        for (const expr of expressions) {
+            const premiseId = expr
+                .premiseId;
+            let group = exprsByPremise.get(premiseId);
+            if (!group) {
+                group = [];
+                exprsByPremise.set(premiseId, group);
+            }
+            group.push(expr);
+        }
+        // Add expressions via loadExpressions (bypasses nesting check for legacy data)
+        for (const [premiseId, pe] of premiseEngines) {
+            const premiseExprs = exprsByPremise.get(premiseId) ?? [];
+            pe.loadExpressions(premiseExprs);
+        }
+        // Set roles (override auto-assignment)
+        if (roles.conclusionPremiseId !== undefined) {
+            engine.setConclusionPremise(roles.conclusionPremiseId);
+        }
+        // After loading: restore the caller's intended grammar config
+        engine.grammarConfig = config?.grammarConfig;
+        engine.restoringFromSnapshot = false;
+        // Post-load normalization: collapse unjustified formulas and apply
+        // grammar rules to loaded data. Runs after all expressions are in place.
+        const restoredGrammarConfig = config?.grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
+        if (restoredGrammarConfig.autoNormalize) {
+            for (const pe of engine.premises.values()) {
+                pe.normalizeExpressions();
+            }
+        }
+        if (checksumVerification === "strict") {
+            engine.flushChecksums();
+            ArgumentEngine.verifyDataChecksums(engine, argument, variables, premises);
+        }
+        const validation = engine.validate();
+        if (!validation.ok) {
+            throw new InvariantViolationError(validation.violations);
+        }
+        return engine;
+    }
+    /**
+     * Verifies that all checksum fields in the snapshot match the recomputed
+     * checksums on the restored engine. Throws on the first mismatch.
+     */
+    static verifySnapshotChecksums(engine, snapshot) {
+        const checksumFields = [
+            "checksum",
+            "descendantChecksum",
+            "combinedChecksum",
+        ];
+        // Verify expression checksums
+        for (const pe of engine.listPremises()) {
+            for (const expr of pe.getExpressions()) {
+                const premiseSnap = snapshot.premises.find((ps) => ps.premise.id === pe.getId());
+                const exprSnap = premiseSnap?.expressions.expressions.find((e) => e.id === expr.id);
+                if (exprSnap) {
+                    for (const field of checksumFields) {
+                        const stored = String(exprSnap[field]);
+                        const computed = String(expr[field]);
+                        if (stored !== "undefined" && stored !== computed) {
+                            throw new Error(`Checksum mismatch on expression "${expr.id}" field "${field}": stored="${stored}", computed="${computed}"`);
+                        }
+                    }
+                }
+            }
+        }
+        // Verify variable checksums
+        for (const v of engine.getVariables()) {
+            const varSnap = snapshot.variables.variables.find((sv) => sv.id === v.id);
+            const storedVarChecksum = varSnap
+                ? String(varSnap.checksum)
+                : undefined;
+            if (storedVarChecksum && storedVarChecksum !== "undefined") {
+                if (storedVarChecksum !== v.checksum) {
+                    throw new Error(`Checksum mismatch on variable "${v.id}": stored="${storedVarChecksum}", computed="${v.checksum}"`);
+                }
+            }
+        }
+        // Verify premise checksums
+        for (const pe of engine.listPremises()) {
+            const premiseSnap = snapshot.premises.find((ps) => ps.premise.id === pe.getId());
+            if (premiseSnap?.premise) {
+                const sp = premiseSnap.premise;
+                for (const field of checksumFields) {
+                    const stored = String(sp[field]);
+                    const computed = pe[field]();
+                    if (stored !== "undefined" && stored !== computed) {
+                        throw new Error(`Checksum mismatch on premise "${pe.getId()}" field "${field}": stored="${stored}", computed="${computed}"`);
+                    }
+                }
+            }
+        }
+        // Verify argument checksums
+        const sa = snapshot.argument;
+        for (const field of checksumFields) {
+            const stored = String(sa[field]);
+            const computed = engine[field]();
+            if (stored !== "undefined" && stored !== computed) {
+                throw new Error(`Checksum mismatch on argument "${engine.getArgument().id}" field "${field}": stored="${stored}", computed="${computed}"`);
+            }
+        }
+    }
+    /**
+     * Verifies that all checksum fields in the input data match the recomputed
+     * checksums on the restored engine. Throws on the first mismatch.
+     */
+    static verifyDataChecksums(engine, argument, variables, premises) {
+        const checksumFields = [
+            "checksum",
+            "descendantChecksum",
+            "combinedChecksum",
+        ];
+        // Verify variable checksums
+        for (const v of engine.getVariables()) {
+            const inputVar = variables.find((iv) => iv.id === v.id);
+            const storedVarChecksum = inputVar
+                ? String(inputVar.checksum)
+                : undefined;
+            if (storedVarChecksum && storedVarChecksum !== "undefined") {
+                if (storedVarChecksum !== v.checksum) {
+                    throw new Error(`Checksum mismatch on variable "${v.id}": stored="${storedVarChecksum}", computed="${v.checksum}"`);
+                }
+            }
+        }
+        // Verify premise checksums
+        for (const pe of engine.listPremises()) {
+            const inputPremise = premises.find((p) => p.id === pe.getId());
+            if (inputPremise) {
+                const sp = inputPremise;
+                for (const field of checksumFields) {
+                    const stored = String(sp[field]);
+                    const computed = pe[field]();
+                    if (stored !== "undefined" && stored !== computed) {
+                        throw new Error(`Checksum mismatch on premise "${pe.getId()}" field "${field}": stored="${stored}", computed="${computed}"`);
+                    }
+                }
+            }
+        }
+        // Verify argument checksums
+        const sa = argument;
+        for (const field of checksumFields) {
+            const stored = String(sa[field]);
+            const computed = engine[field]();
+            if (stored !== "undefined" && stored !== computed) {
+                throw new Error(`Checksum mismatch on argument "${engine.getArgument().id}" field "${field}": stored="${stored}", computed="${computed}"`);
+            }
+        }
+    }
+    rollback(snapshot) {
+        const preRollbackSnap = this.snapshot();
+        this.rollbackInternal(snapshot);
+        const validation = this.validate();
+        if (!validation.ok) {
+            this.rollbackInternal(preRollbackSnap);
+            throw new InvariantViolationError(validation.violations);
+        }
+    }
+    rollbackInternal(snapshot) {
+        this.argument = { ...snapshot.argument };
+        this.checksumConfig = normalizeChecksumConfig(snapshot.config?.checksumConfig);
+        this.positionConfig = snapshot.config?.positionConfig;
+        this.grammarConfig = snapshot.config?.grammarConfig;
+        this.variables = VariableManager.fromSnapshot(snapshot.variables);
+        this.premises = new Map();
+        this.expressionIndex = new Map();
+        for (const premiseSnap of snapshot.premises) {
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, this.argument, this.variables, this.expressionIndex, PERMISSIVE_GRAMMAR_CONFIG);
+            this.premises.set(pe.getId(), pe);
+        }
+        this.conclusionPremiseId = snapshot.conclusionPremiseId;
+        for (const pe of this.premises.values()) {
+            this.wireCircularityCheck(pe);
+            this.wireEmptyBoundPremiseCheck(pe);
+            pe.setVariableIdsCallback(() => new Set(this.variables.toArray().map((v) => v.id)));
+            pe.setArgumentValidateCallback(() => this.validateAfterPremiseMutation());
+            const premiseId = pe.getId();
+            pe.setOnMutate(() => {
+                this.markDirty();
+                this.reactiveDirty.premiseIds.add(premiseId);
+                this.notifySubscribers();
+            });
+        }
+        this.markDirty();
+        this.reactiveDirty = {
+            argument: true,
+            variables: true,
+            roles: true,
+            premiseIds: new Set(),
+            allPremises: true,
+        };
+        this.notifySubscribers();
+    }
+    checksum() {
+        if (this.checksumDirty || this.cachedMetaChecksum === undefined) {
+            this.flushChecksums();
+        }
+        return this.cachedMetaChecksum;
+    }
+    descendantChecksum() {
+        if (this.checksumDirty || this.cachedDescendantChecksum === undefined) {
+            this.flushChecksums();
+        }
+        return this.cachedDescendantChecksum;
+    }
+    combinedChecksum() {
+        if (this.checksumDirty || this.cachedCombinedChecksum === undefined) {
+            this.flushChecksums();
+        }
+        return this.cachedCombinedChecksum;
+    }
+    getCollectionChecksum(name) {
+        if (this.checksumDirty) {
+            this.flushChecksums();
+        }
+        return name === "premises"
+            ? this.cachedPremisesCollectionChecksum
+            : this.cachedVariablesCollectionChecksum;
+    }
+    flushChecksums() {
+        const config = this.checksumConfig;
+        // 1. Flush all premise checksums (which flush expression checksums)
+        for (const pe of this.listPremises()) {
+            pe.flushChecksums();
+        }
+        // 2. Compute argument meta checksum (entity fields + role state MERGED)
+        const argumentFields = config?.argumentFields ?? DEFAULT_CHECKSUM_CONFIG.argumentFields;
+        const roleFields = config?.roleFields ?? DEFAULT_CHECKSUM_CONFIG.roleFields;
+        const mergedFields = new Set([...argumentFields, ...roleFields]);
+        const mergedEntity = {
+            ...this.argument,
+            ...this.getRoleState(),
+        };
+        this.cachedMetaChecksum = entityChecksum(mergedEntity, mergedFields);
+        // 3. Compute collection checksums
+        const premiseEntries = this.listPremises();
+        if (premiseEntries.length > 0) {
+            const premiseMap = {};
+            for (const pe of premiseEntries) {
+                premiseMap[pe.getId()] = pe.combinedChecksum();
+            }
+            this.cachedPremisesCollectionChecksum = computeHash(canonicalSerialize(premiseMap));
+        }
+        else {
+            this.cachedPremisesCollectionChecksum = null;
+        }
+        const vars = this.variables.toArray();
+        if (vars.length > 0) {
+            const varMap = {};
+            for (const v of vars) {
+                varMap[v.id] = v.checksum;
+            }
+            this.cachedVariablesCollectionChecksum = computeHash(canonicalSerialize(varMap));
+        }
+        else {
+            this.cachedVariablesCollectionChecksum = null;
+        }
+        // 4. Compute descendant checksum (exclude null collections)
+        const collectionMap = {};
+        if (this.cachedPremisesCollectionChecksum !== null) {
+            collectionMap.premises = this.cachedPremisesCollectionChecksum;
+        }
+        if (this.cachedVariablesCollectionChecksum !== null) {
+            collectionMap.variables = this.cachedVariablesCollectionChecksum;
+        }
+        this.cachedDescendantChecksum =
+            Object.keys(collectionMap).length > 0
+                ? computeHash(canonicalSerialize(collectionMap))
+                : null;
+        // 5. Compute combined checksum
+        this.cachedCombinedChecksum =
+            this.cachedDescendantChecksum === null
+                ? this.cachedMetaChecksum
+                : computeHash(this.cachedMetaChecksum + this.cachedDescendantChecksum);
+        this.checksumDirty = false;
+    }
+    markDirty() {
+        this.checksumDirty = true;
+        this.cachedMetaChecksum = undefined;
+        this.cachedDescendantChecksum = undefined;
+        this.cachedCombinedChecksum = undefined;
+        this.cachedPremisesCollectionChecksum = undefined;
+        this.cachedVariablesCollectionChecksum = undefined;
+    }
+    /** Invalidate all premise checksums (e.g. after variable changes). */
+    markAllPremisesDirty() {
+        for (const pm of this.listPremises()) {
+            pm.markDirty();
+        }
+    }
+    attachVariableChecksum(v) {
+        const fields = this.checksumConfig?.variableFields ??
+            DEFAULT_CHECKSUM_CONFIG.variableFields;
+        return {
+            ...v,
+            checksum: entityChecksum(v, fields),
+        };
+    }
+    collectReferencedVariables() {
+        return collectArgumentReferencedVariablesStandalone(this.asValidationContext());
+    }
+    validateAfterPremiseMutation() {
+        return validateAfterPremiseMutationStandalone(this.asValidationContext());
+    }
+    validate() {
+        return validateArgumentStandalone(this.asValidationContext());
+    }
+    validateEvaluability() {
+        return validateArgumentEvaluabilityStandalone(this.asValidationContext());
+    }
+    asValidationContext() {
+        return {
+            argumentId: this.argument.id,
+            argumentVersion: this.argument.version,
+            conclusionPremiseId: this.conclusionPremiseId,
+            getArgument: () => this.getArgument(),
+            getVariables: () => this.variables.toArray(),
+            listPremises: () => this.listPremises(),
+            hasPremise: (premiseId) => this.premises.has(premiseId),
+            lookupClaim: (claimId, claimVersion) => this.claimLibrary.get(claimId, claimVersion),
+            flushAndGetChecksumDeltas: () => {
+                const savedMeta = this.cachedMetaChecksum;
+                const savedDescendant = this.cachedDescendantChecksum;
+                const savedCombined = this.cachedCombinedChecksum;
+                this.flushChecksums();
+                return {
+                    savedMeta,
+                    savedDescendant,
+                    savedCombined,
+                    currentMeta: this.cachedMetaChecksum,
+                    currentDescendant: this.cachedDescendantChecksum,
+                    currentCombined: this.cachedCombinedChecksum,
+                };
+            },
+            validateVariables: () => this.variables.validate(),
+            wouldCreateCycle: (variableId, premiseId, visited) => this.wouldCreateCycle(variableId, premiseId, visited),
+        };
+    }
+    asEvaluationContext() {
+        return {
+            argumentId: this.argument.id,
+            conclusionPremiseId: this.conclusionPremiseId,
+            getConclusionPremise: () => this.getConclusionPremise(),
+            listSupportingPremises: () => this.listSupportingPremises(),
+            listPremises: () => this.listPremises(),
+            getVariable: (id) => this.variables.getVariable(id),
+            getPremise: (id) => this.premises.get(id),
+            validateEvaluability: () => this.validateEvaluability(),
+        };
+    }
+    evaluate(assignment, options) {
+        return evaluateArgumentStandalone(this.asEvaluationContext(), assignment, options);
+    }
+    checkValidity(options) {
+        return checkArgumentValidityStandalone(this.asEvaluationContext(), options);
+    }
+    // -----------------------------------------------------------------
+    // Forking
+    // -----------------------------------------------------------------
+    /**
+     * Override point for subclasses to prevent forking. When this returns
+     * `false`, `forkArgument` will throw.
+     */
+    canFork() {
+        return true;
+    }
+    /**
+     * Override point for subclasses to restrict cross-argument bindings.
+     * When this returns `false`, `bindVariableToExternalPremise` will throw.
+     */
+    canBind(_boundArgumentId, _boundArgumentVersion) {
+        return true;
+    }
+}
+//# sourceMappingURL=argument-engine.js.map