@polintpro/proposit-core 0.3.0 → 0.4.0

package/dist/lib/core/premise-engine.d.ts

@@ -1,16 +1,18 @@
-import type { TCoreArgument, TCorePremise, TCorePropositionalExpression, TCorePropositionalVariable, TOptionalChecksum } from "../schemata/index.js";
+import type { TCoreArgument, TCorePremise, TCorePropositionalExpression, TCorePropositionalVariable, TOptionalChecksum, TCoreSource, TCoreExpressionSourceAssociation } from "../schemata/index.js";
 import type { TCoreExpressionAssignment, TCorePremiseEvaluationResult, TCoreValidationResult } from "../types/evaluation.js";
 import type { TCoreMutationResult } from "../types/mutation.js";
 import type { TLogicEngineOptions } from "./argument-engine.js";
 import type { TExpressionInput, TExpressionManagerSnapshot, TExpressionWithoutPosition, TExpressionUpdate } from "./expression-manager.js";
 import { VariableManager } from "./variable-manager.js";
+import type { SourceManager } from "./source-manager.js";
+import type { TExpressionMutations, TExpressionQueries, TVariableReferences, TPremiseClassification, TPremiseEvaluation, TPremiseLifecycle, TPremiseIdentity, TDisplayable, TChecksummable } from "./interfaces/index.js";
 export type TPremiseEngineSnapshot<TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression> = {
     premise: TOptionalChecksum<TPremise>;
     rootExpressionId?: string;
     expressions: TExpressionManagerSnapshot<TExpr>;
     config?: TLogicEngineOptions;
 };
-export declare class PremiseEngine<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable> {
+export declare class PremiseEngine<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource> implements TExpressionMutations<TArg, TPremise, TExpr, TVar, TSource>, TExpressionQueries<TExpr>, TVariableReferences<TArg, TPremise, TExpr, TVar, TSource>, TPremiseClassification, TPremiseEvaluation, TPremiseLifecycle<TPremise, TExpr>, TPremiseIdentity<TArg, TPremise, TExpr, TVar, TSource>, TDisplayable, TChecksummable {
     private premise;
     private rootExpressionId;
     private variables;
@@ -21,182 +23,47 @@ export declare class PremiseEngine<TArg extends TCoreArgument = TCoreArgument, T
     private checksumDirty;
     private cachedChecksum;
     private expressionIndex?;
+    private sourceManager?;
     private onMutate?;
     constructor(premise: TOptionalChecksum<TPremise>, deps: {
         argument: TOptionalChecksum<TArg>;
         variables: VariableManager<TVar>;
         expressionIndex?: Map<string, string>;
+        sourceManager?: SourceManager<TSource>;
     }, config?: TLogicEngineOptions);
     setOnMutate(callback: (() => void) | undefined): void;
-    /**
-     * Deletes all expressions that reference the given variable ID,
-     * including their subtrees. Operator collapse runs after each removal.
-     * Returns all removed expressions in the changeset.
-     */
-    deleteExpressionsUsingVariable(variableId: string): TCoreMutationResult<TExpr[], TExpr, TVar, TPremise, TArg>;
-    /**
-     * Adds an expression to this premise's tree.
-     *
-     * If the expression has `parentId: null` it becomes the root; only one
-     * root is permitted per premise.  If `parentId` is non-null the parent
-     * must already exist within this premise.
-     *
-     * All other structural rules (`implies`/`iff` root-only, child limits,
-     * position uniqueness) are enforced by the underlying `ExpressionManager`.
-     *
-     * @throws If the premise already has a root expression and this one is also a root.
-     * @throws If the expression's parent does not exist in this premise.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     * @throws If the expression does not belong to this argument.
-     */
-    addExpression(expression: TExpressionInput<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Adds an expression as the last child of the given parent, with
-     * position computed automatically.
-     *
-     * If `parentId` is `null`, the expression becomes the root.
-     *
-     * @throws If the premise already has a root and parentId is null.
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
-    appendExpression(parentId: string | null, expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Adds an expression immediately before or after an existing sibling,
-     * with position computed automatically.
-     *
-     * @throws If the sibling does not exist in this premise.
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
-    addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Updates mutable fields of an existing expression in this premise.
-     *
-     * Only `position`, `variableId`, and `operator` may be updated. Structural
-     * fields (`id`, `parentId`, `type`, `argumentId`, `argumentVersion`,
-     * `checksum`) are forbidden — enforced by the underlying
-     * `ExpressionManager`.
-     *
-     * If `variableId` changes, the internal `expressionsByVariableId` index is
-     * updated so that cascade deletion (`deleteExpressionsUsingVariable`) stays
-     * correct.
-     *
-     * @throws If the expression does not exist in this premise.
-     * @throws If `variableId` references a non-existent variable.
-     */
-    updateExpression(expressionId: string, updates: TExpressionUpdate): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Removes an expression and its entire descendant subtree, then collapses
-     * any ancestor operators with fewer than two children (same semantics as
-     * before).  Returns the removed root expression, or `undefined` if not
-     * found.
-     *
-     * `rootExpressionId` is recomputed after every removal because operator
-     * collapse can silently promote a new expression into the root slot.
-     */
-    removeExpression(expressionId: string, deleteSubtree: boolean): TCoreMutationResult<TExpr | undefined, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Splices a new expression between existing nodes in the tree.  The new
-     * expression inherits the tree slot of the anchor node
-     * (`leftNodeId ?? rightNodeId`).
-     *
-     * `rootExpressionId` is recomputed after every insertion because the
-     * anchor may have been the root.
-     *
-     * See `ArgumentEngine.insertExpression` for the full contract; the same
-     * rules apply here.
-     *
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
-    insertExpression(expression: TExpressionInput<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Wraps an existing expression with a new operator and a new sibling
-     * expression in a single atomic operation.
-     *
-     * The operator takes the existing node's slot in the tree. Both the
-     * existing node and the new sibling become children of the operator.
-     *
-     * Exactly one of `leftNodeId` / `rightNodeId` must be provided — it
-     * identifies the existing node and which child slot it occupies.
-     * The new sibling fills the other slot.
-     *
-     * @throws If the expression does not belong to this argument.
-     * @throws If the new sibling is a variable reference and the variable has not been registered.
-     */
-    wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
-    /**
-     * Returns an expression by ID, or `undefined` if not found in this
-     * premise.
-     */
+    deleteExpressionsUsingVariable(variableId: string): TCoreMutationResult<TExpr[], TExpr, TVar, TPremise, TArg, TSource>;
+    addExpression(expression: TExpressionInput<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    appendExpression(parentId: string | null, expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    updateExpression(expressionId: string, updates: TExpressionUpdate): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    removeExpression(expressionId: string, deleteSubtree: boolean): TCoreMutationResult<TExpr | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    insertExpression(expression: TExpressionInput<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    addExpressionSourceAssociation(sourceId: string, expressionId: string): TCoreMutationResult<TCoreExpressionSourceAssociation, TExpr, TVar, TPremise, TArg, TSource>;
+    removeExpressionSourceAssociation(associationId: string): TCoreMutationResult<TCoreExpressionSourceAssociation | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    getSourceAssociationsForExpression(expressionId: string): TCoreExpressionSourceAssociation[];
     getExpression(id: string): TExpr | undefined;
     getId(): string;
     getExtras(): Record<string, unknown>;
-    setExtras(extras: Record<string, unknown>): TCoreMutationResult<Record<string, unknown>, TExpr, TVar, TPremise, TArg>;
+    setExtras(extras: Record<string, unknown>): TCoreMutationResult<Record<string, unknown>, TExpr, TVar, TPremise, TArg, TSource>;
     getRootExpressionId(): string | undefined;
     getRootExpression(): TExpr | undefined;
-    /**
-     * Returns all argument-level variables (from the shared VariableManager)
-     * sorted by ID. Since the VariableManager is shared across all premises,
-     * this returns every registered variable — not just those referenced by
-     * expressions in this premise.
-     */
     getVariables(): TVar[];
     getExpressions(): TExpr[];
     getChildExpressions(parentId: string | null): TExpr[];
-    /**
-     * Returns `true` if the root expression is an `implies` or `iff` operator,
-     * meaning this premise expresses a logical inference relationship.
-     */
     isInference(): boolean;
-    /**
-     * Returns `true` if this premise does not have an inference operator at its
-     * root (i.e. it is a constraint premise).  Equivalent to `!isInference()`.
-     */
     isConstraint(): boolean;
     validateEvaluability(): TCoreValidationResult;
-    /**
-     * Evaluates the premise under a three-valued expression assignment.
-     *
-     * Variable values are looked up in `assignment.variables` using Kleene
-     * three-valued logic (`null` = unknown). Missing variables default to `null`.
-     * Expressions listed in `assignment.rejectedExpressionIds` evaluate to
-     * `false` and their children are not evaluated.
-     *
-     * For inference premises (`implies`/`iff`), an `inferenceDiagnostic` is
-     * computed with three-valued fields unless the root is rejected.
-     */
     evaluate(assignment: TCoreExpressionAssignment, options?: {
         strictUnknownKeys?: boolean;
         requireExactCoverage?: boolean;
     }): TCorePremiseEvaluationResult;
-    /**
-     * Returns a human-readable string of this premise's expression tree using
-     * standard logical notation (∧ ∨ ¬ → ↔).  Missing operands are rendered
-     * as `(?)`.  Returns an empty string when the premise has no expressions.
-     */
     toDisplayString(): string;
-    /**
-     * Returns the set of variable IDs referenced by expressions in this premise.
-     * Only variables that appear in `type: "variable"` expression nodes are
-     * included — not all variables in the shared VariableManager.
-     */
     getReferencedVariableIds(): Set<string>;
-    /**
-     * Returns a serializable TPremise representation of this premise.
-     * Contains only premise identity/metadata and checksum — use
-     * getRootExpressionId(), getExpressions(), getReferencedVariableIds()
-     * for runtime state.
-     */
     toPremiseData(): TPremise;
-    /**
-     * Returns a premise-level checksum combining all entity checksums.
-     * Computed lazily -- only recalculated when state has changed.
-     */
     checksum(): string;
     private computeChecksum;
-    /** Invalidate the cached checksum so the next call recomputes it. */
     markDirty(): void;
     /**
      * Re-reads the single root from ExpressionManager after any operation
@@ -207,10 +74,9 @@ export declare class PremiseEngine<TArg extends TCoreArgument = TCoreArgument, T
     private assertBelongsToArgument;
     private renderExpression;
     private operatorSymbol;
-    /** Returns a serializable snapshot of the premise's owned state. */
     snapshot(): TPremiseEngineSnapshot<TPremise, TExpr>;
     /** Creates a new PremiseEngine from a previously captured snapshot. */
-    static fromSnapshot<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable>(snapshot: TPremiseEngineSnapshot<TPremise, TExpr>, argument: TOptionalChecksum<TArg>, variables: VariableManager<TVar>, expressionIndex?: Map<string, string>): PremiseEngine<TArg, TPremise, TExpr, TVar>;
+    static fromSnapshot<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource>(snapshot: TPremiseEngineSnapshot<TPremise, TExpr>, argument: TOptionalChecksum<TArg>, variables: VariableManager<TVar>, expressionIndex?: Map<string, string>, sourceManager?: SourceManager<TSource>): PremiseEngine<TArg, TPremise, TExpr, TVar, TSource>;
     private syncExpressionIndex;
     private rebuildVariableIndex;
 }

package/dist/lib/core/premise-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"premise-engine.d.ts","sourceRoot":"","sources":["../../../src/lib/core/premise-engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"premise-engine.d.ts","sourceRoot":"","sources":["../../../src/lib/core/premise-engine.ts"],"names":[],"mappings":"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"}

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { DefaultMap } from "../utils/default-map.js";
 import { sortedCopyById, sortedUnique } from "../utils/collections.js";
 import { kleeneAnd, kleeneIff, kleeneImplies, kleeneNot, kleeneOr, } from "./evaluation/kleene.js";
@@ -18,6 +19,7 @@ export class PremiseEngine {
     checksumDirty = true;
     cachedChecksum;
     expressionIndex;
+    sourceManager;
     onMutate;
     constructor(premise, deps, config) {
         this.premise = { ...premise };
@@ -28,15 +30,11 @@ export class PremiseEngine {
         this.expressions = new ExpressionManager(config);
         this.expressionsByVariableId = new DefaultMap(() => new Set());
         this.expressionIndex = deps.expressionIndex;
+        this.sourceManager = deps.sourceManager;
     }
     setOnMutate(callback) {
         this.onMutate = callback;
     }
-    /**
-     * Deletes all expressions that reference the given variable ID,
-     * including their subtrees. Operator collapse runs after each removal.
-     * Returns all removed expressions in the changeset.
-     */
     deleteExpressionsUsingVariable(variableId) {
         const expressionIds = this.expressionsByVariableId.get(variableId);
         if (expressionIds.size === 0) {
@@ -62,6 +60,17 @@ export class PremiseEngine {
                         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);
+                    }
+                }
             }
             // Expressions in the collector already have checksums attached
             // (from ExpressionManager which stores expressions with checksums).
@@ -82,21 +91,6 @@ export class PremiseEngine {
             throw e;
         }
     }
-    /**
-     * Adds an expression to this premise's tree.
-     *
-     * If the expression has `parentId: null` it becomes the root; only one
-     * root is permitted per premise.  If `parentId` is non-null the parent
-     * must already exist within this premise.
-     *
-     * All other structural rules (`implies`/`iff` root-only, child limits,
-     * position uniqueness) are enforced by the underlying `ExpressionManager`.
-     *
-     * @throws If the premise already has a root expression and this one is also a root.
-     * @throws If the expression's parent does not exist in this premise.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     * @throws If the expression does not belong to this argument.
-     */
     addExpression(expression) {
         this.assertBelongsToArgument(expression.argumentId, expression.argumentVersion);
         if (expression.type === "variable" &&
@@ -140,16 +134,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Adds an expression as the last child of the given parent, with
-     * position computed automatically.
-     *
-     * If `parentId` is `null`, the expression becomes the root.
-     *
-     * @throws If the premise already has a root and parentId is null.
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
     appendExpression(parentId, expression) {
         this.assertBelongsToArgument(expression.argumentId, expression.argumentVersion);
         if (expression.type === "variable" &&
@@ -191,14 +175,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Adds an expression immediately before or after an existing sibling,
-     * with position computed automatically.
-     *
-     * @throws If the sibling does not exist in this premise.
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
     addExpressionRelative(siblingId, relativePosition, expression) {
         this.assertBelongsToArgument(expression.argumentId, expression.argumentVersion);
         if (expression.type === "variable" &&
@@ -230,21 +206,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Updates mutable fields of an existing expression in this premise.
-     *
-     * Only `position`, `variableId`, and `operator` may be updated. Structural
-     * fields (`id`, `parentId`, `type`, `argumentId`, `argumentVersion`,
-     * `checksum`) are forbidden — enforced by the underlying
-     * `ExpressionManager`.
-     *
-     * If `variableId` changes, the internal `expressionsByVariableId` index is
-     * updated so that cascade deletion (`deleteExpressionsUsingVariable`) stays
-     * correct.
-     *
-     * @throws If the expression does not exist in this premise.
-     * @throws If `variableId` references a non-existent variable.
-     */
     updateExpression(expressionId, updates) {
         const existing = this.expressions.getExpression(expressionId);
         if (!existing) {
@@ -285,15 +246,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Removes an expression and its entire descendant subtree, then collapses
-     * any ancestor operators with fewer than two children (same semantics as
-     * before).  Returns the removed root expression, or `undefined` if not
-     * found.
-     *
-     * `rootExpressionId` is recomputed after every removal because operator
-     * collapse can silently promote a new expression into the root slot.
-     */
     removeExpression(expressionId, deleteSubtree) {
         // Snapshot the expression before removal (for result).
         const snapshot = this.expressions.getExpression(expressionId);
@@ -332,6 +284,21 @@ export class PremiseEngine {
             }
             this.syncRootExpressionId();
             this.markDirty();
+            // Cascade: remove source associations for all removed expressions
+            if (this.sourceManager) {
+                const removedExprs = collector.toChangeset().expressions;
+                if (removedExprs) {
+                    for (const expr of removedExprs.removed) {
+                        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);
+                        }
+                    }
+                }
+            }
             const changes = collector.toChangeset();
             this.syncExpressionIndex(changes);
             this.onMutate?.();
@@ -344,20 +311,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Splices a new expression between existing nodes in the tree.  The new
-     * expression inherits the tree slot of the anchor node
-     * (`leftNodeId ?? rightNodeId`).
-     *
-     * `rootExpressionId` is recomputed after every insertion because the
-     * anchor may have been the root.
-     *
-     * See `ArgumentEngine.insertExpression` for the full contract; the same
-     * rules apply here.
-     *
-     * @throws If the expression does not belong to this argument.
-     * @throws If the expression is a variable reference and the variable has not been registered.
-     */
     insertExpression(expression, leftNodeId, rightNodeId) {
         this.assertBelongsToArgument(expression.argumentId, expression.argumentVersion);
         if (expression.type === "variable" &&
@@ -387,20 +340,6 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Wraps an existing expression with a new operator and a new sibling
-     * expression in a single atomic operation.
-     *
-     * The operator takes the existing node's slot in the tree. Both the
-     * existing node and the new sibling become children of the operator.
-     *
-     * Exactly one of `leftNodeId` / `rightNodeId` must be provided — it
-     * identifies the existing node and which child slot it occupies.
-     * The new sibling fills the other slot.
-     *
-     * @throws If the expression does not belong to this argument.
-     * @throws If the new sibling is a variable reference and the variable has not been registered.
-     */
     wrapExpression(operator, newSibling, leftNodeId, rightNodeId) {
         this.assertBelongsToArgument(operator.argumentId, operator.argumentVersion);
         this.assertBelongsToArgument(newSibling.argumentId, newSibling.argumentVersion);
@@ -431,10 +370,70 @@ export class PremiseEngine {
             this.expressions.setCollector(null);
         }
     }
-    /**
-     * Returns an expression by ID, or `undefined` if not found in this
-     * premise.
-     */
+    // -------------------------------------------------------------------------
+    // Source association convenience methods
+    // -------------------------------------------------------------------------
+    addExpressionSourceAssociation(sourceId, expressionId) {
+        if (!this.sourceManager) {
+            throw new Error("No SourceManager available.");
+        }
+        if (!this.sourceManager.getSource(sourceId)) {
+            throw new Error(`Source "${sourceId}" does not exist.`);
+        }
+        if (!this.expressions.getExpression(expressionId)) {
+            throw new Error(`Expression "${expressionId}" does not exist in premise "${this.premise.id}".`);
+        }
+        const assoc = {
+            id: randomUUID(),
+            sourceId,
+            expressionId,
+            premiseId: this.premise.id,
+            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();
+        this.onMutate?.();
+        return { result: assocWithChecksum, changes: collector.toChangeset() };
+    }
+    removeExpressionSourceAssociation(associationId) {
+        if (!this.sourceManager) {
+            return { result: undefined, changes: {} };
+        }
+        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();
+        this.onMutate?.();
+        return {
+            result: removalResult.removedExpressionAssociations[0],
+            changes: collector.toChangeset(),
+        };
+    }
+    getSourceAssociationsForExpression(expressionId) {
+        if (!this.sourceManager) {
+            return [];
+        }
+        return this.sourceManager.getAssociationsForExpression(expressionId);
+    }
     getExpression(id) {
         return this.expressions.getExpression(id);
     }
@@ -469,12 +468,6 @@ export class PremiseEngine {
         }
         return this.expressions.getExpression(this.rootExpressionId);
     }
-    /**
-     * Returns all argument-level variables (from the shared VariableManager)
-     * sorted by ID. Since the VariableManager is shared across all premises,
-     * this returns every registered variable — not just those referenced by
-     * expressions in this premise.
-     */
     getVariables() {
         return sortedCopyById(this.variables.toArray());
     }
@@ -484,19 +477,11 @@ export class PremiseEngine {
     getChildExpressions(parentId) {
         return this.expressions.getChildExpressions(parentId);
     }
-    /**
-     * Returns `true` if the root expression is an `implies` or `iff` operator,
-     * meaning this premise expresses a logical inference relationship.
-     */
     isInference() {
         const root = this.getRootExpression();
         return (root?.type === "operator" &&
             (root.operator === "implies" || root.operator === "iff"));
     }
-    /**
-     * Returns `true` if this premise does not have an inference operator at its
-     * root (i.e. it is a constraint premise).  Equivalent to `!isInference()`.
-     */
     isConstraint() {
         return !this.isInference();
     }
@@ -607,17 +592,6 @@ export class PremiseEngine {
         }
         return makeValidationResult(issues);
     }
-    /**
-     * Evaluates the premise under a three-valued expression assignment.
-     *
-     * Variable values are looked up in `assignment.variables` using Kleene
-     * three-valued logic (`null` = unknown). Missing variables default to `null`.
-     * Expressions listed in `assignment.rejectedExpressionIds` evaluate to
-     * `false` and their children are not evaluated.
-     *
-     * For inference premises (`implies`/`iff`), an `inferenceDiagnostic` is
-     * computed with three-valued fields unless the root is rejected.
-     */
     evaluate(assignment, options) {
         const validation = this.validateEvaluability();
         if (!validation.ok) {
@@ -746,22 +720,12 @@ export class PremiseEngine {
             inferenceDiagnostic,
         };
     }
-    /**
-     * Returns a human-readable string of this premise's expression tree using
-     * standard logical notation (∧ ∨ ¬ → ↔).  Missing operands are rendered
-     * as `(?)`.  Returns an empty string when the premise has no expressions.
-     */
     toDisplayString() {
         if (this.rootExpressionId === undefined) {
             return "";
         }
         return this.renderExpression(this.rootExpressionId);
     }
-    /**
-     * Returns the set of variable IDs referenced by expressions in this premise.
-     * Only variables that appear in `type: "variable"` expression nodes are
-     * included — not all variables in the shared VariableManager.
-     */
     getReferencedVariableIds() {
         const ids = new Set();
         for (const expr of this.expressions.toArray()) {
@@ -771,22 +735,12 @@ export class PremiseEngine {
         }
         return ids;
     }
-    /**
-     * Returns a serializable TPremise representation of this premise.
-     * Contains only premise identity/metadata and checksum — use
-     * getRootExpressionId(), getExpressions(), getReferencedVariableIds()
-     * for runtime state.
-     */
     toPremiseData() {
         return {
             ...this.premise,
             checksum: this.checksum(),
         };
     }
-    /**
-     * Returns a premise-level checksum combining all entity checksums.
-     * Computed lazily -- only recalculated when state has changed.
-     */
     checksum() {
         if (this.checksumDirty || this.cachedChecksum === undefined) {
             this.cachedChecksum = this.computeChecksum();
@@ -809,7 +763,6 @@ export class PremiseEngine {
         }
         return computeHash(canonicalSerialize(checksumMap));
     }
-    /** Invalidate the cached checksum so the next call recomputes it. */
     markDirty() {
         this.checksumDirty = true;
     }
@@ -890,7 +843,6 @@ export class PremiseEngine {
                 return "¬";
         }
     }
-    /** Returns a serializable snapshot of the premise's owned state. */
     snapshot() {
         const exprSnapshot = this.expressions.snapshot();
         return {
@@ -904,8 +856,8 @@ export class PremiseEngine {
         };
     }
     /** Creates a new PremiseEngine from a previously captured snapshot. */
-    static fromSnapshot(snapshot, argument, variables, expressionIndex) {
-        const pe = new PremiseEngine(snapshot.premise, { argument, variables, expressionIndex }, snapshot.config);
+    static fromSnapshot(snapshot, argument, variables, expressionIndex, sourceManager) {
+        const pe = new PremiseEngine(snapshot.premise, { argument, variables, expressionIndex, sourceManager }, snapshot.config);
         // Restore expressions from the snapshot
         pe.expressions = ExpressionManager.fromSnapshot(snapshot.expressions);
         // Restore rootExpressionId from snapshot