@proposit/proposit-core 0.8.9

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

@@ -0,0 +1,401 @@
+import type { TCoreArgument, TCoreLogicalOperatorType, TCorePremise, TCorePropositionalExpression, TCorePropositionalVariable } from "../../schemata/index.js";
+import type { TCoreExpressionAssignment, TCorePremiseEvaluationResult, TCoreValidationResult } from "../../types/evaluation.js";
+import type { TInvariantValidationResult } from "../../types/validation.js";
+import type { TCoreMutationResult } from "../../types/mutation.js";
+import type { TExpressionInput, TExpressionWithoutPosition, TExpressionUpdate } from "../expression-manager.js";
+import type { TPremiseEngineSnapshot } from "../premise-engine.js";
+/**
+ * Single-premise expression tree mutations.
+ */
+export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable> {
+    /**
+     * 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. All structural rules (`implies`/`iff`
+     * root-only, child limits, position uniqueness) are enforced.
+     *
+     * When `grammarConfig.autoNormalize` is `true`, operator nesting
+     * violations are auto-corrected by inserting a `formula` buffer between
+     * the parent operator and the non-`not` operator child, rather than
+     * throwing. Auto-normalize is only active for `addExpression`; compound
+     * operations (`insertExpression`, `wrapExpression`) and `removeExpression`
+     * always throw on violations regardless of this flag.
+     *
+     * @param expression - The expression to add, including position and
+     *   parent assignment.
+     * @returns The added expression (with checksum) and changeset.
+     * @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 a non-not operator would become a direct child of another
+     *   operator expression (when `autoNormalize` is `false`).
+     */
+    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.
+     *
+     * @param parentId - The parent expression ID, or `null` for root.
+     * @param expression - The expression to add (position is auto-assigned).
+     * @returns The added expression (with checksum) and changeset.
+     * @throws If the premise already has a root and `parentId` is `null`.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
+     */
+    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.
+     *
+     * @param siblingId - The ID of the existing sibling expression.
+     * @param relativePosition - Whether to insert `"before"` or `"after"`
+     *   the sibling.
+     * @param expression - The expression to add (position is auto-assigned).
+     * @returns The added expression (with checksum) and changeset.
+     * @throws If the sibling does not exist in this premise.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
+     */
+    addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    /**
+     * Updates mutable fields of an existing expression. Only `position`,
+     * `variableId`, and `operator` may be updated.
+     *
+     * @param expressionId - The ID of the expression to update.
+     * @param updates - The fields to update.
+     * @returns The updated expression and changeset.
+     * @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 optionally its entire descendant subtree,
+     * then collapses any ancestor operators with fewer than two children.
+     *
+     * @param expressionId - The ID of the expression to remove.
+     * @param deleteSubtree - Whether to remove all descendants as well.
+     * @returns The removed root expression, or `undefined` if not found.
+     * @throws If removal would promote a non-not operator as a direct
+     *   child of another operator expression.
+     */
+    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`).
+     *
+     * @param expression - The expression to insert, including position and
+     *   parent assignment.
+     * @param leftNodeId - The existing node to become the left child of
+     *   the new expression.
+     * @param rightNodeId - The existing node to become the right child of
+     *   the new expression.
+     * @returns The inserted expression (with checksum) and changeset.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
+     */
+    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
+     * 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.
+     *
+     * @param operator - The new operator expression to wrap with.
+     * @param newSibling - The new sibling expression to add alongside the
+     *   existing node.
+     * @param leftNodeId - The existing node to place as the left child.
+     * @param rightNodeId - The existing node to place as the right child.
+     * @returns The inserted operator (with checksum) and changeset.
+     * @throws If the new sibling is a variable reference and the variable
+     *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
+     */
+    wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    /**
+     * Toggles negation on an expression. If the expression's parent is a
+     * NOT operator, removes the NOT (promoting the expression). Otherwise,
+     * wraps the expression with a new NOT operator.
+     *
+     * @param expressionId - The ID of the expression to toggle negation on.
+     * @param extraFields - Optional additional fields to merge into newly
+     *   created expressions (NOT and formula nodes). Structural fields
+     *   (id, type, operator, parentId, position, premiseId, argumentId,
+     *   argumentVersion) cannot be overridden.
+     * @returns The new NOT expression when adding negation, or `null` when
+     *   removing it, along with the changeset.
+     * @throws If the expression does not exist in this premise.
+     */
+    toggleNegation(expressionId: string, extraFields?: Partial<TExpr>): TCoreMutationResult<TExpr | null, TExpr, TVar, TPremise, TArg>;
+    /**
+     * Changes the operator type of an existing operator expression.
+     *
+     * Handles three structural cases automatically:
+     * - **Simple change:** The operator has exactly 2 children and no merge
+     *   condition. Updates the operator type in-place.
+     * - **Merge:** The operator has exactly 2 children and its parent is the
+     *   same type as `newOperator`. Dissolves the current operator and
+     *   reparents its children under the parent.
+     * - **Split:** The operator has >2 children. Extracts `sourceChildId` and
+     *   `targetChildId` into a new sub-operator of type `newOperator`,
+     *   inserting a formula buffer if required by grammar enforcement.
+     *
+     * @param expressionId  The operator expression to change.
+     * @param newOperator   The target operator type.
+     * @param sourceChildId First child to include in a split (required when >2 children).
+     * @param targetChildId Second child to include in a split (required when >2 children).
+     * @param extraFields   Optional partial expression fields merged into any
+     *                      newly created expressions (formula buffer, new sub-operator).
+     *                      Structural fields (id, type, operator, parentId, position,
+     *                      premiseId, argumentId, argumentVersion) cannot be overridden.
+     * @returns result — For simple change: the updated operator expression.
+     *                   For merge: null (operator was dissolved).
+     *                   For split: the newly created sub-operator expression.
+     *          changes — Full changeset with correct hierarchical checksums.
+     * @throws If the expression does not exist, is not an operator, or is "not".
+     * @throws If >2 children and sourceChildId/targetChildId not provided.
+     * @throws If sourceChildId/targetChildId are not children of expressionId.
+     */
+    changeOperator(expressionId: string, newOperator: TCoreLogicalOperatorType, sourceChildId?: string, targetChildId?: string, extraFields?: Partial<TExpr>): TCoreMutationResult<TExpr | null, TExpr, TVar, TPremise, TArg>;
+    /**
+     * Performs a full normalization sweep on this premise's expression tree.
+     * Collapses unjustified formulas, operators with 0/1 children, and inserts
+     * formula buffers where needed. Works regardless of `autoNormalize` setting.
+     */
+    normalizeExpressions(): TCoreMutationResult<void, TExpr, TVar, TPremise, TArg>;
+}
+/**
+ * Single-premise expression tree reads.
+ */
+export interface TExpressionQueries<TExpr extends TCorePropositionalExpression = TCorePropositionalExpression> {
+    /**
+     * Returns an expression by ID, or `undefined` if not found in this
+     * premise.
+     *
+     * @param id - The expression ID to look up.
+     * @returns The expression entity, or `undefined`.
+     */
+    getExpression(id: string): TExpr | undefined;
+    /**
+     * Returns the ID of the root expression, or `undefined` if the premise
+     * is empty.
+     *
+     * @returns The root expression ID, or `undefined`.
+     */
+    getRootExpressionId(): string | undefined;
+    /**
+     * Returns the root expression, or `undefined` if the premise is empty.
+     *
+     * @returns The root expression entity, or `undefined`.
+     */
+    getRootExpression(): TExpr | undefined;
+    /**
+     * Returns all expressions in this premise.
+     *
+     * @returns An array of expression entities.
+     */
+    getExpressions(): TExpr[];
+    /**
+     * Returns the child expressions of the given parent, sorted by
+     * position.
+     *
+     * @param parentId - The parent expression ID, or `null` for root-level
+     *   children.
+     * @returns An array of child expression entities.
+     */
+    getChildExpressions(parentId: string | null): TExpr[];
+}
+/**
+ * Variable reference queries and cascade deletion.
+ */
+export interface TVariableReferences<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable> {
+    /**
+     * 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.
+     *
+     * @returns An array of variable entities.
+     */
+    getVariables(): TVar[];
+    /**
+     * Returns the set of variable IDs referenced by expressions in this
+     * premise. Only variables that appear in `type: "variable"` expression
+     * nodes are included.
+     *
+     * @returns A Set of referenced variable ID strings.
+     */
+    getReferencedVariableIds(): Set<string>;
+    /**
+     * Deletes all expressions that reference the given variable ID,
+     * including their subtrees. Operator collapse runs after each removal.
+     *
+     * @param variableId - The variable ID whose referencing expressions
+     *   should be removed.
+     * @returns The removed expressions and changeset.
+     */
+    deleteExpressionsUsingVariable(variableId: string): TCoreMutationResult<TExpr[], TExpr, TVar, TPremise, TArg>;
+}
+/**
+ * Premise type classification (inference vs constraint).
+ */
+export interface TPremiseClassification {
+    /**
+     * Returns `true` if the root expression is an `implies` or `iff`
+     * operator, meaning this premise expresses a logical inference
+     * relationship.
+     *
+     * @returns Whether this premise is an inference.
+     */
+    isInference(): boolean;
+    /**
+     * Returns `true` if this premise does not have an inference operator at
+     * its root. Equivalent to `!isInference()`.
+     *
+     * @returns Whether this premise is a constraint.
+     */
+    isConstraint(): boolean;
+}
+/**
+ * Premise-level evaluation: single-assignment evaluation and evaluability
+ * validation.
+ */
+export interface TPremiseEvaluation {
+    /**
+     * Validates that this premise is structurally ready for evaluation.
+     *
+     * @returns A validation result with any issues found.
+     */
+    validateEvaluability(): TCoreValidationResult;
+    /**
+     * Evaluates the premise under a three-valued expression assignment.
+     *
+     * Variable values are looked up using Kleene three-valued logic
+     * (`null` = unknown). Missing variables default to `null`. For
+     * inference premises (`implies`/`iff`), an `inferenceDiagnostic` is
+     * computed with three-valued fields unless the root is rejected.
+     *
+     * @param assignment - The variable assignment and optional rejected
+     *   expression IDs.
+     * @param options - Optional evaluation options.
+     * @param options.strictUnknownKeys - If `true`, unknown variable keys
+     *   in the assignment cause an error.
+     * @param options.requireExactCoverage - If `true`, the assignment must
+     *   cover exactly the referenced variables.
+     * @returns The premise evaluation result.
+     */
+    evaluate(assignment: TCoreExpressionAssignment, options?: {
+        strictUnknownKeys?: boolean;
+        requireExactCoverage?: boolean;
+    }): TCorePremiseEvaluationResult;
+}
+/**
+ * Premise snapshot and mutation callback lifecycle.
+ * Static fromSnapshot factory is class-level only.
+ */
+export interface TPremiseLifecycle<TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression> {
+    /**
+     * Returns a serializable snapshot of the premise's owned state.
+     *
+     * @returns The premise engine snapshot.
+     */
+    snapshot(): TPremiseEngineSnapshot<TPremise, TExpr>;
+    /**
+     * Sets a callback invoked after every mutation, or `undefined` to
+     * clear.
+     *
+     * @param callback - The mutation callback, or `undefined` to remove.
+     */
+    setOnMutate(callback: (() => void) | undefined): void;
+    /**
+     * Sets a callback that checks whether adding a variable-expression to a
+     * premise would create a circular binding. Injected by `ArgumentEngine`
+     * to enable cross-premise cycle detection. If not set, only the direct
+     * check (within the premise itself) runs.
+     *
+     * @param check - A function that returns `true` if adding the variable
+     *   to the premise would create a cycle, or `undefined` to clear.
+     */
+    setCircularityCheck(check: ((variableId: string, premiseId: string) => boolean) | undefined): void;
+    /**
+     * Sets a callback that checks whether a premise-bound variable's target
+     * premise has an empty expression tree. Injected by `ArgumentEngine` to
+     * enable cross-premise validation. Used during `validateEvaluability`.
+     *
+     * @param check - A function that returns `true` if the variable's bound
+     *   premise has no root expression, or `undefined` to clear.
+     */
+    setEmptyBoundPremiseCheck(check: ((variableId: string) => boolean) | undefined): void;
+    /**
+     * Invalidates the cached checksum so the next call recomputes it.
+     */
+    markDirty(): void;
+    /**
+     * Run invariant validation on this premise and its expression tree.
+     */
+    validate(): TInvariantValidationResult;
+    /**
+     * Sets a callback that returns the full set of variable IDs registered
+     * in the argument. Injected by `ArgumentEngine`.
+     *
+     * @param callback - A function returning the set of registered variable
+     *   IDs, or `undefined` to clear.
+     */
+    setVariableIdsCallback(callback: (() => Set<string>) | undefined): void;
+    /**
+     * Sets a callback that runs full argument-level invariant validation.
+     * Injected by `ArgumentEngine` so the premise can delegate to the
+     * argument-level validator.
+     *
+     * @param callback - A function returning the invariant validation result,
+     *   or `undefined` to clear.
+     */
+    setArgumentValidateCallback(callback: (() => TInvariantValidationResult) | undefined): void;
+}
+/**
+ * Premise entity identity and metadata access.
+ */
+export interface TPremiseIdentity<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable> {
+    /**
+     * Returns the premise ID.
+     *
+     * @returns The premise ID string.
+     */
+    getId(): string;
+    /**
+     * Returns a serializable premise representation containing only
+     * identity/metadata and checksum. Use `getRootExpressionId()`,
+     * `getExpressions()`, `getReferencedVariableIds()` for runtime state.
+     *
+     * @returns The premise data entity.
+     */
+    toPremiseData(): TPremise;
+    /**
+     * Returns the premise's extra metadata record.
+     *
+     * @returns The extras record.
+     */
+    getExtras(): Record<string, unknown>;
+    /**
+     * Replaces the premise's extra metadata record.
+     *
+     * @param extras - The new extras record.
+     * @returns The previous extras record and changeset.
+     */
+    setExtras(extras: Record<string, unknown>): TCoreMutationResult<Record<string, unknown>, TExpr, TVar, TPremise, TArg>;
+}
+//# sourceMappingURL=premise-engine.interfaces.d.ts.map

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

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=premise-engine.interfaces.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"premise-engine.interfaces.js","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/premise-engine.interfaces.ts"],"names":[],"mappings":""}

package/dist/lib/core/interfaces/shared.interfaces.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An entity that can produce a human-readable display string.
+ */
+export interface TDisplayable {
+    /**
+     * Renders the entity as a human-readable string.
+     *
+     * @returns A human-readable display string.
+     */
+    toDisplayString(): string;
+}
+/**
+ * An entity that can produce hierarchical content checksums:
+ * meta (entity-only), descendant (children), and combined (both).
+ */
+export interface THierarchicalChecksummable<TCollectionName extends string = string> {
+    /** Returns the meta checksum — derived from entity data only. */
+    checksum(): string;
+    /** Returns the descendant checksum — derived from children's combinedChecksums. Null if no children. */
+    descendantChecksum(): string | null;
+    /** Returns the combined checksum — hash(checksum + descendantChecksum), or equals checksum if no descendants. */
+    combinedChecksum(): string;
+    /** Returns the checksum for a named descendant collection. Null if collection is empty. */
+    getCollectionChecksum(name: TCollectionName): string | null;
+    /** Forces recomputation of all dirty checksums in the hierarchy. */
+    flushChecksums(): void;
+}
+//# sourceMappingURL=shared.interfaces.d.ts.map

package/dist/lib/core/interfaces/shared.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/shared.interfaces.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;;OAIG;IACH,eAAe,IAAI,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B,CACvC,eAAe,SAAS,MAAM,GAAG,MAAM;IAEvC,iEAAiE;IACjE,QAAQ,IAAI,MAAM,CAAA;IAClB,wGAAwG;IACxG,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAAA;IACnC,iHAAiH;IACjH,gBAAgB,IAAI,MAAM,CAAA;IAC1B,2FAA2F;IAC3F,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAAA;IAC3D,oEAAoE;IACpE,cAAc,IAAI,IAAI,CAAA;CACzB"}

package/dist/lib/core/interfaces/shared.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shared.interfaces.js.map

package/dist/lib/core/interfaces/shared.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.interfaces.js","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/shared.interfaces.ts"],"names":[],"mappings":""}

package/dist/lib/core/invariant-violation-error.d.ts

@@ -0,0 +1,10 @@
+import type { TInvariantViolation } from "../types/validation.js";
+/**
+ * Thrown when a mutation would leave the system in an invalid state.
+ * Carries the full list of {@link TInvariantViolation} entries that were detected.
+ */
+export declare class InvariantViolationError extends Error {
+    readonly violations: TInvariantViolation[];
+    constructor(violations: TInvariantViolation[]);
+}
+//# sourceMappingURL=invariant-violation-error.d.ts.map

package/dist/lib/core/invariant-violation-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant-violation-error.d.ts","sourceRoot":"","sources":["../../../src/lib/core/invariant-violation-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAEjE;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAC9C,SAAgB,UAAU,EAAE,mBAAmB,EAAE,CAAA;gBAErC,UAAU,EAAE,mBAAmB,EAAE;CAShD"}

package/dist/lib/core/invariant-violation-error.js

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a mutation would leave the system in an invalid state.
+ * Carries the full list of {@link TInvariantViolation} entries that were detected.
+ */
+export class InvariantViolationError extends Error {
+    violations;
+    constructor(violations) {
+        const summary = violations.length === 1
+            ? violations[0].message
+            : `${violations.length} invariant violations detected`;
+        super(summary);
+        this.name = "InvariantViolationError";
+        this.violations = violations;
+    }
+}
+//# sourceMappingURL=invariant-violation-error.js.map

package/dist/lib/core/invariant-violation-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant-violation-error.js","sourceRoot":"","sources":["../../../src/lib/core/invariant-violation-error.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC9B,UAAU,CAAuB;IAEjD,YAAY,UAAiC;QACzC,MAAM,OAAO,GACT,UAAU,CAAC,MAAM,KAAK,CAAC;YACnB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO;YACvB,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,gCAAgC,CAAA;QAC9D,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAChC,CAAC;CACJ"}