usesteady 0.1.0-alpha.1

package/dist/src/present/boundary-explanation/boundary-explanation-detector.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Boundary Explanation detector — Phase 5C.
+ *
+ * Pure, deterministic functions that map already-available state to a
+ * BoundaryExplanation.  No re-interpretation, no state mutation.
+ *
+ * ── Decision order (first-match-wins) ────────────────────────────────────────
+ *
+ *   1. question_form_needs_action   mode = clarify + question-shaped input
+ *   2. multi_intent_first_only      compound-verb input, mode = guide or execute
+ *   3. needs_specific_target        mode = guide, guided_recovery, missing file target
+ *   4. policy_may_block_target      set by coordinator when 5D contradiction detected
+ *      (this detector does not produce it — it requires parsedChange + policy)
+ *   5. scope_must_be_narrowed       mode = guide, incomplete, missing fields present
+ *   6. not_ready_missing_fields     mode = guide, missing fields present (general fallback)
+ *
+ *   For the reminder path, detectReminderBoundaryExplanation is used instead.
+ *
+ * ── Authority constraint ──────────────────────────────────────────────────────
+ *
+ *   Reads: mode, intentState, guidance.missing, rawInput.
+ *   Must not re-run any interpreter or completion logic.
+ *   Must not inspect the filesystem or any external environment.
+ *   Must not modify any shared state.
+ */
+import type { IntakeResult } from "../../intake/types.js";
+import type { DebugTrace } from "../../intake/trace.js";
+import type { BoundaryExplanation } from "./boundary-explanation-types.js";
+type ReminderLike = {
+    readonly state: "ready_to_confirm" | "needs_time" | "needs_subject" | "ambiguous";
+    readonly missing?: readonly string[];
+};
+/**
+ * Detect the single most relevant boundary explanation for an intake result.
+ *
+ * Returns undefined when no explanation is warranted.
+ * Never returns more than one explanation.
+ */
+export declare function detectBoundaryExplanation(rawInput: string, intakeResult: IntakeResult, _trace?: DebugTrace): BoundaryExplanation | undefined;
+/**
+ * Detect a boundary explanation for a reminder presentation.
+ *
+ * Only "not_ready_missing_fields" applies to the reminder path.
+ * Other codes are intake-only.
+ */
+export declare function detectReminderBoundaryExplanation(presentation: ReminderLike): BoundaryExplanation | undefined;
+export {};
+//# sourceMappingURL=boundary-explanation-detector.d.ts.map

package/dist/src/present/boundary-explanation/boundary-explanation-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-explanation-detector.d.ts","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/boundary-explanation-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAQ,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAA2B,MAAM,iCAAiC,CAAC;AAIpG,KAAK,YAAY,GAAG;IAClB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,YAAY,GAAG,eAAe,GAAG,WAAW,CAAC;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAmDF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAM,MAAM,EACpB,YAAY,EAAE,YAAY,EAC1B,MAAM,CAAC,EAAO,UAAU,GACvB,mBAAmB,GAAG,SAAS,CAgCjC;AAID;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,YAAY,GACzB,mBAAmB,GAAG,SAAS,CAKjC"}

package/dist/src/present/boundary-explanation/boundary-explanation-detector.js

@@ -0,0 +1,107 @@
+/**
+ * Boundary Explanation detector — Phase 5C.
+ *
+ * Pure, deterministic functions that map already-available state to a
+ * BoundaryExplanation.  No re-interpretation, no state mutation.
+ *
+ * ── Decision order (first-match-wins) ────────────────────────────────────────
+ *
+ *   1. question_form_needs_action   mode = clarify + question-shaped input
+ *   2. multi_intent_first_only      compound-verb input, mode = guide or execute
+ *   3. needs_specific_target        mode = guide, guided_recovery, missing file target
+ *   4. policy_may_block_target      set by coordinator when 5D contradiction detected
+ *      (this detector does not produce it — it requires parsedChange + policy)
+ *   5. scope_must_be_narrowed       mode = guide, incomplete, missing fields present
+ *   6. not_ready_missing_fields     mode = guide, missing fields present (general fallback)
+ *
+ *   For the reminder path, detectReminderBoundaryExplanation is used instead.
+ *
+ * ── Authority constraint ──────────────────────────────────────────────────────
+ *
+ *   Reads: mode, intentState, guidance.missing, rawInput.
+ *   Must not re-run any interpreter or completion logic.
+ *   Must not inspect the filesystem or any external environment.
+ *   Must not modify any shared state.
+ */
+// ─── Deterministic message catalog ───────────────────────────────────────────
+const MESSAGES = {
+    question_form_needs_action: "This is phrased as a question rather than a command. Rephrase as a direct action — for example, 'Change X to Y in file Z' — to proceed.",
+    multi_intent_first_only: "This input contains more than one action. Only the first was processed. Submit the remaining actions separately.",
+    needs_specific_target: "The intent is clear, but the target location is missing. Provide the specific file or value to change.",
+    policy_may_block_target: "This change is structurally executable, but the target file may be restricted by policy. Review the target before approving.",
+    scope_must_be_narrowed: "The scope of this change is too broad to act on safely. Narrow to a specific file, section, or value.",
+    not_ready_missing_fields: "Some required fields are missing. Provide the missing information to complete the request.",
+};
+// ─── Question-form detection ──────────────────────────────────────────────────
+const QUESTION_LEAD = /^(how|what|why|can|is|are|does|do|will|would|should|could|when|where|which)\b/i;
+function isQuestionForm(input) {
+    const trimmed = input.trim();
+    return trimmed.endsWith("?") || QUESTION_LEAD.test(trimmed);
+}
+// ─── Compound-action detection ────────────────────────────────────────────────
+const COMPOUND_CONNECTORS = /\b(and|then)\b/i;
+// Verbs that indicate deliberate actions (not description verbs like "is", "has").
+const ACTION_VERB = /\b(change|update|replace|fix|set|add|remove|delete|deploy|restart|check|run|create|modify|install|enable|disable|toggle|revert|rollback|push|pull|send|export|import|launch|rename|move|copy|reset|apply|configure|upgrade|downgrade|start|stop|kill|flush|migrate|rebuild|clear)\b/gi;
+function hasCompoundActions(input) {
+    if (!COMPOUND_CONNECTORS.test(input))
+        return false;
+    const hits = Array.from(input.matchAll(ACTION_VERB));
+    return hits.length >= 2;
+}
+// ─── Missing file-target detection ───────────────────────────────────────────
+const FILE_FIELD_TERMS = /\b(file|path|location|component|module|directory|folder|target|where)\b/i;
+function hasMissingFileTarget(intakeResult) {
+    const missing = intakeResult.guidance?.missing ?? [];
+    return missing.some(f => FILE_FIELD_TERMS.test(f));
+}
+// ─── Main detector (intake path) ─────────────────────────────────────────────
+/**
+ * Detect the single most relevant boundary explanation for an intake result.
+ *
+ * Returns undefined when no explanation is warranted.
+ * Never returns more than one explanation.
+ */
+export function detectBoundaryExplanation(rawInput, intakeResult, _trace) {
+    const { mode, intentState, guidance } = intakeResult;
+    // 1. question_form_needs_action
+    if (mode === "clarify" && isQuestionForm(rawInput)) {
+        return explain("question_form_needs_action");
+    }
+    // 2. multi_intent_first_only
+    if ((mode === "guide" || mode === "execute") && hasCompoundActions(rawInput)) {
+        return explain("multi_intent_first_only");
+    }
+    // 3. needs_specific_target
+    if (mode === "guide" && intentState === "guided_recovery" && hasMissingFileTarget(intakeResult)) {
+        return explain("needs_specific_target");
+    }
+    // 4. policy_may_block_target — NOT produced here; requires parsedChange + policy.
+    //    The coordinator injects it after 5D cross-layer detection.
+    // 5. scope_must_be_narrowed
+    if (mode === "guide" && intentState === "incomplete" && (guidance?.missing.length ?? 0) > 0) {
+        return explain("scope_must_be_narrowed");
+    }
+    // 6. not_ready_missing_fields (guide fallback when missing fields exist)
+    if (mode === "guide" && (guidance?.missing.length ?? 0) > 0) {
+        return explain("not_ready_missing_fields");
+    }
+    return undefined;
+}
+// ─── Reminder path detector ───────────────────────────────────────────────────
+/**
+ * Detect a boundary explanation for a reminder presentation.
+ *
+ * Only "not_ready_missing_fields" applies to the reminder path.
+ * Other codes are intake-only.
+ */
+export function detectReminderBoundaryExplanation(presentation) {
+    if (presentation.state === "needs_time" || presentation.state === "needs_subject") {
+        return explain("not_ready_missing_fields");
+    }
+    return undefined;
+}
+// ─── Factory helper ───────────────────────────────────────────────────────────
+function explain(code) {
+    return { code, message: MESSAGES[code] };
+}
+//# sourceMappingURL=boundary-explanation-detector.js.map

package/dist/src/present/boundary-explanation/boundary-explanation-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-explanation-detector.js","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/boundary-explanation-detector.ts"],"names":[],"mappings":"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"}

package/dist/src/present/boundary-explanation/boundary-explanation-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Boundary Explanation types — Phase 5C.
+ *
+ * Provides human-legible explanations for correct-but-confusing routing decisions.
+ *
+ * ── Authority constraint ──────────────────────────────────────────────────────
+ *
+ *   Boundary explanations are metadata only.
+ *   They describe decisions that have already been made.
+ *   They do not re-evaluate, override, or change any routing decision.
+ *   They do not affect CVG signal levels.
+ *   They do not affect confirm enablement.
+ *
+ * ── Stacking rule ────────────────────────────────────────────────────────────
+ *
+ *   Exactly one explanation may appear per presentation result.
+ *   First-match-wins. No stacking. No combining.
+ */
+/**
+ * BoundaryExplanationCode — the semantic identity of the boundary encountered.
+ *
+ *   question_form_needs_action   Input was phrased as a question, not a command.
+ *   multi_intent_first_only      Compound input: only the first action was processed.
+ *   needs_specific_target        Intent is clear but the target location is missing.
+ *   policy_may_block_target      Target is structurally reachable but may be policy-blocked.
+ *   scope_must_be_narrowed       Scope is too broad to act on safely.
+ *   not_ready_missing_fields     Required fields are absent (reminder path).
+ */
+export type BoundaryExplanationCode = "question_form_needs_action" | "multi_intent_first_only" | "needs_specific_target" | "policy_may_block_target" | "scope_must_be_narrowed" | "not_ready_missing_fields";
+/**
+ * BoundaryExplanation — one explanation attached to a presentation result.
+ *
+ *   code     — stable identifier used by consumers for rendering decisions
+ *   message  — deterministic, human-readable explanation text
+ *
+ * This field is either absent (no boundary detected) or present (one boundary).
+ * It is never null. It never stacks.
+ */
+export type BoundaryExplanation = {
+    readonly code: BoundaryExplanationCode;
+    readonly message: string;
+};
+//# sourceMappingURL=boundary-explanation-types.d.ts.map

package/dist/src/present/boundary-explanation/boundary-explanation-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-explanation-types.d.ts","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/boundary-explanation-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,GAC/B,4BAA4B,GAC5B,yBAAyB,GACzB,uBAAuB,GACvB,yBAAyB,GACzB,wBAAwB,GACxB,0BAA0B,CAAC;AAI/B;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAK,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC"}

package/dist/src/present/boundary-explanation/boundary-explanation-types.js

@@ -0,0 +1,20 @@
+/**
+ * Boundary Explanation types — Phase 5C.
+ *
+ * Provides human-legible explanations for correct-but-confusing routing decisions.
+ *
+ * ── Authority constraint ──────────────────────────────────────────────────────
+ *
+ *   Boundary explanations are metadata only.
+ *   They describe decisions that have already been made.
+ *   They do not re-evaluate, override, or change any routing decision.
+ *   They do not affect CVG signal levels.
+ *   They do not affect confirm enablement.
+ *
+ * ── Stacking rule ────────────────────────────────────────────────────────────
+ *
+ *   Exactly one explanation may appear per presentation result.
+ *   First-match-wins. No stacking. No combining.
+ */
+export {};
+//# sourceMappingURL=boundary-explanation-types.js.map

package/dist/src/present/boundary-explanation/boundary-explanation-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-explanation-types.js","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/boundary-explanation-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/src/present/boundary-explanation/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Boundary Explanation — Phase 5C public API.
+ *
+ * Exports types and detection functions.
+ * This module is presentation-layer only.
+ * It has zero authority over routing, mode, or confirm decisions.
+ */
+export type { BoundaryExplanationCode, BoundaryExplanation } from "./boundary-explanation-types.js";
+export { detectBoundaryExplanation, detectReminderBoundaryExplanation } from "./boundary-explanation-detector.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/present/boundary-explanation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACpG,OAAO,EAAE,yBAAyB,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/src/present/boundary-explanation/index.js

@@ -0,0 +1,2 @@
+export { detectBoundaryExplanation, detectReminderBoundaryExplanation } from "./boundary-explanation-detector.js";
+//# sourceMappingURL=index.js.map

package/dist/src/present/boundary-explanation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/present/boundary-explanation/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,yBAAyB,EAAE,iCAAiC,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/src/present/control-visibility/control-visibility-assertions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Control Visibility Assertions — Phase 5B.
+ *
+ * ── Purpose ───────────────────────────────────────────────────────────────────
+ *
+ *   A HARD GUARD layer. Not optional. Not stylistic.
+ *
+ *   Throws immediately on any ControlVisibilityResult that violates the
+ *   authority invariants. Catches invalid states before they reach rendering.
+ *
+ * ── Locked rules (permanent — see docs/cvg-baseline.md) ─────────────────────
+ *
+ *   C2 — CVG may assert, but never route.
+ *        This function throws or returns void. It never changes the caller's output.
+ *
+ *   C3 — CVG may detect violations, but never repair them silently.
+ *        A bad result throws. It is never promoted, demoted, or patched here.
+ *        Silent repair is worse than the violation it hides.
+ *
+ * ── What this guards ──────────────────────────────────────────────────────────
+ *
+ *   1. Blocking signal that does not disable confirm
+ *      → system would allow execution on a blocked state
+ *
+ *   2. Blocking signal indistinguishable from normal
+ *      → different authority levels collapse into same presentation
+ *
+ *   3. Ambiguous signal treated as confirmable
+ *      → ambiguous state would allow execution without clarification
+ *
+ *   4. Refused signal missing surface requirement
+ *      → a refused state could be silently hidden from H
+ *
+ *   5. ready_to_confirm treated as blocking
+ *      → normal state incorrectly blocks execution
+ *
+ * ── What this does NOT do ─────────────────────────────────────────────────────
+ *
+ *   Does NOT fix invalid states   — it throws; the caller must not produce them
+ *   Does NOT log or warn          — it throws immediately
+ *   Does NOT affect valid results — returns void when all invariants hold
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   Call assertControlVisibilityConsistency(result) immediately after
+ *   evaluateControlVisibility() in any presentation entry point.
+ *   A throw here means the evaluator or upstream state produced an invalid result.
+ */
+import type { ControlVisibilityResult } from "./control-visibility-types.js";
+/**
+ * Assert that a ControlVisibilityResult satisfies all authority invariants.
+ *
+ * Throws a ControlVisibilityViolationError if any invariant is broken.
+ * Returns void when all invariants hold.
+ *
+ * Call this immediately after evaluateControlVisibility() in every
+ * presentation entry point. This is the runtime enforcement of the CVG contract.
+ */
+export declare function assertControlVisibilityConsistency(result: ControlVisibilityResult): void;
+/**
+ * ControlVisibilityViolationError — thrown when a CVG invariant is broken.
+ *
+ * Carries the violating result and the invariant code for traceability.
+ */
+export declare class ControlVisibilityViolationError extends Error {
+    readonly result: ControlVisibilityResult;
+    readonly invariant: string;
+    constructor(result: ControlVisibilityResult, invariant: string, message: string);
+}
+//# sourceMappingURL=control-visibility-assertions.d.ts.map

package/dist/src/present/control-visibility/control-visibility-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-visibility-assertions.d.ts","sourceRoot":"","sources":["../../../../src/present/control-visibility/control-visibility-assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAI7E;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,uBAAuB,GAC9B,IAAI,CAoHN;AAID;;;;GAIG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAgB,MAAM,EAAK,uBAAuB,CAAC;IACnD,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,MAAM,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMhF"}

package/dist/src/present/control-visibility/control-visibility-assertions.js

@@ -0,0 +1,138 @@
+/**
+ * Control Visibility Assertions — Phase 5B.
+ *
+ * ── Purpose ───────────────────────────────────────────────────────────────────
+ *
+ *   A HARD GUARD layer. Not optional. Not stylistic.
+ *
+ *   Throws immediately on any ControlVisibilityResult that violates the
+ *   authority invariants. Catches invalid states before they reach rendering.
+ *
+ * ── Locked rules (permanent — see docs/cvg-baseline.md) ─────────────────────
+ *
+ *   C2 — CVG may assert, but never route.
+ *        This function throws or returns void. It never changes the caller's output.
+ *
+ *   C3 — CVG may detect violations, but never repair them silently.
+ *        A bad result throws. It is never promoted, demoted, or patched here.
+ *        Silent repair is worse than the violation it hides.
+ *
+ * ── What this guards ──────────────────────────────────────────────────────────
+ *
+ *   1. Blocking signal that does not disable confirm
+ *      → system would allow execution on a blocked state
+ *
+ *   2. Blocking signal indistinguishable from normal
+ *      → different authority levels collapse into same presentation
+ *
+ *   3. Ambiguous signal treated as confirmable
+ *      → ambiguous state would allow execution without clarification
+ *
+ *   4. Refused signal missing surface requirement
+ *      → a refused state could be silently hidden from H
+ *
+ *   5. ready_to_confirm treated as blocking
+ *      → normal state incorrectly blocks execution
+ *
+ * ── What this does NOT do ─────────────────────────────────────────────────────
+ *
+ *   Does NOT fix invalid states   — it throws; the caller must not produce them
+ *   Does NOT log or warn          — it throws immediately
+ *   Does NOT affect valid results — returns void when all invariants hold
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   Call assertControlVisibilityConsistency(result) immediately after
+ *   evaluateControlVisibility() in any presentation entry point.
+ *   A throw here means the evaluator or upstream state produced an invalid result.
+ */
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Assert that a ControlVisibilityResult satisfies all authority invariants.
+ *
+ * Throws a ControlVisibilityViolationError if any invariant is broken.
+ * Returns void when all invariants hold.
+ *
+ * Call this immediately after evaluateControlVisibility() in every
+ * presentation entry point. This is the runtime enforcement of the CVG contract.
+ */
+export function assertControlVisibilityConsistency(result) {
+    // I1 — Blocking signal must disable confirm.
+    if (result.level === "blocking" && !result.must_block_confirm) {
+        throw new ControlVisibilityViolationError(result, "I1", `Blocking signal "${result.signal}" does not disable confirm. ` +
+            `must_block_confirm must be true for all blocking signals.`);
+    }
+    // I2 — Blocking signal must not be indistinguishable from normal.
+    //      A blocking result with must_block_confirm=false and must_surface=false
+    //      would be identical in flags to a normal result.
+    if (result.level === "blocking" &&
+        !result.must_surface &&
+        !result.must_block_confirm) {
+        throw new ControlVisibilityViolationError(result, "I2", `Blocking signal "${result.signal}" is indistinguishable from normal. ` +
+            `A blocking result must set must_block_confirm or must_surface (or both).`);
+    }
+    // I3 — Ambiguous must not be confirmable.
+    //      must_block_confirm=false would allow confirm on an ambiguous state.
+    //      must_surface must be true (H must see it).
+    if (result.signal === "ambiguous" && result.must_block_confirm) {
+        throw new ControlVisibilityViolationError(result, "I3a", `Ambiguous signal has must_block_confirm=true, which is reserved for blocking. ` +
+            `Ambiguous is "attention" level — it must surface but not hard-block.`);
+    }
+    if (result.signal === "ambiguous" && !result.must_surface) {
+        throw new ControlVisibilityViolationError(result, "I3b", `Ambiguous signal is not surfaced (must_surface=false). ` +
+            `Ambiguous state must always be visible to H.`);
+    }
+    // I4 — Refused states must have surface requirement.
+    if ((result.signal === "refused_scope" || result.signal === "refused_execution") &&
+        !result.must_surface) {
+        throw new ControlVisibilityViolationError(result, "I4", `Refused signal "${result.signal}" is missing surface requirement. ` +
+            `All refused states must be surfaced to H.`);
+    }
+    // I5 — ready_to_confirm must not be treated as blocking.
+    if (result.signal === "ready_to_confirm" && result.must_block_confirm) {
+        throw new ControlVisibilityViolationError(result, "I5", `"ready_to_confirm" signal has must_block_confirm=true. ` +
+            `A ready state must never block confirm.`);
+    }
+    // I6 — must_differentiate must always be true (no level may be invisible).
+    if (!result.must_differentiate) {
+        throw new ControlVisibilityViolationError(result, "I6", `Signal "${result.signal}" has must_differentiate=false. ` +
+            `All control visibility results must be structurally distinct.`);
+    }
+    // I7 — provisionally_executable must always surface (Phase 5D).
+    if (result.signal === "provisionally_executable" && !result.must_surface) {
+        throw new ControlVisibilityViolationError(result, "I7", `"provisionally_executable" signal has must_surface=false. ` +
+            `A provisional execution warning must always be visible to H.`);
+    }
+    // I8 — provisionally_executable must never be blocking (Phase 5D).
+    //       It is attention-level: it informs, does not hard-block.
+    if (result.signal === "provisionally_executable" && result.must_block_confirm) {
+        throw new ControlVisibilityViolationError(result, "I8", `"provisionally_executable" signal has must_block_confirm=true. ` +
+            `A provisional warning is attention-level and must not hard-block confirm.`);
+    }
+    // I9 — provisionally_executable must be distinguishable from ready_to_confirm (Phase 5D).
+    //       Both are non-blocking, but provisionally_executable must surface (attention)
+    //       while ready_to_confirm does not need to (normal). The must_surface flag
+    //       enforces the structural difference.
+    if (result.signal === "provisionally_executable" &&
+        result.level !== "attention") {
+        throw new ControlVisibilityViolationError(result, "I9", `"provisionally_executable" signal has level="${result.level}" but must be "attention". ` +
+            `It must remain structurally distinguishable from "ready_to_confirm" (normal).`);
+    }
+}
+// ─── Error type ───────────────────────────────────────────────────────────────
+/**
+ * ControlVisibilityViolationError — thrown when a CVG invariant is broken.
+ *
+ * Carries the violating result and the invariant code for traceability.
+ */
+export class ControlVisibilityViolationError extends Error {
+    result;
+    invariant;
+    constructor(result, invariant, message) {
+        super(`[CVG ${invariant}] ${message}`);
+        this.name = "ControlVisibilityViolationError";
+        this.result = result;
+        this.invariant = invariant;
+    }
+}
+//# sourceMappingURL=control-visibility-assertions.js.map

package/dist/src/present/control-visibility/control-visibility-assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-visibility-assertions.js","sourceRoot":"","sources":["../../../../src/present/control-visibility/control-visibility-assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC,CAChD,MAA+B;IAE/B,6CAA6C;IAC7C,IAAI,MAAM,CAAC,KAAK,KAAK,UAAU,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC9D,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,oBAAoB,MAAM,CAAC,MAAM,8BAA8B;YAC/D,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,kEAAkE;IAClE,8EAA8E;IAC9E,uDAAuD;IACvD,IACE,MAAM,CAAC,KAAK,KAAK,UAAU;QAC3B,CAAC,MAAM,CAAC,YAAY;QACpB,CAAC,MAAM,CAAC,kBAAkB,EAC1B,CAAC;QACD,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,oBAAoB,MAAM,CAAC,MAAM,sCAAsC;YACvE,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,2EAA2E;IAC3E,kDAAkD;IAClD,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC/D,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,KAAK,EACL,gFAAgF;YAChF,sEAAsE,CACvE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QAC1D,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,KAAK,EACL,yDAAyD;YACzD,8CAA8C,CAC/C,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,IACE,CAAC,MAAM,CAAC,MAAM,KAAK,eAAe,IAAI,MAAM,CAAC,MAAM,KAAK,mBAAmB,CAAC;QAC5E,CAAC,MAAM,CAAC,YAAY,EACpB,CAAC;QACD,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,mBAAmB,MAAM,CAAC,MAAM,oCAAoC;YACpE,2CAA2C,CAC5C,CAAC;IACJ,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM,CAAC,MAAM,KAAK,kBAAkB,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;QACtE,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,yDAAyD;YACzD,yCAAyC,CAC1C,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC/B,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,WAAW,MAAM,CAAC,MAAM,kCAAkC;YAC1D,+DAA+D,CAChE,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,IAAI,MAAM,CAAC,MAAM,KAAK,0BAA0B,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACzE,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,4DAA4D;YAC5D,8DAA8D,CAC/D,CAAC;IACJ,CAAC;IAED,mEAAmE;IACnE,gEAAgE;IAChE,IAAI,MAAM,CAAC,MAAM,KAAK,0BAA0B,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC9E,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,iEAAiE;YACjE,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IAED,0FAA0F;IAC1F,qFAAqF;IACrF,gFAAgF;IAChF,4CAA4C;IAC5C,IACE,MAAM,CAAC,MAAM,KAAK,0BAA0B;QAC5C,MAAM,CAAC,KAAK,KAAK,WAAW,EAC5B,CAAC;QACD,MAAM,IAAI,+BAA+B,CACvC,MAAM,EACN,IAAI,EACJ,gDAAgD,MAAM,CAAC,KAAK,6BAA6B;YACzF,+EAA+E,CAChF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACxC,MAAM,CAA6B;IACnC,SAAS,CAAS;IAElC,YAAY,MAA+B,EAAE,SAAiB,EAAE,OAAe;QAC7E,KAAK,CAAC,QAAQ,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAQ,iCAAiC,CAAC;QACnD,IAAI,CAAC,MAAM,GAAM,MAAM,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/present/control-visibility/control-visibility-evaluator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Control Visibility Evaluator — Phase 5B.
+ *
+ * ── Responsibility ────────────────────────────────────────────────────────────
+ *
+ *   Pure mapping from presentation state → ControlVisibilityResult.
+ *
+ *   No inference. No guessing. No logic authority.
+ *   Every mapping is an explicit, deterministic read of existing state.
+ *
+ * ── What this does NOT do ─────────────────────────────────────────────────────
+ *
+ *   Does NOT call intake, execution, or UCP
+ *   Does NOT derive new decisions from the presentation
+ *   Does NOT change any output shape
+ *   Does NOT produce side effects
+ *
+ * ── Locked rules (permanent — see docs/cvg-baseline.md) ─────────────────────
+ *
+ *   C1 — CVG is derived only from existing presentation state.
+ *        No re-evaluation. No classification. No inference. Pure mapping.
+ *
+ *   C2 — CVG may assert, but never route.
+ *        This function returns a result. It never changes what the caller returns.
+ *
+ *   C4 — Any new presentation family must extend ControlVisibilityInput here,
+ *        add a mapping case below, and pass all uniqueness/invariant tests.
+ *        Exhaustive switch required — no default fallthrough.
+ *
+ * ── Signal mapping summary ────────────────────────────────────────────────────
+ *
+ *   reminder_presentation:
+ *     ready_to_confirm   → signal: "ready_to_confirm",  level: "normal"
+ *     needs_time         → signal: "not_ready",          level: "blocking"
+ *     needs_subject      → signal: "not_ready",          level: "blocking"
+ *     ambiguous          → signal: "ambiguous",          level: "attention"
+ *
+ *   intake_presentation (by mode):
+ *     execute            → signal: "ready_to_confirm",  level: "normal"
+ *     guide              → signal: "not_ready",          level: "blocking"
+ *     clarify            → signal: "ambiguous",          level: "attention"
+ *     refuse             → signal: "refused_execution",  level: "blocking"
+ *     ignore             → signal: "not_ready",          level: "blocking"
+ *
+ *   cursor_preparation:
+ *     ready_for_confirmation → signal: "ready_to_confirm",  level: "normal"
+ *     conflict_detected      → signal: "conflict_detected", level: "blocking"
+ *     not_execute            → signal: "not_ready",          level: "blocking"
+ *
+ *   cursor_execution:
+ *     accepted                       → signal: "ready_to_confirm",  level: "normal"
+ *     refused_due_to_scope           → signal: "refused_scope",     level: "blocking"
+ *     refused_due_to_execution_error → signal: "refused_execution", level: "blocking"
+ *     blocked_ineligible             → signal: "refused_execution", level: "blocking"
+ *     blocked_persistence_failure    → signal: "refused_execution", level: "blocking"
+ */
+import type { ControlVisibilityInput, ControlVisibilityResult } from "./control-visibility-types.js";
+/**
+ * Evaluate the control visibility for a given presentation input.
+ *
+ * Pure function. No side effects. No inference. Deterministic.
+ *
+ * @param input  A ControlVisibilityInput discriminated union arm.
+ * @returns      A ControlVisibilityResult characterizing the authority level.
+ */
+export declare function evaluateControlVisibility(input: ControlVisibilityInput): ControlVisibilityResult;
+//# sourceMappingURL=control-visibility-evaluator.d.ts.map

package/dist/src/present/control-visibility/control-visibility-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-visibility-evaluator.d.ts","sourceRoot":"","sources":["../../../../src/present/control-visibility/control-visibility-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EAGxB,MAAM,+BAA+B,CAAC;AAIvC;;;;;;;GAOG;AAWH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,sBAAsB,GAC5B,uBAAuB,CAmBzB"}