@proposit/proposit-core 0.10.0 → 0.11.0

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

@@ -0,0 +1,155 @@
+import { type TCoreArgument, type TCoreLogicalOperatorType, type TCorePremise, type TCorePropositionalExpression, type TCorePropositionalVariable, type TOptionalChecksum, type TClaimBoundVariable } from "../schemata/index.js";
+import { PremiseEngine, type TPremiseEngineSnapshot } from "./premise-engine.js";
+import { VariableManager } from "./variable-manager.js";
+import { type TLogicEngineOptions } from "./argument-engine.js";
+/**
+ * Minimal structural interface needed by `populateFromCitations`. Using a
+ * structural type rather than the concrete `ArgumentEngine<…>` class prevents
+ * generic-parameter variance errors when the caller uses default type params.
+ */
+export type TVariableMaterializer = {
+    ensureClaimBoundVariable(claimId: string): TClaimBoundVariable;
+};
+import { type TGrammarConfig } from "../types/grammar.js";
+import type { TExpressionInput, TExpressionWithoutPosition, TExpressionUpdate } from "./expression-manager.js";
+import type { TCoreMutationResult } from "../types/mutation.js";
+import type { ClaimCitationLibrary } from "./claim-citation-library.js";
+/**
+ * A managed engine for derivation premises that enforces structural rules
+ * from the v0.11.0 spec on construction and on snapshot restoration.
+ *
+ * Construction validates the premise type (`DERIVATION_TYPE_MISMATCH` if the
+ * premise isn't `type: "derivation"`). Full expression-tree structural
+ * validation (`DERIVATION_STRUCTURE_INVALID`) runs in `fromSnapshot` — after
+ * expressions are loaded — and will be called from mutation overrides in
+ * Task 6.
+ *
+ * Note: The constructor only validates the premise type, not the expression
+ * tree, because `PremiseEngine` is always constructed before expressions are
+ * loaded (expressions are added separately via mutations or `loadExpressions`).
+ * Structural validation at the end of `fromSnapshot` catches tampered
+ * snapshots, and Task 6 mutation overrides will enforce it on every change.
+ *
+ * The classic `PremiseEngine` is permissive and allows mutations that leave a
+ * derivation premise temporarily or permanently invalid. The managed engine
+ * wraps it for safe, structurally-enforced editing.
+ *
+ * Use `ManagedDerivationPremiseEngine.fromSnapshot(...)` to restore from a
+ * serialized snapshot — the validation pass catches tampered snapshots.
+ */
+export declare class ManagedDerivationPremiseEngine<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable> extends PremiseEngine<TArg, TPremise, TExpr, TVar> {
+    /**
+     * Captured from `config.generateId` (or the default UUID generator) for
+     * use in `populateFromCitations`, which needs to mint new expression IDs.
+     * Stored separately because `PremiseEngine`'s generateId is private.
+     * Not `readonly` because `fromSnapshot` re-injects it after the prototype
+     * upgrade.
+     */
+    private generateIdFn;
+    constructor(premise: TOptionalChecksum<TPremise>, deps: {
+        argument: TOptionalChecksum<TArg>;
+        variables: VariableManager<TVar>;
+        expressionIndex?: Map<string, string>;
+    }, config?: TLogicEngineOptions);
+    /**
+     * Restore a `ManagedDerivationPremiseEngine` from a serialized snapshot,
+     * applying both derivation-type and structural validation. Throws on
+     * tampered or structurally invalid snapshots.
+     *
+     * Delegates to `PremiseEngine.fromSnapshot` for the full restoration logic
+     * (including the private `rebuildVariableIndex` pass), then upgrades the
+     * prototype and validates. TypeScript's static methods do not support
+     * `super`, so the parent is called by name and the result is recast.
+     */
+    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>, grammarConfig?: TGrammarConfig, generateId?: () => string): ManagedDerivationPremiseEngine<TArg, TPremise, TExpr, TVar>;
+    /**
+     * Validate that the wrapped premise has `type === "derivation"`.
+     * @throws InvariantViolationError with code `DERIVATION_TYPE_MISMATCH`
+     */
+    protected assertDerivationType(): void;
+    /**
+     * Validate that the expression tree conforms to the derivation rules from
+     * the v0.11.0 spec (naked-Q or IMPLIES/IFF with Q as consequent).
+     * @throws InvariantViolationError with code `DERIVATION_STRUCTURE_INVALID`
+     */
+    protected assertWellFormed(): void;
+    addExpression(expression: TExpressionInput<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    appendExpression(parentId: string | null, expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    updateExpression(expressionId: string, updates: TExpressionUpdate): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    removeExpression(expressionId: string, deleteSubtree: boolean): TCoreMutationResult<TExpr | undefined, TExpr, TVar, TPremise, TArg>;
+    insertExpression(expression: TExpressionInput<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    toggleNegation(expressionId: string, extraFields?: Partial<TExpr>): TCoreMutationResult<TExpr | null, TExpr, TVar, TPremise, TArg>;
+    wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
+    changeOperator(expressionId: string, newOperator: TCoreLogicalOperatorType, sourceChildId?: string, targetChildId?: string, extraFields?: Partial<TExpr>): TCoreMutationResult<TExpr | null, TExpr, TVar, TPremise, TArg>;
+    normalizeExpressions(): TCoreMutationResult<void, TExpr, TVar, TPremise, TArg>;
+    loadExpressions(expressions: TExpressionInput<TExpr>[]): void;
+    /**
+     * One-shot snapshot helper that builds the antecedent of this derivation
+     * premise from the current global citations of the derived claim.
+     *
+     * Behavior by citation count:
+     *   - n = 0: no change. Premise stays in its current form (typically
+     *     naked-Q, indicating "no support given").
+     *   - n = 1: produces `IMPLIES(VariableExpression(S1), VariableExpression(Q))`.
+     *   - n ≥ 2: produces `IMPLIES(OR(VariableExpression(S1), …,
+     *     VariableExpression(Sn)), VariableExpression(Q))`.
+     *
+     * Materializes a claim-bound variable for each cited source via
+     * `argumentEngine.ensureClaimBoundVariable(citation.sourceClaimId)`.
+     *
+     * **Tree construction approach:** Mutations are performed via `super.*`
+     * calls, bypassing this class's overrides (which call `assertWellFormed()`
+     * after every mutation and would reject intermediate states during
+     * multi-step construction). For n ≥ 2 the grammar is temporarily switched
+     * to `PERMISSIVE_GRAMMAR_CONFIG` so that the OR operator can sit directly
+     * under IMPLIES without triggering an auto-inserted formula buffer. The
+     * grammar is restored and `assertWellFormed()` is called at the end to
+     * validate the final state.
+     *
+     * @throws InvariantViolationError(DERIVATION_ANTECEDENT_NON_EMPTY) when the
+     *         derivation premise already has a non-empty antecedent (i.e., the
+     *         root is `implies`/`iff` with a position-0 child). The caller
+     *         decides whether to delete and re-create the premise.
+     *
+     * @since 0.11.0
+     */
+    populateFromCitations(citationLib: ClaimCitationLibrary, argumentEngine: TVariableMaterializer): void;
+    /**
+     * Returns the ID of the consequent expression, or `undefined` if the tree
+     * has no root yet.
+     *
+     * - Naked form (root is a variable expression): the root IS the consequent.
+     * - Implication/biconditional form (root is `implies`/`iff`): the position-1
+     *   child of the root is the consequent.
+     */
+    private getConsequentExpressionId;
+    /**
+     * Reject an `insertExpression` call that would place a new node into the
+     * consequent slot of the root `implies`/`iff`.
+     *
+     * Detection is by parentId + position on the input: we block when
+     * `expression.parentId === rootId` AND `expression.position >= consequent.position`.
+     * For `implies`/`iff` the consequent sits at position 1, so this blocks
+     * insertions into position 1 (which would displace the consequent) and
+     * positions beyond (which would exceed arity 2). Insertions at position 0
+     * (antecedent slot) pass through.
+     */
+    private assertNotConsequentSlot;
+    /**
+     * Reject `removeExpression` and `toggleNegation` calls on the consequent
+     * expression.
+     */
+    private assertNotConsequentExpression;
+    /**
+     * Reject `updateExpression` calls that change the consequent's `variableId`
+     * or `type`.
+     */
+    private assertConsequentNotMutated;
+    /**
+     * Reject `changeOperator` calls that would swap the root `implies`/`iff`
+     * to a non-implication operator (`and`, `or`, `not`).
+     */
+    private assertRootOperatorChangeValid;
+}
+//# sourceMappingURL=managed-derivation-premise-engine.d.ts.map

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

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