@proposit/proposit-core 0.12.3 → 1.0.0

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

@@ -1,6 +1,5 @@
 import { isClaimBound, isPremiseBound, } from "../schemata/index.js";
-import { DEFAULT_GRAMMAR_CONFIG, PERMISSIVE_GRAMMAR_CONFIG, } from "../types/grammar.js";
-import { AXIOM_VARIABLE_ASSIGNMENT_FORBIDDEN, CLAIM_NOT_FOUND, CREATE_DERIVATION_CLAIM_NOT_FOUND, CREATE_DERIVATION_REQUIRES_DERIVED_CLAIM_ID, DERIVATION_STRUCTURE_INVALID_AT_EVALUATION, } from "../types/validation.js";
+import { AXIOM_VARIABLE_ASSIGNMENT_FORBIDDEN, CLAIM_NOT_FOUND, CREATE_DERIVATION_CLAIM_NOT_FOUND, CREATE_DERIVATION_REQUIRES_DERIVED_CLAIM_ID, } from "../types/validation.js";
 import { validateDerivationStructure } from "../utils/derivation-validation.js";
 import { DEFAULT_CHECKSUM_CONFIG, normalizeChecksumConfig, serializeChecksumConfig, } from "../consts.js";
 import { ChangeCollector } from "./change-collector.js";
@@ -8,6 +7,12 @@ import { canonicalSerialize, computeHash, entityChecksum } from "./checksum.js";
 import { evaluateArgument as evaluateArgumentStandalone, checkArgumentValidity as checkArgumentValidityStandalone, } from "./evaluation/argument-evaluation.js";
 import { makeErrorIssue, makeValidationResult, } from "./evaluation/validation.js";
 import { validateArgument as validateArgumentStandalone, validateArgumentAfterPremiseMutation as validateAfterPremiseMutationStandalone, validateArgumentEvaluability as validateArgumentEvaluabilityStandalone, collectArgumentReferencedVariables as collectArgumentReferencedVariablesStandalone, } from "./argument-validation.js";
+import { normalizeArgument } from "../grammar/normalize.js";
+import { runAssistiveNormalization } from "../grammar/auto-normalize.js";
+import { isNakedQDerivationPremise } from "../grammar/naked-q.js";
+import { populateFromGrounding as populateFromGroundingImpl, } from "../grammar/populate-from.js";
+import { removeUnresolvableVariables as removeUnresolvableVariablesImpl, removeOrphanOperators as removeOrphanOperatorsImpl, removeDuplicateDerivationPremises as removeDuplicateDerivationPremisesImpl, dropAxiomsFromMixedAntecedent as dropAxiomsFromMixedAntecedentImpl, } from "../grammar/repair.js";
+import { validate as validateGrammar } from "../grammar/validate.js";
 import { InvariantViolationError } from "./invariant-violation-error.js";
 import { PremiseEngine } from "./premise-engine.js";
 import { VariableManager } from "./variable-manager.js";
@@ -28,9 +33,24 @@ export class ArgumentEngine {
     conclusionPremiseId;
     checksumConfig;
     positionConfig;
-    grammarConfig;
+    engineBehavior;
     generateId;
     restoringFromSnapshot = false;
+    // D2b — re-entrance guard for the AN post-mutation hook. The
+    // `setOnMutate` callbacks (3 sites: createPremise, fromSnapshot,
+    // restoreFromSnapshot) fire `runAssistiveNormalization(this)` after
+    // every successful mutation when `behavior === 'assistive'`. AN
+    // itself mutates premises (removeExpression / reparentExpression /
+    // wrapInFormula), which re-fires `setOnMutate`. Without a guard the
+    // outer mutation would trigger nested AN sweeps. The guard is
+    // toggled by `_beginApplyAN()` / `_endApplyAN()` (see below); the
+    // chokepoint is `applyANToFixedPoint` in
+    // `src/lib/grammar/an-rules.ts`, so both
+    // `runAssistiveNormalization` (post-hook) and `normalizeArgument`
+    // (`engine.normalize()`) are covered by the same gate. The
+    // accessor pair is `beginApplyAN()` / `endApplyAN()` below
+    // (marked `@internal` — not part of the public API).
+    applyingAN = false;
     checksumDirty = true;
     cachedMetaChecksum;
     cachedDescendantChecksum;
@@ -53,7 +73,7 @@ export class ArgumentEngine {
         this.premises = new Map();
         this.checksumConfig = options?.checksumConfig;
         this.positionConfig = options?.positionConfig;
-        this.grammarConfig = options?.grammarConfig;
+        this.engineBehavior = options?.behavior ?? "assistive";
         this.generateId = options?.generateId ?? defaultGenerateId;
         this.variables = new VariableManager({
             checksumConfig: this.checksumConfig,
@@ -159,7 +179,7 @@ export class ArgumentEngine {
         this.suppressPremiseValidation();
         try {
             const result = fn();
-            const validation = this.validate();
+            const validation = this.validateInvariants();
             if (!validation.ok) {
                 this.rollbackInternal(snap);
                 throw new InvariantViolationError(validation.violations);
@@ -295,6 +315,92 @@ export class ArgumentEngine {
             }
         }
     }
+    /**
+     * Current engine behavior setting. Controls whether the
+     * auto-normalization (AN) rule set runs as a post-hook after every
+     * successful Structural mutation. See the JSDoc on
+     * `TLogicEngineOptions.behavior` for the full contract.
+     *
+     * @since 1.0.0
+     */
+    get behavior() {
+        return this.engineBehavior;
+    }
+    /**
+     * Access to the engine's ID generator function. Used by in-package
+     * helpers that build new entity trees and need fresh IDs (e.g. the
+     * `populateFromGrounding` factory in
+     * `src/lib/grammar/populate-from.ts`). The generator is captured
+     * once at construction (default `crypto.randomUUID`) and stays
+     * immutable for the engine's lifetime; this accessor returns the
+     * same function reference on every call.
+     *
+     * Replaces the prior `(engine as unknown as { generateId: () =>
+     * string }).generateId` cast in `populate-from.ts`. The accessor is
+     * marked `@internal` so it is not surfaced in generated API docs /
+     * type bundles — the in-package factory callers are its intended
+     * consumers; external programmatic-construction use cases should
+     * supply their own generator rather than borrowing the engine's.
+     *
+     * @internal
+     * @since 1.0.0
+     */
+    get idGenerator() {
+        return this.generateId;
+    }
+    /**
+     * Switches the engine's behavior at runtime. Going `permissive →
+     * assistive` does **not** auto-run a global `normalize()` pass; the
+     * UI is expected to prompt the user before invoking `normalize()`
+     * explicitly.
+     *
+     * As of v1.0 (Phase D2) behavior is enforced entirely via the AN
+     * post-mutation hook in `runAssistiveNormalization` — the legacy
+     * per-flag `grammarConfig` plumbing that bridged behavior to
+     * premise-level enforcement is gone. Switching `permissive →
+     * assistive` makes the next successful Structural mutation trigger
+     * the AN pass; switching the other direction stops the AN pass
+     * from running until the user opts back in.
+     *
+     * @since 1.0.0
+     */
+    setBehavior(b) {
+        this.engineBehavior = b;
+    }
+    /**
+     * Acquire the AN re-entrance guard. Returns `true` iff the guard
+     * was acquired (i.e. AN is not already running for this engine);
+     * the caller is then obligated to call `endApplyAN()` after the
+     * AN sweep. Returns `false` if AN is already in progress, in
+     * which case the caller short-circuits to avoid nested AN
+     * sweeps.
+     *
+     * Used by `applyANToFixedPoint` in `src/lib/grammar/an-rules.ts`
+     * (the single chokepoint for both `runAssistiveNormalization`
+     * and `normalizeArgument`). The post-mutation hook in
+     * `setOnMutate` calls `runAssistiveNormalization(this)` which
+     * delegates to `applyANToFixedPoint`; AN's own mutations re-fire
+     * `setOnMutate`, which would otherwise recurse. This guard
+     * breaks the recursion.
+     *
+     * @internal
+     * @since 1.0.0
+     */
+    beginApplyAN() {
+        if (this.applyingAN)
+            return false;
+        this.applyingAN = true;
+        return true;
+    }
+    /**
+     * Release the AN re-entrance guard. Pairs with `beginApplyAN()`.
+     *
+     * @internal
+     * @since 1.0.0
+     */
+    endApplyAN() {
+        this.applyingAN = false;
+    }
     getArgument() {
         this.flushChecksums();
         return {
@@ -429,7 +535,6 @@ export class ArgumentEngine {
             }, {
                 checksumConfig: this.checksumConfig,
                 positionConfig: this.positionConfig,
-                grammarConfig: this.grammarConfig,
                 generateId: this.generateId,
             });
             this.premises.set(id, pm);
@@ -441,6 +546,16 @@ export class ArgumentEngine {
                 this.markDirty();
                 this.reactiveDirty.premiseIds.add(id);
                 this.notifySubscribers();
+                // D2b — AN post-mutation hook per spec §5. Skipped
+                // during snapshot restoration (PE.fromSnapshot bypasses
+                // mutations anyway, but the guard is defensive).
+                // `runAssistiveNormalization` is a no-op in permissive
+                // mode; re-entrance from AN's own mutations is guarded
+                // inside `applyANToFixedPoint` via the engine's
+                // `_beginApplyAN()` flag.
+                if (!this.restoringFromSnapshot) {
+                    runAssistiveNormalization(this);
+                }
             });
             const collector = new ChangeCollector();
             collector.addedPremise(pm.toPremiseData());
@@ -813,6 +928,18 @@ export class ArgumentEngine {
     getVariable(variableId) {
         return this.variables.getVariable(variableId);
     }
+    /**
+     * Look up a claim by `(id, version)` in the engine's claim library.
+     * Returns `undefined` if the claim is not present. Exposed for
+     * repair primitives and other tooling that needs to inspect a
+     * claim's `type` discriminator at a particular version pinned by
+     * a claim-bound variable.
+     *
+     * @since 1.0.0
+     */
+    getClaim(claimId, claimVersion) {
+        return this.claimLibrary.get(claimId, claimVersion);
+    }
     hasVariable(variableId) {
         return this.variables.hasVariable(variableId);
     }
@@ -882,27 +1009,144 @@ export class ArgumentEngine {
         return roots;
     }
     /**
-     * Normalizes expression trees across all premises. Collapses unjustified
-     * formulas, operators with 0/1 children, and inserts formula buffers where
-     * needed. Works regardless of `autoNormalize` setting.
+     * Construct (or no-op on) the per-claim derivation premise's
+     * antecedent from a citation lookup. Factory + naked-Q-only:
+     *
+     *  - 0 connections → no-op (naked-Q stays).
+     *  - 1 connection → `IMPLIES(citation-var, Q)`.
+     *  - ≥ 2 connections → `IMPLIES(OR(c1, …, cn), Q)`. In
+     *    `'assistive'` mode the per-mutation AN-1 post-hook inserts a
+     *    formula buffer between IMPLIES and OR; in `'permissive'` the
+     *    OR sits directly under IMPLIES (a P-1 violation surfaces via
+     *    `validate('presentable')`).
+     *
+     * **No throw on already-populated.** Per the Structural-only
+     * mutation throw rule, if the target derivation premise is not in
+     * the naked-Q form the factory returns `{ kind: 'no-op', state:
+     * <existing> }` without mutating. UI/caller is responsible for
+     * explicit user consent + clearing the antecedent via a repair
+     * primitive before re-calling. Preserves the no-changes-without-
+     * consent principle.
+     *
+     * Throws only when no derivation premise exists for the given
+     * `derivedClaimId` (legitimate entity-not-found Structural check).
+     *
+     * @since 1.0.0
      */
-    normalizeAllExpressions() {
-        const merged = {};
-        for (const pe of this.premises.values()) {
-            const { changes } = pe.normalizeExpressions();
-            if (changes.expressions) {
-                merged.expressions ??= { added: [], modified: [], removed: [] };
-                merged.expressions.added.push(...changes.expressions.added);
-                merged.expressions.modified.push(...changes.expressions.modified);
-                merged.expressions.removed.push(...changes.expressions.removed);
-            }
-            if (changes.premises) {
-                merged.premises ??= { added: [], modified: [], removed: [] };
-                merged.premises.modified.push(...changes.premises.modified);
-            }
-        }
-        return { result: undefined, changes: merged };
+    populateFromCitations(derivedClaimId, citationLookup) {
+        return populateFromGroundingImpl(this, derivedClaimId, citationLookup);
+    }
+    /**
+     * Mirror of `populateFromCitations` for axiom connections. Same
+     * factory contract: naked-Q-only, no throw on already-populated.
+     *
+     * @since 1.0.0
+     */
+    populateFromAxioms(derivedClaimId, axiomLookup) {
+        return populateFromGroundingImpl(this, derivedClaimId, axiomLookup);
+    }
+    /**
+     * Repair primitive: resolve E-3 violations by deleting each
+     * unresolvable claim- or premise-bound variable, cascading the
+     * removal across all premises. Returns the violations resolved
+     * (for UX confirmation / undo / "we made N changes" feedback).
+     *
+     * **User-initiated; never auto-runs.** Respects `behavior`: in
+     * `'assistive'` mode, the AN post-hook fires after each cascade
+     * mutation; in `'permissive'` no AN runs.
+     *
+     * @since 1.0.0
+     */
+    removeUnresolvableVariables() {
+        return removeUnresolvableVariablesImpl(this);
+    }
+    /**
+     * Repair primitive: resolve E-1 violations (operators with < 2
+     * children) by running the AN-3 cleanup pass globally. Returns the
+     * violations resolved. The repair is non-meaning-changing — it
+     * only removes empty operators and promotes single-child operators
+     * — but lives alongside `normalize()` so the UI can present a
+     * focused "Remove N orphan operators" action with a precise return
+     * value.
+     *
+     * **User-initiated; never auto-runs.** Bypasses `behavior` —
+     * cleanup runs even in permissive mode (the user has already
+     * accepted the action by clicking the repair button).
+     *
+     * @since 1.0.0
+     */
+    removeOrphanOperators() {
+        return removeOrphanOperatorsImpl(this);
+    }
+    /**
+     * Repair primitive: resolve E-6 violations (claim has > 1
+     * derivation premise) by keeping one premise per `derivedClaimId`
+     * and deleting the rest. Strategy controls which premise is kept:
+     *
+     *  - `'keep-first'` (default): keep the premise with the
+     *    lexicographically smallest id; delete the rest. Deterministic
+     *    and snapshot-stable.
+     *  - `'keep-largest-antecedent'`: keep the premise whose antecedent
+     *    subtree has the most claim-bound variable expressions; tie-break
+     *    by id.
+     *
+     * **User-initiated; never auto-runs.** Respects `behavior`.
+     *
+     * @since 1.0.0
+     */
+    removeDuplicateDerivationPremises(strategy = "keep-first") {
+        return removeDuplicateDerivationPremisesImpl(this, strategy);
+    }
+    /**
+     * Repair primitive: resolve D-3 violations (mixed-grounding
+     * antecedent — axioms + citations in one derivation) by deleting
+     * every axiom-bound variable expression from the offending
+     * antecedent subtree. The remaining citation-bound variables stay,
+     * giving the derivation a homogeneous citation-grounded antecedent.
+     *
+     * **User-initiated; never auto-runs.** Respects `behavior`. In
+     * `'assistive'` mode, AN may collapse a resulting single-child OR
+     * via AN-3; in `'permissive'` the OR may persist with one child
+     * (a downstream D-2 violation — follow up with
+     * `removeOrphanOperators()` if desired).
+     *
+     * @since 1.0.0
+     */
+    dropAxiomsFromMixedAntecedent() {
+        return dropAxiomsFromMixedAntecedentImpl(this);
     }
+    /**
+     * Global normalize pass per spec §6. Runs the AN rule set
+     * (AN-1..AN-4) everywhere it can fire, converging the argument
+     * toward `tier` (defaults to `'presentable'`).
+     *
+     * `normalize` is non-destructive in the logical-meaning sense — it
+     * does not delete variables, change claim references, or modify
+     * operator semantics. Recovery from Evaluable or Derivable violations
+     * requires user intent and is exposed via the repair primitives
+     * (Phase C4).
+     *
+     * In v1.0 every AN rule targets a Presentable invariant, so calls
+     * with `tier` ∈ {'structural', 'evaluable', 'derivable'} are
+     * effectively no-ops. The parameter exists as forward-compatible
+     * API surface for a future submit/finalize gate.
+     *
+     * **Bypasses `behavior`.** `normalize()` is user-initiated (the UI
+     * invokes it after the user confirms a Tidy / Normalize action), so
+     * cleanup runs regardless of whether the engine is in `'assistive'`
+     * or `'permissive'` mode. The engine's `behavior` setting is not
+     * mutated by this call.
+     *
+     * @since 1.0.0
+     */
+    normalize(tier = "presentable") {
+        normalizeArgument(this, tier);
+    }
+    // D2 — `normalizeAllExpressions` was the per-engine wrapper that
+    // delegated to `pe.normalizeExpressions()` on every premise.
+    // Both methods are deleted in D2. Callers migrate to
+    // `engine.normalize(tier?)` (Phase C3), which routes through the
+    // four native AN passes in `src/lib/grammar/an-rules.ts`.
     getRoleState() {
         return {
             ...(this.conclusionPremiseId !== undefined
@@ -966,12 +1210,23 @@ export class ArgumentEngine {
             config: {
                 checksumConfig: serializeChecksumConfig(this.checksumConfig),
                 positionConfig: this.positionConfig,
-                grammarConfig: this.grammarConfig,
+                // `behavior` is intentionally omitted from the snapshot.
+                // Consumers re-supply it at restore time via
+                // `new ArgumentEngine(...)` options or `setBehavior()`;
+                // a restored engine defaults to `'assistive'`. The fork
+                // path (`forkArgumentEngine` / `PropositCore.forkArgument`)
+                // explicitly threads the source engine's `behavior` into
+                // the forked engine's config (see D5 — `fork.ts`), so
+                // fork callers don't lose the setting.
+                //
+                // D2: the legacy `grammarConfig` field is gone — all
+                // P-1 / AN behavior is driven by `engine.behavior` +
+                // the AN post-mutation hook.
             },
         };
     }
     /** Creates a new ArgumentEngine from a previously captured snapshot. */
-    static fromSnapshot(snapshot, claimLibrary, grammarConfig, checksumVerification, generateId) {
+    static fromSnapshot(snapshot, claimLibrary, checksumVerification, generateId) {
         const engine = new ArgumentEngine(snapshot.argument, claimLibrary, snapshot.config
             ? {
                 ...snapshot.config,
@@ -984,7 +1239,7 @@ export class ArgumentEngine {
         engine.restoringFromSnapshot = true;
         // Restore premises first (premise-bound variables reference them)
         for (const premiseSnap of snapshot.premises) {
-            const pe = PremiseEngine.fromSnapshot(premiseSnap, snapshot.argument, engine.variables, engine.expressionIndex, grammarConfig, generateId);
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, snapshot.argument, engine.variables, engine.expressionIndex, generateId);
             engine.premises.set(pe.getId(), pe);
             engine.wireCircularityCheck(pe);
             engine.wireEmptyBoundPremiseCheck(pe);
@@ -995,6 +1250,13 @@ export class ArgumentEngine {
                 engine.markDirty();
                 engine.reactiveDirty.premiseIds.add(premiseId);
                 engine.notifySubscribers();
+                // D2b — AN post-mutation hook per spec §5. See the
+                // matching comment in `createPremise`'s setOnMutate
+                // callback for the re-entrance / snapshot-restore
+                // rationale.
+                if (!engine.restoringFromSnapshot) {
+                    runAssistiveNormalization(engine);
+                }
             });
         }
         // Restore claim-bound variables first, then premise-bound variables
@@ -1017,31 +1279,25 @@ export class ArgumentEngine {
         // Restore conclusion role (don't use setConclusionPremise to avoid auto-assign logic)
         engine.conclusionPremiseId = snapshot.conclusionPremiseId;
         engine.restoringFromSnapshot = false;
-        // Apply the caller's grammarConfig override to the engine and all
-        // premise engines so that validate() and subsequent mutations use the
-        // caller's grammar rules instead of whatever was stored in the snapshot.
-        if (grammarConfig) {
-            engine.grammarConfig = grammarConfig;
-            for (const pe of engine.premises.values()) {
-                pe.setGrammarConfig(grammarConfig);
-            }
-        }
-        // Post-load normalization: only run full normalize when autoNormalize
-        // is `true` (boolean). When it is a granular config object, individual
-        // flags control in-operation behavior — loading should not mutate data.
-        const restoredGrammarConfig = grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
-        if (restoredGrammarConfig.autoNormalize === true) {
-            for (const pe of engine.premises.values()) {
-                pe.normalizeExpressions();
-            }
-        }
+        // C7: No post-load normalization. The snapshot loads as-is; any
+        // lower-tier (Evaluable / Derivable / Presentable) violations
+        // are queryable post-load via `engine.validate(tier)`.
         if (checksumVerification === "strict") {
             engine.flushChecksums();
             ArgumentEngine.verifySnapshotChecksums(engine, snapshot);
         }
-        const validation = engine.validate();
-        if (!validation.ok) {
-            throw new InvariantViolationError(validation.violations);
+        // D2: load-time invariant validation no longer needs the
+        // PERMISSIVE swap — the legacy `EXPR_FORMULA_BETWEEN_OPERATORS_VIOLATED`
+        // check was deleted alongside the rest of `grammarConfig`. P-1
+        // is now surfaced via `engine.validate('presentable')`
+        // post-load. Non-grammar invariants (schema conformance,
+        // reference integrity, conclusion ref, circularity, etc.)
+        // still throw at load time. D4 inlined the
+        // `runLoadTimeValidationCore` wrapper and routes through the
+        // public `validateInvariants()` method.
+        const loadValidation = engine.validateInvariants();
+        if (!loadValidation.ok) {
+            throw new InvariantViolationError(loadValidation.violations);
         }
         return engine;
     }
@@ -1051,19 +1307,14 @@ export class ArgumentEngine {
      * `premiseId` field and loaded in BFS order (roots first, then children
      * of already-added nodes) to satisfy parent-existence requirements.
      */
-    static fromData(argument, claimLibrary, variables, premises, expressions, roles, config, grammarConfig, checksumVerification) {
-        const loadingGrammarConfig = grammarConfig ?? config?.grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
+    static fromData(argument, claimLibrary, variables, premises, expressions, roles, config, checksumVerification) {
         const normalizedConfig = config
             ? {
                 ...config,
                 checksumConfig: normalizeChecksumConfig(config.checksumConfig),
             }
             : undefined;
-        const loadingConfig = {
-            ...normalizedConfig,
-            grammarConfig: loadingGrammarConfig,
-        };
-        const engine = new ArgumentEngine(argument, claimLibrary, loadingConfig);
+        const engine = new ArgumentEngine(argument, claimLibrary, normalizedConfig);
         engine.restoringFromSnapshot = true;
         // Register claim-bound variables first (no dependencies)
         for (const v of variables) {
@@ -1121,24 +1372,24 @@ export class ArgumentEngine {
         if (roles.conclusionPremiseId !== undefined) {
             engine.setConclusionPremise(roles.conclusionPremiseId);
         }
-        // After loading: restore the caller's intended grammar config
-        engine.grammarConfig = config?.grammarConfig;
         engine.restoringFromSnapshot = false;
-        // Post-load normalization: only run full normalize when autoNormalize
-        // is `true` (boolean). Granular config objects skip post-load normalization.
-        const restoredGrammarConfig = config?.grammarConfig ?? DEFAULT_GRAMMAR_CONFIG;
-        if (restoredGrammarConfig.autoNormalize === true) {
-            for (const pe of engine.premises.values()) {
-                pe.normalizeExpressions();
-            }
-        }
+        // C7: No post-load normalization. See the matched note in
+        // `fromSnapshot` above. Load is non-mutating; lower-tier
+        // violations surface via `engine.validate(tier)`. Phase D
+        // removes the legacy grammarConfig parameter entirely.
         if (checksumVerification === "strict") {
             engine.flushChecksums();
             ArgumentEngine.verifyDataChecksums(engine, argument, variables, premises);
         }
-        const validation = engine.validate();
-        if (!validation.ok) {
-            throw new InvariantViolationError(validation.violations);
+        // C7: PERMISSIVE-gated load-time validation (see matched comment
+        // in `fromSnapshot` above). Non-grammar invariants still throw at
+        // load; lower-tier grammar violations surface post-load via
+        // `engine.validate(tier)`. D4 inlined the
+        // `runLoadTimeValidationCore` wrapper and routes through the
+        // public `validateInvariants()` method.
+        const loadValidation = engine.validateInvariants();
+        if (!loadValidation.ok) {
+            throw new InvariantViolationError(loadValidation.violations);
         }
         return engine;
     }
@@ -1253,7 +1504,7 @@ export class ArgumentEngine {
     rollback(snapshot) {
         const preRollbackSnap = this.snapshot();
         this.rollbackInternal(snapshot);
-        const validation = this.validate();
+        const validation = this.validateInvariants();
         if (!validation.ok) {
             this.rollbackInternal(preRollbackSnap);
             throw new InvariantViolationError(validation.violations);
@@ -1263,12 +1514,11 @@ export class ArgumentEngine {
         this.argument = { ...snapshot.argument };
         this.checksumConfig = normalizeChecksumConfig(snapshot.config?.checksumConfig);
         this.positionConfig = snapshot.config?.positionConfig;
-        this.grammarConfig = snapshot.config?.grammarConfig;
         this.variables = VariableManager.fromSnapshot(snapshot.variables);
         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, PERMISSIVE_GRAMMAR_CONFIG);
+            const pe = PremiseEngine.fromSnapshot(premiseSnap, this.argument, this.variables, this.expressionIndex);
             this.premises.set(pe.getId(), pe);
         }
         this.conclusionPremiseId = snapshot.conclusionPremiseId;
@@ -1282,6 +1532,13 @@ export class ArgumentEngine {
                 this.markDirty();
                 this.reactiveDirty.premiseIds.add(premiseId);
                 this.notifySubscribers();
+                // D2b — AN post-mutation hook per spec §5. See the
+                // matching comment in `createPremise`'s setOnMutate
+                // callback for the re-entrance / snapshot-restore
+                // rationale.
+                if (!this.restoringFromSnapshot) {
+                    runAssistiveNormalization(this);
+                }
             });
         }
         this.markDirty();
@@ -1405,9 +1662,85 @@ export class ArgumentEngine {
     validateAfterPremiseMutation() {
         return validateAfterPremiseMutationStandalone(this.asValidationContext());
     }
-    validate() {
+    /**
+     * Four-tier grammar validation per spec §4. Returns the union of
+     * violations from Structural up through `tier` — `'structural'`
+     * returns S-rule violations only, `'evaluable'` returns S + E,
+     * `'derivable'` returns S + E + D, `'presentable'` returns the full
+     * union. Empty array means the argument is at the requested tier
+     * or stricter. Never throws on grammar issues.
+     *
+     * For the legacy pre-1.0 invariant sweep (schema conformance,
+     * reference integrity, ownership, conclusion ref, circularity,
+     * checksums) use {@link validateInvariants} instead. The pre-1.0
+     * no-arg overload of `validate()` was removed in Phase D4.
+     */
+    validate(tier) {
+        return validateGrammar(tier, this.asGrammarValidatorContext());
+    }
+    /**
+     * Legacy invariant sweep — schema conformance, reference integrity,
+     * ownership, conclusion-ref + circularity, checksum stability, and
+     * per-premise validation. Returns a `TInvariantValidationResult`.
+     * Used internally by mutation-rollback and snapshot-load paths and
+     * exposed publicly for library-wide invariant checks (see
+     * `ArgumentLibrary.validate` and `PropositCore.validate`).
+     *
+     * Distinct from {@link validate}, which runs the four-tier grammar
+     * validator (`Structural ⊇ Evaluable ⊇ Derivable ⊇ Presentable`)
+     * and returns a `readonly TViolation[]`. The two are
+     * complementary — grammar tiers cover AST-shape rules; this method
+     * covers schema/reference/structural-bookkeeping invariants that
+     * sit outside the tier hierarchy.
+     *
+     * @since 1.0.0 — replaces the legacy `validate()` no-arg overload
+     *   removed in Phase D4 of the `grammar-tiers/core` branch.
+     */
+    validateInvariants() {
         return validateArgumentStandalone(this.asValidationContext());
     }
+    /**
+     * Construct the pure-data `TValidatorContext` consumed by the
+     * grammar-tier validators. Claims are gathered by walking the
+     * engine's claim-bound variables and looking each one up in the
+     * claim library — the `TClaimLookup` contract doesn't expose
+     * iteration, so we materialize the referenced subset only.
+     */
+    asGrammarValidatorContext() {
+        const argument = this.getArgument();
+        const premises = [];
+        const expressions = [];
+        for (const pe of this.listPremises()) {
+            premises.push(pe.toPremiseData());
+            expressions.push(...pe.getExpressions());
+        }
+        const variables = this.variables.toArray();
+        // Gather referenced claims via claim-bound variables. Duplicate
+        // (id, version) pairs are deduped via a Set on the composite key.
+        const seen = new Set();
+        const claims = [];
+        for (const v of variables) {
+            if (!isClaimBound(v))
+                continue;
+            const cb = v;
+            const key = `${cb.claimId}:${cb.claimVersion}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const claim = this.claimLibrary.get(cb.claimId, cb.claimVersion);
+            if (claim !== undefined) {
+                claims.push(claim);
+            }
+        }
+        return {
+            argument,
+            premises,
+            expressions,
+            variables,
+            claims,
+            roleState: this.getRoleState(),
+        };
+    }
     validateEvaluability() {
         const base = validateArgumentEvaluabilityStandalone(this.asValidationContext());
         const derivationIssues = this.collectDerivationStructureIssues();
@@ -1420,15 +1753,19 @@ export class ArgumentEngine {
      * Apps can pre-check derivation premise structures before invoking the full
      * evaluation pipeline.
      *
+     * Violations carry the underlying `DERIVATION_STRUCTURE_INVALID` code
+     * (per the derivation-validation utility). The pre-1.0
+     * `DERIVATION_STRUCTURE_INVALID_AT_EVALUATION` override was removed in
+     * Phase D4 alongside the legacy `validate()` no-arg overload — naked-Q
+     * is a valid Derivable state (per spec §4.2) and is skipped by
+     * evaluation rather than thrown.
+     *
      * @since 0.11.0
      */
     validateDerivationStructures() {
         const violations = [];
         for (const { violation } of this.collectDerivationViolations()) {
-            violations.push({
-                ...violation,
-                code: DERIVATION_STRUCTURE_INVALID_AT_EVALUATION,
-            });
+            violations.push(violation);
         }
         return { ok: violations.length === 0, violations };
     }
@@ -1436,7 +1773,7 @@ export class ArgumentEngine {
         const issues = [];
         for (const { violation } of this.collectDerivationViolations()) {
             issues.push(makeErrorIssue({
-                code: DERIVATION_STRUCTURE_INVALID_AT_EVALUATION,
+                code: "DERIVATION_STRUCTURE_INVALID",
                 message: violation.message,
                 premiseId: violation.entityId,
             }));
@@ -1486,14 +1823,37 @@ export class ArgumentEngine {
         };
     }
     asEvaluationContext() {
+        // C8: naked-Q derivation premises (single variable expression at
+        // root, type='derivation') contribute nothing to evaluation. The
+        // evaluator-context's premise listings filter them out so they
+        // are entirely invisible to evaluate() and checkValidity(). This
+        // replaces the pre-1.0 DERIVATION_STRUCTURE_INVALID_AT_EVALUATION
+        // throw on naked-Q. Filter applies uniformly to conclusion,
+        // supporting, and full premise listings. The predicate lives in
+        // `src/lib/grammar/naked-q.ts` so the C6 factory and this filter
+        // share one definition.
         return {
             argumentId: this.argument.id,
             conclusionPremiseId: this.conclusionPremiseId,
-            getConclusionPremise: () => this.getConclusionPremise(),
-            listSupportingPremises: () => this.listSupportingPremises(),
-            listPremises: () => this.listPremises(),
+            getConclusionPremise: () => {
+                const c = this.getConclusionPremise();
+                if (c === undefined)
+                    return undefined;
+                if (isNakedQDerivationPremise(c))
+                    return undefined;
+                return c;
+            },
+            listSupportingPremises: () => this.listSupportingPremises().filter((pm) => !isNakedQDerivationPremise(pm)),
+            listPremises: () => this.listPremises().filter((pm) => !isNakedQDerivationPremise(pm)),
             getVariable: (id) => this.variables.getVariable(id),
-            getPremise: (id) => this.premises.get(id),
+            getPremise: (id) => {
+                const pe = this.premises.get(id);
+                if (pe === undefined)
+                    return undefined;
+                if (isNakedQDerivationPremise(pe))
+                    return undefined;
+                return pe;
+            },
             validateEvaluability: () => this.validateEvaluability(),
         };
     }