@polintpro/proposit-core 0.3.0 → 0.4.0

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

@@ -7,6 +7,7 @@ import { kleeneAnd, kleeneNot } from "./evaluation/kleene.js";
 import { makeErrorIssue, makeValidationResult, } from "./evaluation/validation.js";
 import { PremiseEngine } from "./premise-engine.js";
 import { VariableManager } from "./variable-manager.js";
+import { SourceManager } from "./source-manager.js";
 /**
  * Manages a propositional logic argument composed of premises, variable
  * assignments, and logical roles (supporting premises and a conclusion).
@@ -18,6 +19,7 @@ export class ArgumentEngine {
     argument;
     premises;
     variables;
+    sourceManager;
     conclusionPremiseId;
     checksumConfig;
     positionConfig;
@@ -29,6 +31,7 @@ export class ArgumentEngine {
         argument: true,
         variables: true,
         roles: true,
+        sources: true,
         premiseIds: new Set(),
         allPremises: true,
     };
@@ -40,15 +43,12 @@ export class ArgumentEngine {
             checksumConfig: this.checksumConfig,
             positionConfig: this.positionConfig,
         });
+        this.sourceManager = new SourceManager();
         this.expressionIndex = new Map();
         this.conclusionPremiseId = undefined;
         this.checksumConfig = options?.checksumConfig;
         this.positionConfig = options?.positionConfig;
     }
-    /**
-     * Registers a listener that is called after every mutation.
-     * Returns an unsubscribe function.
-     */
     subscribe = (listener) => {
         this.listeners.add(listener);
         return () => {
@@ -70,6 +70,7 @@ export class ArgumentEngine {
             !dirty.argument &&
             !dirty.variables &&
             !dirty.roles &&
+            !dirty.sources &&
             dirty.premiseIds.size === 0 &&
             !dirty.allPremises) {
             return prev;
@@ -108,17 +109,43 @@ export class ArgumentEngine {
                 }
             }
         }
+        let sourcesRecord;
+        let varAssocRecord;
+        let exprAssocRecord;
+        if (dirty.sources || !prev) {
+            sourcesRecord = {};
+            for (const s of this.sourceManager.getSources()) {
+                sourcesRecord[s.id] = s;
+            }
+            varAssocRecord = {};
+            for (const a of this.sourceManager.getAllVariableSourceAssociations()) {
+                varAssocRecord[a.id] = a;
+            }
+            exprAssocRecord = {};
+            for (const a of this.sourceManager.getAllExpressionSourceAssociations()) {
+                exprAssocRecord[a.id] = a;
+            }
+        }
+        else {
+            sourcesRecord = prev.sources;
+            varAssocRecord = prev.variableSourceAssociations;
+            exprAssocRecord = prev.expressionSourceAssociations;
+        }
         const snapshot = {
             argument,
             variables,
             premises,
             roles,
+            sources: sourcesRecord,
+            variableSourceAssociations: varAssocRecord,
+            expressionSourceAssociations: exprAssocRecord,
         };
         this.cachedReactiveSnapshot = snapshot;
         this.reactiveDirty = {
             argument: false,
             variables: false,
             roles: false,
+            sources: false,
             premiseIds: new Set(),
             allPremises: false,
         };
@@ -178,12 +205,15 @@ export class ArgumentEngine {
                 this.reactiveDirty.premiseIds.add(p.id);
             }
         }
+        if (changes.sources ||
+            changes.variableSourceAssociations ||
+            changes.expressionSourceAssociations) {
+            this.reactiveDirty.sources = true;
+        }
     }
-    /** Returns a shallow copy of the argument metadata with checksum attached. */
     getArgument() {
         return { ...this.argument, checksum: this.checksum() };
     }
-    /** Renders the argument as a multi-line string with role labels for each premise. */
     toDisplayString() {
         const lines = [];
         const arg = this.getArgument();
@@ -206,19 +236,9 @@ export class ArgumentEngine {
         }
         return lines.join("\n");
     }
-    /**
-     * Creates a new premise with an auto-generated UUID and registers it
-     * with this engine.
-     */
     createPremise(extras) {
         return this.createPremiseWithId(randomUUID(), extras);
     }
-    /**
-     * Creates a premise with a caller-supplied ID and registers it with
-     * this engine.
-     *
-     * @throws If a premise with the given ID already exists.
-     */
     createPremiseWithId(id, extras) {
         if (this.premises.has(id)) {
             throw new Error(`Premise "${id}" already exists.`);
@@ -233,6 +253,7 @@ export class ArgumentEngine {
             argument: this.argument,
             variables: this.variables,
             expressionIndex: this.expressionIndex,
+            sourceManager: this.sourceManager,
         }, {
             checksumConfig: this.checksumConfig,
             positionConfig: this.positionConfig,
@@ -257,21 +278,24 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /**
-     * Removes a premise and clears any role assignments that reference it.
-     * Returns the removed premise data, or `undefined` if not found.
-     */
     removePremise(premiseId) {
         const pm = this.premises.get(premiseId);
         if (!pm)
             return { result: undefined, changes: {} };
         const data = pm.toPremiseData();
-        // Clean up expression index for removed premise's expressions
+        const collector = new ChangeCollector();
+        // Clean up expression index and source associations for removed premise's expressions
         for (const expr of pm.getExpressions()) {
             this.expressionIndex.delete(expr.id);
+            const sourceResult = this.sourceManager.removeAssociationsForExpression(expr.id);
+            for (const assoc of sourceResult.removedExpressionAssociations) {
+                collector.removedExpressionSourceAssociation(assoc);
+            }
+            for (const orphan of sourceResult.removedOrphanSources) {
+                collector.removedSource(orphan);
+            }
         }
         this.premises.delete(premiseId);
-        const collector = new ChangeCollector();
         collector.removedPremise(data);
         if (this.conclusionPremiseId === premiseId) {
             this.conclusionPremiseId = undefined;
@@ -286,31 +310,20 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /** Returns the premise with the given ID, or `undefined` if not found. */
     getPremise(premiseId) {
         return this.premises.get(premiseId);
     }
-    /** Returns `true` if a premise with the given ID exists. */
     hasPremise(premiseId) {
         return this.premises.has(premiseId);
     }
-    /** Returns all premise IDs in lexicographic order. */
     listPremiseIds() {
         return Array.from(this.premises.keys()).sort((a, b) => a.localeCompare(b));
     }
-    /** Returns all premises in lexicographic ID order. */
     listPremises() {
         return this.listPremiseIds()
             .map((id) => this.premises.get(id))
             .filter((pm) => pm !== undefined);
     }
-    /**
-     * Registers a propositional variable for use across all premises.
-     *
-     * @throws If `variable.symbol` is already in use.
-     * @throws If `variable.id` already exists.
-     * @throws If the variable does not belong to this argument.
-     */
     addVariable(variable) {
         if (variable.argumentId !== this.argument.id) {
             throw new Error(`Variable argumentId "${variable.argumentId}" does not match engine argument ID "${this.argument.id}".`);
@@ -332,12 +345,6 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /**
-     * Updates fields on an existing variable. Since all premises share the
-     * same VariableManager, the update is immediately visible everywhere.
-     *
-     * @throws If the new symbol is already in use by a different variable.
-     */
     updateVariable(variableId, updates) {
         const updated = this.variables.updateVariable(variableId, updates);
         const collector = new ChangeCollector();
@@ -363,10 +370,6 @@ export class ArgumentEngine {
             changes: collector.toChangeset(),
         };
     }
-    /**
-     * Removes a variable and cascade-deletes all expressions referencing it
-     * across every premise (including subtrees and operator collapse).
-     */
     removeVariable(variableId) {
         const variable = this.variables.getVariable(variableId);
         if (!variable) {
@@ -374,6 +377,8 @@ export class ArgumentEngine {
         }
         const collector = new ChangeCollector();
         // Cascade: delete referencing expressions in every premise
+        // (PremiseEngine.removeExpression already cascades expression-source
+        //  associations via the Task 12 logic)
         for (const pm of this.listPremises()) {
             const { changes } = pm.deleteExpressionsUsingVariable(variableId);
             if (changes.expressions) {
@@ -381,6 +386,24 @@ export class ArgumentEngine {
                     collector.removedExpression(e);
                 }
             }
+            if (changes.expressionSourceAssociations) {
+                for (const a of changes.expressionSourceAssociations.removed) {
+                    collector.removedExpressionSourceAssociation(a);
+                }
+            }
+            if (changes.sources) {
+                for (const s of changes.sources.removed) {
+                    collector.removedSource(s);
+                }
+            }
+        }
+        // Cascade: remove variable-source associations
+        const varAssocResult = this.sourceManager.removeAssociationsForVariable(variableId);
+        for (const assoc of varAssocResult.removedVariableAssociations) {
+            collector.removedVariableSourceAssociation(assoc);
+        }
+        for (const orphan of varAssocResult.removedOrphanSources) {
+            collector.removedSource(orphan);
         }
         this.variables.removeVariable(variableId);
         collector.removedVariable(variable);
@@ -394,27 +417,18 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /** Returns all registered variables sorted by ID. */
     getVariables() {
         return this.variables.toArray();
     }
-    /** Returns the variable with the given ID, or `undefined` if not found. */
     getVariable(variableId) {
         return this.variables.getVariable(variableId);
     }
-    /** Returns `true` if a variable with the given ID exists. */
     hasVariable(variableId) {
         return this.variables.hasVariable(variableId);
     }
-    /** Returns the variable with the given symbol, or `undefined` if not found. */
     getVariableBySymbol(symbol) {
         return this.variables.getVariableBySymbol(symbol);
     }
-    /**
-     * Builds a Map keyed by a caller-supplied function over all variables.
-     * Useful for indexing by extension fields (e.g. statementId).
-     * The caller should cache the result — this is O(n) per call.
-     */
     buildVariableIndex(keyFn) {
         const map = new Map();
         for (const v of this.variables.toArray()) {
@@ -422,29 +436,24 @@ export class ArgumentEngine {
         }
         return map;
     }
-    /** Returns an expression by ID from any premise, or `undefined` if not found. */
     getExpression(expressionId) {
         const premiseId = this.expressionIndex.get(expressionId);
         if (premiseId === undefined)
             return undefined;
         return this.premises.get(premiseId)?.getExpression(expressionId);
     }
-    /** Returns `true` if an expression with the given ID exists in any premise. */
     hasExpression(expressionId) {
         return this.expressionIndex.has(expressionId);
     }
-    /** Returns the premise ID that contains the given expression, or `undefined`. */
     getExpressionPremiseId(expressionId) {
         return this.expressionIndex.get(expressionId);
     }
-    /** Returns the PremiseEngine containing the given expression, or `undefined`. */
     findPremiseByExpressionId(expressionId) {
         const premiseId = this.expressionIndex.get(expressionId);
         if (premiseId === undefined)
             return undefined;
         return this.premises.get(premiseId);
     }
-    /** Returns all expressions across all premises, sorted by ID. */
     getAllExpressions() {
         const all = [];
         for (const pe of this.listPremises()) {
@@ -452,10 +461,6 @@ export class ArgumentEngine {
         }
         return all.sort((a, b) => a.id.localeCompare(b.id));
     }
-    /**
-     * Returns all expressions that reference the given variable ID,
-     * across all premises.
-     */
     getExpressionsByVariableId(variableId) {
         const result = [];
         for (const pe of this.listPremises()) {
@@ -471,7 +476,6 @@ export class ArgumentEngine {
         }
         return result;
     }
-    /** Returns the root expression from each premise that has one. */
     listRootExpressions() {
         const roots = [];
         for (const pe of this.listPremises()) {
@@ -481,7 +485,6 @@ export class ArgumentEngine {
         }
         return roots;
     }
-    /** Returns the current role assignments (conclusion premise ID only; supporting is derived). */
     getRoleState() {
         return {
             ...(this.conclusionPremiseId !== undefined
@@ -489,11 +492,6 @@ export class ArgumentEngine {
                 : {}),
         };
     }
-    /**
-     * Designates a premise as the argument's conclusion.
-     *
-     * @throws If the premise does not exist.
-     */
     setConclusionPremise(premiseId) {
         const premise = this.premises.get(premiseId);
         if (!premise) {
@@ -512,7 +510,6 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /** Clears the conclusion designation. */
     clearConclusionPremise() {
         this.conclusionPremiseId = undefined;
         const roles = this.getRoleState();
@@ -527,21 +524,190 @@ export class ArgumentEngine {
             changes,
         };
     }
-    /** Returns the conclusion premise, or `undefined` if none is set. */
     getConclusionPremise() {
         if (this.conclusionPremiseId === undefined) {
             return undefined;
         }
         return this.premises.get(this.conclusionPremiseId);
     }
-    /**
-     * Returns all supporting premises (derived: inference premises that are
-     * not the conclusion) in lexicographic ID order.
-     */
     listSupportingPremises() {
         return this.listPremises().filter((pm) => pm.isInference() && pm.getId() !== this.conclusionPremiseId);
     }
-    /** Returns a serializable snapshot of the full engine state. */
+    // -------------------------------------------------------------------------
+    // Source management
+    // -------------------------------------------------------------------------
+    addSource(source) {
+        if (source.argumentId !== this.argument.id) {
+            throw new Error(`Source argumentId "${source.argumentId}" does not match engine argument ID "${this.argument.id}".`);
+        }
+        if (source.argumentVersion !== this.argument.version) {
+            throw new Error(`Source argumentVersion ${source.argumentVersion} does not match engine argument version ${this.argument.version}.`);
+        }
+        const fields = this.checksumConfig?.sourceFields ??
+            DEFAULT_CHECKSUM_CONFIG.sourceFields;
+        const sourceWithChecksum = {
+            ...source,
+            checksum: entityChecksum(source, fields),
+        };
+        this.sourceManager.addSource(sourceWithChecksum);
+        const collector = new ChangeCollector();
+        collector.addedSource(sourceWithChecksum);
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return { result: sourceWithChecksum, changes };
+    }
+    removeSource(sourceId) {
+        const source = this.sourceManager.getSource(sourceId);
+        if (!source) {
+            return { result: undefined, changes: {} };
+        }
+        const removalResult = this.sourceManager.removeSource(sourceId);
+        const collector = new ChangeCollector();
+        collector.removedSource(source);
+        for (const assoc of removalResult.removedVariableAssociations) {
+            collector.removedVariableSourceAssociation(assoc);
+        }
+        for (const assoc of removalResult.removedExpressionAssociations) {
+            collector.removedExpressionSourceAssociation(assoc);
+        }
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return { result: source, changes };
+    }
+    addVariableSourceAssociation(sourceId, variableId) {
+        if (!this.sourceManager.getSource(sourceId)) {
+            throw new Error(`Source "${sourceId}" does not exist.`);
+        }
+        if (!this.variables.hasVariable(variableId)) {
+            throw new Error(`Variable "${variableId}" does not exist.`);
+        }
+        const assoc = {
+            id: randomUUID(),
+            sourceId,
+            variableId,
+            argumentId: this.argument.id,
+            argumentVersion: this.argument.version,
+            checksum: "",
+        };
+        const fields = this.checksumConfig?.variableSourceAssociationFields ??
+            DEFAULT_CHECKSUM_CONFIG.variableSourceAssociationFields;
+        const assocWithChecksum = {
+            ...assoc,
+            checksum: entityChecksum(assoc, fields),
+        };
+        this.sourceManager.addVariableSourceAssociation(assocWithChecksum);
+        const collector = new ChangeCollector();
+        collector.addedVariableSourceAssociation(assocWithChecksum);
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return { result: assocWithChecksum, changes };
+    }
+    removeVariableSourceAssociation(associationId) {
+        const allVarAssocs = this.sourceManager.getAllVariableSourceAssociations();
+        if (!allVarAssocs.some((a) => a.id === associationId)) {
+            return { result: undefined, changes: {} };
+        }
+        const removalResult = this.sourceManager.removeVariableSourceAssociation(associationId);
+        const collector = new ChangeCollector();
+        for (const assoc of removalResult.removedVariableAssociations) {
+            collector.removedVariableSourceAssociation(assoc);
+        }
+        for (const orphan of removalResult.removedOrphanSources) {
+            collector.removedSource(orphan);
+        }
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return {
+            result: removalResult.removedVariableAssociations[0],
+            changes,
+        };
+    }
+    addExpressionSourceAssociation(sourceId, expressionId, premiseId) {
+        if (!this.sourceManager.getSource(sourceId)) {
+            throw new Error(`Source "${sourceId}" does not exist.`);
+        }
+        const pm = this.premises.get(premiseId);
+        if (!pm) {
+            throw new Error(`Premise "${premiseId}" does not exist.`);
+        }
+        if (!pm.getExpression(expressionId)) {
+            throw new Error(`Expression "${expressionId}" does not exist in premise "${premiseId}".`);
+        }
+        const assoc = {
+            id: randomUUID(),
+            sourceId,
+            expressionId,
+            premiseId,
+            argumentId: this.argument.id,
+            argumentVersion: this.argument.version,
+            checksum: "",
+        };
+        const fields = this.checksumConfig?.expressionSourceAssociationFields ??
+            DEFAULT_CHECKSUM_CONFIG.expressionSourceAssociationFields;
+        const assocWithChecksum = {
+            ...assoc,
+            checksum: entityChecksum(assoc, fields),
+        };
+        this.sourceManager.addExpressionSourceAssociation(assocWithChecksum);
+        const collector = new ChangeCollector();
+        collector.addedExpressionSourceAssociation(assocWithChecksum);
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return { result: assocWithChecksum, changes };
+    }
+    removeExpressionSourceAssociation(associationId) {
+        const allExprAssocs = this.sourceManager.getAllExpressionSourceAssociations();
+        if (!allExprAssocs.some((a) => a.id === associationId)) {
+            return { result: undefined, changes: {} };
+        }
+        const removalResult = this.sourceManager.removeExpressionSourceAssociation(associationId);
+        const collector = new ChangeCollector();
+        for (const assoc of removalResult.removedExpressionAssociations) {
+            collector.removedExpressionSourceAssociation(assoc);
+        }
+        for (const orphan of removalResult.removedOrphanSources) {
+            collector.removedSource(orphan);
+        }
+        this.markDirty();
+        const changes = collector.toChangeset();
+        this.markReactiveDirty(changes);
+        this.notifySubscribers();
+        return {
+            result: removalResult.removedExpressionAssociations[0],
+            changes,
+        };
+    }
+    getSources() {
+        return this.sourceManager.getSources();
+    }
+    getSource(sourceId) {
+        return this.sourceManager.getSource(sourceId);
+    }
+    getAssociationsForSource(sourceId) {
+        return this.sourceManager.getAssociationsForSource(sourceId);
+    }
+    getAssociationsForVariable(variableId) {
+        return this.sourceManager.getAssociationsForVariable(variableId);
+    }
+    getAssociationsForExpression(expressionId) {
+        return this.sourceManager.getAssociationsForExpression(expressionId);
+    }
+    getAllVariableSourceAssociations() {
+        return this.sourceManager.getAllVariableSourceAssociations();
+    }
+    getAllExpressionSourceAssociations() {
+        return this.sourceManager.getAllExpressionSourceAssociations();
+    }
     snapshot() {
         return {
             argument: { ...this.argument },
@@ -554,6 +720,7 @@ export class ArgumentEngine {
                 checksumConfig: this.checksumConfig,
                 positionConfig: this.positionConfig,
             },
+            sources: this.sourceManager.snapshot(),
         };
     }
     /** Creates a new ArgumentEngine from a previously captured snapshot. */
@@ -563,9 +730,13 @@ export class ArgumentEngine {
         for (const v of snapshot.variables.variables) {
             engine.addVariable(v);
         }
+        // Restore source manager (before premises, so PremiseEngines get the correct reference)
+        if (snapshot.sources) {
+            engine.sourceManager = SourceManager.fromSnapshot(snapshot.sources);
+        }
         // Restore premises using PremiseEngine.fromSnapshot
         for (const premiseSnap of snapshot.premises) {
-            const pe = PremiseEngine.fromSnapshot(premiseSnap, snapshot.argument, engine.variables, engine.expressionIndex);
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, snapshot.argument, engine.variables, engine.expressionIndex, engine.sourceManager);
             engine.premises.set(pe.getId(), pe);
             const premiseId = pe.getId();
             pe.setOnMutate(() => {
@@ -632,16 +803,18 @@ export class ArgumentEngine {
         }
         return engine;
     }
-    /** Restores the engine to a previously captured snapshot state. */
     rollback(snapshot) {
         this.argument = { ...snapshot.argument };
         this.checksumConfig = snapshot.config?.checksumConfig;
         this.positionConfig = snapshot.config?.positionConfig;
         this.variables = VariableManager.fromSnapshot(snapshot.variables);
+        this.sourceManager = snapshot.sources
+            ? SourceManager.fromSnapshot(snapshot.sources)
+            : new SourceManager();
         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);
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, this.argument, this.variables, this.expressionIndex, this.sourceManager);
             this.premises.set(pe.getId(), pe);
         }
         this.conclusionPremiseId = snapshot.conclusionPremiseId;
@@ -657,16 +830,12 @@ export class ArgumentEngine {
             argument: true,
             variables: true,
             roles: true,
+            sources: true,
             premiseIds: new Set(),
             allPremises: true,
         };
         this.notifySubscribers();
     }
-    /**
-     * Returns an argument-level checksum combining argument metadata, role
-     * state, and all premise checksums. Computed lazily -- only recalculated
-     * when the engine's own state has changed.
-     */
     checksum() {
         if (this.checksumDirty || this.cachedChecksum === undefined) {
             this.cachedChecksum = this.computeChecksum();
@@ -689,6 +858,17 @@ export class ArgumentEngine {
         for (const pe of this.listPremises()) {
             checksumMap[pe.getId()] = pe.checksum();
         }
+        // Source checksums
+        for (const s of this.sourceManager.getSources()) {
+            checksumMap[s.id] = s.checksum;
+        }
+        // Association checksums
+        for (const a of this.sourceManager.getAllVariableSourceAssociations()) {
+            checksumMap[a.id] = a.checksum;
+        }
+        for (const a of this.sourceManager.getAllExpressionSourceAssociations()) {
+            checksumMap[a.id] = a.checksum;
+        }
         return computeHash(canonicalSerialize(checksumMap));
     }
     markDirty() {
@@ -708,10 +888,6 @@ export class ArgumentEngine {
             checksum: entityChecksum(v, fields),
         };
     }
-    /**
-     * Collects all variables referenced by expressions across all premises,
-     * indexed both by variable ID and by symbol.
-     */
     collectReferencedVariables() {
         const byIdTmp = new Map();
         const bySymbolTmp = new Map();
@@ -758,12 +934,6 @@ export class ArgumentEngine {
             bySymbol,
         };
     }
-    /**
-     * Validates that this argument is structurally ready for evaluation:
-     * a conclusion must be set, all role references must point to existing
-     * premises, variable ID/symbol mappings must be consistent, and every
-     * premise must be individually evaluable.
-     */
     validateEvaluability() {
         const issues = [];
         if (this.conclusionPremiseId === undefined) {
@@ -814,21 +984,44 @@ export class ArgumentEngine {
             const premiseValidation = premise.validateEvaluability();
             issues.push(...premiseValidation.issues);
         }
+        // Source validation
+        for (const assoc of this.sourceManager.getAllVariableSourceAssociations()) {
+            if (!this.variables.hasVariable(assoc.variableId)) {
+                issues.push(makeErrorIssue({
+                    code: "SOURCE_VARIABLE_ASSOCIATION_INVALID_VARIABLE",
+                    message: `Variable-source association "${assoc.id}" references non-existent variable "${assoc.variableId}".`,
+                }));
+            }
+        }
+        for (const assoc of this.sourceManager.getAllExpressionSourceAssociations()) {
+            const premise = this.premises.get(assoc.premiseId);
+            if (!premise) {
+                issues.push(makeErrorIssue({
+                    code: "SOURCE_EXPRESSION_ASSOCIATION_INVALID_PREMISE",
+                    message: `Expression-source association "${assoc.id}" references non-existent premise "${assoc.premiseId}".`,
+                }));
+            }
+            else if (!premise.getExpression(assoc.expressionId)) {
+                issues.push(makeErrorIssue({
+                    code: "SOURCE_EXPRESSION_ASSOCIATION_INVALID_EXPRESSION",
+                    message: `Expression-source association "${assoc.id}" references non-existent expression "${assoc.expressionId}" in premise "${assoc.premiseId}".`,
+                }));
+            }
+        }
+        // Orphaned sources (warning, not error)
+        for (const source of this.sourceManager.getSources()) {
+            const assocs = this.sourceManager.getAssociationsForSource(source.id);
+            if (assocs.variable.length === 0 &&
+                assocs.expression.length === 0) {
+                issues.push({
+                    severity: "warning",
+                    code: "SOURCE_ORPHANED",
+                    message: `Source "${source.id}" has no associations.`,
+                });
+            }
+        }
         return makeValidationResult(issues);
     }
-    /**
-     * Evaluates the argument under a three-valued expression assignment.
-     *
-     * Variables may be `true`, `false`, or `null` (unknown). Expressions
-     * listed in `rejectedExpressionIds` evaluate to `false` (children
-     * skipped). All result flags (`isAdmissibleAssignment`,
-     * `allSupportingPremisesTrue`, `conclusionTrue`, `isCounterexample`,
-     * `preservesTruthUnderAssignment`) are three-valued: `null` means
-     * the result is indeterminate due to unknown variable values.
-     *
-     * Returns `{ ok: false }` with validation details if the argument is
-     * not structurally evaluable.
-     */
     evaluate(assignment, options) {
         const validateFirst = options?.validateFirst ?? true;
         if (validateFirst) {
@@ -922,16 +1115,6 @@ export class ArgumentEngine {
             };
         }
     }
-    /**
-     * Enumerates all 2^n variable assignments and checks for counterexamples.
-     *
-     * A counterexample is an admissible assignment where all supporting
-     * premises are true but the conclusion is false. The argument is valid
-     * if no counterexamples exist.
-     *
-     * Supports early termination (`firstCounterexample` mode) and
-     * configurable limits on variables and assignments checked.
-     */
     checkValidity(options) {
         const validateFirst = options?.validateFirst ?? true;
         if (validateFirst) {