@polintpro/proposit-core 0.6.6 → 0.7.3

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

@@ -1,12 +1,15 @@
 import { randomUUID } from "node:crypto";
-import { isClaimBound, isPremiseBound, } from "../schemata/index.js";
-import { PERMISSIVE_GRAMMAR_CONFIG, } from "../types/grammar.js";
+import { Value } from "typebox/value";
+import { CoreArgumentSchema, isClaimBound, isPremiseBound, } from "../schemata/index.js";
+import { DEFAULT_GRAMMAR_CONFIG, PERMISSIVE_GRAMMAR_CONFIG, } from "../types/grammar.js";
+import { ARG_SCHEMA_INVALID, ARG_OWNERSHIP_MISMATCH, ARG_CLAIM_REF_NOT_FOUND, ARG_PREMISE_REF_NOT_FOUND, ARG_CIRCULARITY_DETECTED, ARG_CONCLUSION_NOT_FOUND, ARG_CHECKSUM_MISMATCH, } from "../types/validation.js";
 import { DEFAULT_CHECKSUM_CONFIG, normalizeChecksumConfig, serializeChecksumConfig, } from "../consts.js";
 import { getOrCreate, sortedUnique } from "../utils/collections.js";
 import { ChangeCollector } from "./change-collector.js";
 import { canonicalSerialize, computeHash, entityChecksum } from "./checksum.js";
 import { kleeneAnd, kleeneNot } from "./evaluation/kleene.js";
 import { makeErrorIssue, makeValidationResult, } from "./evaluation/validation.js";
+import { InvariantViolationError } from "./invariant-violation-error.js";
 import { PremiseEngine } from "./premise-engine.js";
 import { VariableManager } from "./variable-manager.js";
 /**
@@ -27,6 +30,7 @@ export class ArgumentEngine {
     checksumConfig;
     positionConfig;
     grammarConfig;
+    restoringFromSnapshot = false;
     checksumDirty = true;
     cachedMetaChecksum;
     cachedDescendantChecksum;
@@ -104,6 +108,15 @@ export class ArgumentEngine {
             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 () => {
@@ -115,6 +128,47 @@ export class ArgumentEngine {
             listener();
         }
     }
+    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();
     };
@@ -265,90 +319,115 @@ export class ArgumentEngine {
         }
         return lines.join("\n");
     }
-    createPremise(extras) {
-        return this.createPremiseWithId(randomUUID(), extras);
+    createPremise(extras, symbol) {
+        return this.createPremiseWithId(randomUUID(), extras, symbol);
     }
-    createPremiseWithId(id, extras) {
-        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,
-        });
-        this.premises.set(id, pm);
-        this.wireCircularityCheck(pm);
-        this.wireEmptyBoundPremiseCheck(pm);
-        pm.setOnMutate(() => {
+    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,
+            });
+            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();
-            this.reactiveDirty.premiseIds.add(id);
+            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: randomUUID(),
+                    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 = collector.toChangeset();
+            this.markReactiveDirty(changes);
             this.notifySubscribers();
+            return {
+                result: pm,
+                changes,
+            };
         });
-        const collector = new ChangeCollector();
-        collector.addedPremise(pm.toPremiseData());
-        this.markDirty();
-        if (this.conclusionPremiseId === undefined) {
-            this.conclusionPremiseId = id;
-            collector.setRoles(this.getRoleState());
-        }
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: pm,
-            changes,
-        };
     }
     removePremise(premiseId) {
-        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.removeVariable(v.id);
-            if (removeResult.changes.variables) {
-                for (const rv of removeResult.changes.variables.removed) {
-                    collector.removedVariable(rv);
-                }
+        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);
             }
-            if (removeResult.changes.expressions) {
-                for (const re of removeResult.changes.expressions.removed) {
-                    collector.removedExpression(re);
+            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);
+                    }
                 }
             }
-        }
-        this.markDirty();
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: data,
-            changes,
-        };
+            this.markDirty();
+            const changes = collector.toChangeset();
+            this.markReactiveDirty(changes);
+            this.notifySubscribers();
+            return {
+                result: data,
+                changes,
+            };
+        });
     }
     getPremise(premiseId) {
         return this.premises.get(premiseId);
@@ -365,122 +444,90 @@ export class ArgumentEngine {
             .filter((pm) => pm !== undefined);
     }
     addVariable(variable) {
-        // 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,
+        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.markDirty();
+            this.markAllPremisesDirty();
+            const changes = collector.toChangeset();
+            this.markReactiveDirty(changes);
+            this.notifySubscribers();
+            return {
+                result: withChecksum,
+                changes,
+            };
         });
-        this.variables.addVariable(withChecksum);
-        const collector = new ChangeCollector();
-        collector.addedVariable(withChecksum);
-        this.markDirty();
-        this.markAllPremisesDirty();
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: withChecksum,
-            changes,
-        };
     }
     bindVariableToPremise(variable) {
-        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,
+        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.markDirty();
+            this.markAllPremisesDirty();
+            const changes = collector.toChangeset();
+            this.markReactiveDirty(changes);
+            this.notifySubscribers();
+            return {
+                result: withChecksum,
+                changes,
+            };
         });
-        this.variables.addVariable(withChecksum);
-        const collector = new ChangeCollector();
-        collector.addedVariable(withChecksum);
-        this.markDirty();
-        this.markAllPremisesDirty();
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: withChecksum,
-            changes,
-        };
     }
-    updateVariable(variableId, updates) {
-        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.");
+    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}".`);
             }
-            // 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.`);
-                }
+            if (variable.argumentVersion !== this.argument.version) {
+                throw new Error(`Variable argumentVersion "${variable.argumentVersion}" does not match engine argument version "${this.argument.version}".`);
             }
-        }
-        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.`);
-                }
+            if (variable.boundArgumentId === this.argument.id) {
+                throw new Error(`boundArgumentId matches this engine's argument — use bindVariableToPremise for internal bindings.`);
             }
-            // 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.`);
-                }
+            if (!this.canBind(variable.boundArgumentId, variable.boundArgumentVersion)) {
+                throw new Error(`Binding to argument "${variable.boundArgumentId}" version ${variable.boundArgumentVersion} is not allowed.`);
             }
-        }
-        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);
+            const withChecksum = this.attachVariableChecksum({
+                ...variable,
+            });
             this.variables.addVariable(withChecksum);
-            collector.modifiedVariable(withChecksum);
+            const collector = new ChangeCollector();
+            collector.addedVariable(withChecksum);
             this.markDirty();
             this.markAllPremisesDirty();
             const changes = collector.toChangeset();
@@ -490,13 +537,90 @@ export class ArgumentEngine {
                 result: withChecksum,
                 changes,
             };
-        }
-        return {
-            result: undefined,
-            changes: collector.toChangeset(),
-        };
+        });
     }
-    removeVariable(variableId) {
+    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.markDirty();
+                this.markAllPremisesDirty();
+                const changes = collector.toChangeset();
+                this.markReactiveDirty(changes);
+                this.notifySubscribers();
+                return {
+                    result: withChecksum,
+                    changes,
+                };
+            }
+            return {
+                result: undefined,
+                changes: collector.toChangeset(),
+            };
+        });
+    }
+    removeVariableCore(variableId) {
         const variable = this.variables.getVariable(variableId);
         if (!variable) {
             return { result: undefined, changes: {} };
@@ -523,6 +647,11 @@ export class ArgumentEngine {
             changes,
         };
     }
+    removeVariable(variableId) {
+        return this.withValidation(() => {
+            return this.removeVariableCore(variableId);
+        });
+    }
     getVariables() {
         return this.variables.toArray();
     }
@@ -605,36 +734,40 @@ export class ArgumentEngine {
         };
     }
     setConclusionPremise(premiseId) {
-        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);
-        this.markDirty();
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: roles,
-            changes,
-        };
+        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);
+            this.markDirty();
+            const changes = collector.toChangeset();
+            this.markReactiveDirty(changes);
+            this.notifySubscribers();
+            return {
+                result: roles,
+                changes,
+            };
+        });
     }
     clearConclusionPremise() {
-        this.conclusionPremiseId = undefined;
-        const roles = this.getRoleState();
-        const collector = new ChangeCollector();
-        collector.setRoles(roles);
-        this.markDirty();
-        const changes = collector.toChangeset();
-        this.markReactiveDirty(changes);
-        this.notifySubscribers();
-        return {
-            result: roles,
-            changes,
-        };
+        return this.withValidation(() => {
+            this.conclusionPremiseId = undefined;
+            const roles = this.getRoleState();
+            const collector = new ChangeCollector();
+            collector.setRoles(roles);
+            this.markDirty();
+            const changes = collector.toChangeset();
+            this.markReactiveDirty(changes);
+            this.notifySubscribers();
+            return {
+                result: roles,
+                changes,
+            };
+        });
     }
     getConclusionPremise() {
         if (this.conclusionPremiseId === undefined) {
@@ -674,12 +807,15 @@ export class ArgumentEngine {
                 checksumConfig: normalizeChecksumConfig(snapshot.config.checksumConfig),
             }
             : 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);
             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();
@@ -695,15 +831,26 @@ export class ArgumentEngine {
         }
         for (const v of snapshot.variables.variables) {
             if (isPremiseBound(v)) {
-                engine.bindVariableToPremise(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;
         if (checksumVerification === "strict") {
             engine.flushChecksums();
             ArgumentEngine.verifySnapshotChecksums(engine, snapshot);
         }
+        const validation = engine.validate();
+        if (!validation.ok) {
+            throw new InvariantViolationError(validation.violations);
+        }
         return engine;
     }
     /**
@@ -713,7 +860,7 @@ export class ArgumentEngine {
      * 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 ?? PERMISSIVE_GRAMMAR_CONFIG;
+        const loadingGrammarConfig = grammarConfig ?? config?.grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
         const normalizedConfig = config
             ? {
                 ...config,
@@ -725,6 +872,7 @@ export class ArgumentEngine {
             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)) {
@@ -741,7 +889,13 @@ export class ArgumentEngine {
         // Register premise-bound variables (depend on premises)
         for (const v of variables) {
             if (isPremiseBound(v)) {
-                engine.bindVariableToPremise(v);
+                const pbv = v;
+                if (pbv.boundArgumentId === engine.argument.id) {
+                    engine.bindVariableToPremise(v);
+                }
+                else {
+                    engine.bindVariableToExternalPremise(v);
+                }
             }
         }
         // Group expressions by premiseId
@@ -767,10 +921,15 @@ export class ArgumentEngine {
         }
         // After loading: restore the caller's intended grammar config
         engine.grammarConfig = config?.grammarConfig;
+        engine.restoringFromSnapshot = false;
         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;
     }
     /**
@@ -882,6 +1041,15 @@ export class ArgumentEngine {
         }
     }
     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;
@@ -897,6 +1065,8 @@ export class ArgumentEngine {
         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();
@@ -999,6 +1169,11 @@ export class ArgumentEngine {
     }
     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() {
@@ -1060,6 +1235,207 @@ export class ArgumentEngine {
             bySymbol,
         };
     }
+    /**
+     * Validates after a PremiseEngine mutation. Identical to `validate()` but
+     * clears cached argument-level checksums first so the checksum-stability
+     * check is skipped (checksums are known to be dirty after a premise
+     * mutation).
+     */
+    /**
+     * Lightweight validation triggered after a PremiseEngine mutation.
+     * Skips per-premise deep validation (which is O(n) over all premises)
+     * and argument-level checksum stability checks (checksums are known to
+     * be dirty). Only checks argument-level cross-references that a
+     * PremiseEngine mutation could affect.
+     */
+    validateAfterPremiseMutation() {
+        const violations = [];
+        // Variable references: ensure all variable expressions in the
+        // mutated premise still reference known variables (this is the main
+        // cross-cutting invariant a premise mutation can break).
+        for (const v of this.variables.toArray()) {
+            const base = v;
+            if (isPremiseBound(base)) {
+                const pb = base;
+                if (pb.boundArgumentId === this.argument.id) {
+                    if (!this.premises.has(pb.boundPremiseId)) {
+                        violations.push({
+                            code: ARG_PREMISE_REF_NOT_FOUND,
+                            message: `Premise-bound variable "${pb.id}" references non-existent premise "${pb.boundPremiseId}".`,
+                            entityType: "variable",
+                            entityId: pb.id,
+                        });
+                    }
+                }
+            }
+        }
+        // Conclusion premise reference
+        if (this.conclusionPremiseId !== undefined &&
+            !this.premises.has(this.conclusionPremiseId)) {
+            violations.push({
+                code: ARG_CONCLUSION_NOT_FOUND,
+                message: `Conclusion premise "${this.conclusionPremiseId}" does not exist in this argument.`,
+                entityType: "argument",
+                entityId: this.argument.id,
+            });
+        }
+        return {
+            ok: violations.length === 0,
+            violations,
+        };
+    }
+    validate() {
+        const violations = [];
+        // 1. Schema check — flush checksums first so fields are populated
+        const savedMeta = this.cachedMetaChecksum;
+        const savedDescendant = this.cachedDescendantChecksum;
+        const savedCombined = this.cachedCombinedChecksum;
+        this.flushChecksums();
+        const arg = this.getArgument();
+        if (!Value.Check(CoreArgumentSchema, arg)) {
+            violations.push({
+                code: ARG_SCHEMA_INVALID,
+                message: `Argument "${arg.id}" does not conform to CoreArgumentSchema.`,
+                entityType: "argument",
+                entityId: arg.id,
+            });
+        }
+        // 2. Delegate to VariableManager.validate()
+        const varResult = this.variables.validate();
+        violations.push(...varResult.violations);
+        // 3. Delegate to each PremiseEngine.validate()
+        for (const pe of this.listPremises()) {
+            const premiseResult = pe.validate();
+            violations.push(...premiseResult.violations);
+        }
+        // 4. Variable ownership: all variables must belong to this argument
+        for (const v of this.variables.toArray()) {
+            const base = v;
+            if (base.argumentId !== this.argument.id ||
+                base.argumentVersion !== this.argument.version) {
+                violations.push({
+                    code: ARG_OWNERSHIP_MISMATCH,
+                    message: `Variable "${base.id}" has argumentId/version "${base.argumentId}/${base.argumentVersion}" but engine is "${this.argument.id}/${this.argument.version}".`,
+                    entityType: "variable",
+                    entityId: base.id,
+                });
+            }
+        }
+        // 5. Claim-bound variable references
+        for (const v of this.variables.toArray()) {
+            const base = v;
+            if (isClaimBound(base)) {
+                const cb = base;
+                if (!this.claimLibrary.get(cb.claimId, cb.claimVersion)) {
+                    violations.push({
+                        code: ARG_CLAIM_REF_NOT_FOUND,
+                        message: `Variable "${cb.id}" references claim "${cb.claimId}" version ${cb.claimVersion} which does not exist in the claim library.`,
+                        entityType: "variable",
+                        entityId: cb.id,
+                    });
+                }
+            }
+        }
+        // 6. Premise-bound internal variable references
+        for (const v of this.variables.toArray()) {
+            const base = v;
+            if (isPremiseBound(base)) {
+                const pb = base;
+                if (pb.boundArgumentId === this.argument.id) {
+                    if (!this.premises.has(pb.boundPremiseId)) {
+                        violations.push({
+                            code: ARG_PREMISE_REF_NOT_FOUND,
+                            message: `Premise-bound variable "${pb.id}" references non-existent premise "${pb.boundPremiseId}".`,
+                            entityType: "variable",
+                            entityId: pb.id,
+                        });
+                    }
+                }
+            }
+        }
+        // 7. Circularity detection for internal premise-bound variables.
+        //    A cycle exists when a premise-bound variable's bound premise
+        //    transitively references back to itself through other
+        //    premise-bound variables.
+        for (const v of this.variables.toArray()) {
+            const base = v;
+            if (isPremiseBound(base)) {
+                const pb = base;
+                if (pb.boundArgumentId === this.argument.id) {
+                    // Trace from the bound premise through expressions'
+                    // variable references to see if we reach back to the
+                    // same premise.
+                    const boundPremise = this.premises.get(pb.boundPremiseId);
+                    if (boundPremise) {
+                        let hasCycle = false;
+                        for (const expr of boundPremise.getExpressions()) {
+                            if (expr.type === "variable") {
+                                try {
+                                    if (this.wouldCreateCycle(expr.variableId, pb.boundPremiseId, new Set())) {
+                                        hasCycle = true;
+                                        break;
+                                    }
+                                }
+                                catch {
+                                    hasCycle = true;
+                                    break;
+                                }
+                            }
+                        }
+                        if (hasCycle) {
+                            violations.push({
+                                code: ARG_CIRCULARITY_DETECTED,
+                                message: `Premise-bound variable "${pb.id}" creates a circular dependency through premise "${pb.boundPremiseId}".`,
+                                entityType: "variable",
+                                entityId: pb.id,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // 8. Conclusion premise reference
+        if (this.conclusionPremiseId !== undefined &&
+            !this.premises.has(this.conclusionPremiseId)) {
+            violations.push({
+                code: ARG_CONCLUSION_NOT_FOUND,
+                message: `Conclusion premise "${this.conclusionPremiseId}" does not exist in this argument.`,
+                entityType: "argument",
+                entityId: this.argument.id,
+            });
+        }
+        // 9. Argument-level checksum verification
+        if (savedMeta !== undefined && savedMeta !== this.cachedMetaChecksum) {
+            violations.push({
+                code: ARG_CHECKSUM_MISMATCH,
+                message: `Argument "${this.argument.id}" meta checksum changed after flush: "${savedMeta}" → "${this.cachedMetaChecksum}".`,
+                entityType: "argument",
+                entityId: this.argument.id,
+            });
+        }
+        if (savedDescendant !== undefined &&
+            savedDescendant !== this.cachedDescendantChecksum) {
+            violations.push({
+                code: ARG_CHECKSUM_MISMATCH,
+                message: `Argument "${this.argument.id}" descendant checksum changed after flush: "${String(savedDescendant)}" → "${String(this.cachedDescendantChecksum)}".`,
+                entityType: "argument",
+                entityId: this.argument.id,
+            });
+        }
+        if (savedCombined !== undefined &&
+            savedCombined !== this.cachedCombinedChecksum) {
+            violations.push({
+                code: ARG_CHECKSUM_MISMATCH,
+                message: `Argument "${this.argument.id}" combined checksum changed after flush: "${savedCombined}" → "${this.cachedCombinedChecksum}".`,
+                entityType: "argument",
+                entityId: this.argument.id,
+            });
+        }
+        return {
+            ok: violations.length === 0,
+            violations,
+        };
+    }
     validateEvaluability() {
         const issues = [];
         if (this.conclusionPremiseId === undefined) {
@@ -1150,11 +1526,17 @@ export class ArgumentEngine {
                 .filter((expr) => expr.type === "variable")
                 .map((expr) => expr.variableId))),
         ].sort();
-        // Only claim-bound variables get truth-table columns;
-        // premise-bound variables are resolved lazily from their bound premise.
+        // Claim-bound and externally-bound premise variables get truth-table columns;
+        // internally-bound premise variables are resolved lazily.
         const referencedVariableIds = allVariableIds.filter((vid) => {
             const v = this.variables.getVariable(vid);
-            return v != null && isClaimBound(v);
+            if (v == null)
+                return false;
+            if (isClaimBound(v))
+                return true;
+            if (isPremiseBound(v) && v.boundArgumentId !== this.argument.id)
+                return true;
+            return false;
         });
         try {
             // Build a resolver that lazily evaluates premise-bound variables
@@ -1166,9 +1548,13 @@ export class ArgumentEngine {
                     return resolverCache.get(variableId);
                 }
                 const variable = this.variables.getVariable(variableId);
-                if (!variable || !isPremiseBound(variable)) {
+                if (!variable ||
+                    !isPremiseBound(variable) ||
+                    variable.boundArgumentId !== this.argument.id) {
+                    // Claim-bound or externally-bound: read from assignment
                     return assignment.variables[variableId] ?? null;
                 }
+                // Internal premise-bound: lazy resolution
                 const boundPremiseId = variable.boundPremiseId;
                 const boundPremise = this.premises.get(boundPremiseId);
                 if (!boundPremise) {
@@ -1274,11 +1660,17 @@ export class ArgumentEngine {
                 .filter((expr) => expr.type === "variable")
                 .map((expr) => expr.variableId))),
         ].sort();
-        // Only claim-bound variables get truth-table columns;
-        // premise-bound variables are resolved lazily from their bound premise.
+        // Claim-bound and externally-bound premise variables get truth-table columns;
+        // internally-bound premise variables are resolved lazily.
         const checkedVariableIds = allVariableIdsForCheck.filter((vid) => {
             const v = this.variables.getVariable(vid);
-            return v != null && isClaimBound(v);
+            if (v == null)
+                return false;
+            if (isClaimBound(v))
+                return true;
+            if (isPremiseBound(v) && v.boundArgumentId !== this.argument.id)
+                return true;
+            return false;
         });
         if (options?.maxVariables !== undefined &&
             checkedVariableIds.length > options.maxVariables) {
@@ -1355,5 +1747,150 @@ export class ArgumentEngine {
             truncated,
         };
     }
+    // -----------------------------------------------------------------
+    // 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;
+    }
+    /**
+     * Creates an independent copy of this argument under a new argument ID.
+     *
+     * Every premise, expression, and variable receives a fresh ID (via
+     * `options.generateId`, defaulting to `crypto.randomUUID`). All internal
+     * cross-references are remapped to the new IDs. Each forked entity carries
+     * `forkedFrom*` metadata pointing back to the originals.
+     *
+     * The returned engine is fully independent — mutations on either the
+     * source or the fork do not affect the other.
+     */
+    forkArgument(newArgumentId, claimLibrary, sourceLibrary, claimSourceLibrary, options) {
+        // 1. Guard
+        if (!this.canFork()) {
+            throw new Error("Forking is not allowed for this engine.");
+        }
+        const generateId = options?.generateId ?? randomUUID;
+        // 2. Snapshot the current engine state
+        const snap = this.snapshot();
+        const originalArgumentId = snap.argument.id;
+        const originalArgumentVersion = snap.argument.version;
+        // 3. Build remap tables  (old ID → new ID)
+        const premiseRemap = new Map();
+        const expressionRemap = new Map();
+        const variableRemap = new Map();
+        for (const ps of snap.premises) {
+            premiseRemap.set(ps.premise.id, generateId());
+            for (const expr of ps.expressions.expressions) {
+                expressionRemap.set(expr.id, generateId());
+            }
+        }
+        for (const v of snap.variables.variables) {
+            variableRemap.set(v.id, generateId());
+        }
+        const remapTable = {
+            argumentId: { from: originalArgumentId, to: newArgumentId },
+            premises: premiseRemap,
+            expressions: expressionRemap,
+            variables: variableRemap,
+        };
+        // 4. Remap the argument entity
+        snap.argument = {
+            ...snap.argument,
+            id: newArgumentId,
+            version: 0,
+            forkedFromArgumentId: originalArgumentId,
+            forkedFromArgumentVersion: originalArgumentVersion,
+        };
+        // 5. Remap premises and their expressions
+        for (const ps of snap.premises) {
+            const originalPremiseId = ps.premise.id;
+            const newPremiseId = premiseRemap.get(originalPremiseId);
+            ps.premise = {
+                ...ps.premise,
+                id: newPremiseId,
+                argumentId: newArgumentId,
+                argumentVersion: 0,
+                forkedFromPremiseId: originalPremiseId,
+                forkedFromArgumentId: originalArgumentId,
+                forkedFromArgumentVersion: originalArgumentVersion,
+            };
+            // Remap rootExpressionId
+            if (ps.rootExpressionId) {
+                ps.rootExpressionId = expressionRemap.get(ps.rootExpressionId);
+            }
+            // Remap each expression
+            ps.expressions.expressions = ps.expressions.expressions.map((expr) => {
+                const originalExprId = expr.id;
+                const newExprId = expressionRemap.get(originalExprId);
+                const remapped = {
+                    ...expr,
+                    id: newExprId,
+                    argumentId: newArgumentId,
+                    argumentVersion: 0,
+                    premiseId: newPremiseId,
+                    parentId: expr.parentId
+                        ? (expressionRemap.get(expr.parentId) ?? null)
+                        : null,
+                    forkedFromExpressionId: originalExprId,
+                    forkedFromPremiseId: originalPremiseId,
+                    forkedFromArgumentId: originalArgumentId,
+                    forkedFromArgumentVersion: originalArgumentVersion,
+                };
+                // Remap variableId on variable-type expressions
+                if (remapped.type === "variable" &&
+                    "variableId" in remapped) {
+                    const origVarId = remapped.variableId;
+                    remapped.variableId = variableRemap.get(origVarId);
+                }
+                return remapped;
+            });
+        }
+        // 6. Remap variables
+        snap.variables.variables = snap.variables.variables.map((v) => {
+            const originalVarId = v.id;
+            const newVarId = variableRemap.get(originalVarId);
+            const remapped = {
+                ...v,
+                id: newVarId,
+                argumentId: newArgumentId,
+                argumentVersion: 0,
+                forkedFromVariableId: originalVarId,
+                forkedFromArgumentId: originalArgumentId,
+                forkedFromArgumentVersion: originalArgumentVersion,
+            };
+            // Remap premise-bound variable references
+            if (isPremiseBound(remapped)) {
+                const premiseBound = remapped;
+                premiseBound.boundPremiseId = premiseRemap.get(premiseBound.boundPremiseId);
+                premiseBound.boundArgumentId = newArgumentId;
+                premiseBound.boundArgumentVersion = 0;
+            }
+            return remapped;
+        });
+        // 7. Remap conclusion role
+        if (snap.conclusionPremiseId) {
+            snap.conclusionPremiseId = premiseRemap.get(snap.conclusionPremiseId);
+        }
+        // 8. Carry config from options or source engine
+        snap.config = {
+            checksumConfig: serializeChecksumConfig(options?.checksumConfig ?? this.checksumConfig),
+            positionConfig: options?.positionConfig ?? this.positionConfig,
+            grammarConfig: options?.grammarConfig ?? this.grammarConfig,
+        };
+        // 9. Construct the new engine from the remapped snapshot
+        const engine = ArgumentEngine.fromSnapshot(snap, claimLibrary, sourceLibrary, claimSourceLibrary, options?.grammarConfig ?? this.grammarConfig, "ignore");
+        return { engine, remapTable };
+    }
 }
 //# sourceMappingURL=argument-engine.js.map