usesteady 0.1.0-alpha.1

package/dist/src/index.js

@@ -0,0 +1,58 @@
+/**
+ * usesteady-core-v2 — public API surface.
+ *
+ * This is the only import path consumers should use.
+ * Internal modules may be accessed directly for testing.
+ */
+export { createEnvelope, createIntentEnvelope, createPRVEnvelope, createSafetyEnvelope, createContextAlignmentEnvelope, createDisambiguationEnvelope, createCompletionEnvelope, createIntentInterpretationEnvelope, createChangeInterpretationEnvelope, createResponseEnvelope, createInteractionContractEnvelope, createInteractionEventEnvelope, createDebugTraceEnvelope, } from "./ucp/envelope.js";
+export { hashObject, stableStringify } from "./ucp/hashes.js";
+// UCP mappers (pure, one per envelope family)
+export { mapIntentToEnvelope } from "./ucp/mappers/map-intent.js";
+export { mapPRVToEnvelope } from "./ucp/mappers/map-prv.js";
+export { mapSafetyToEnvelope } from "./ucp/mappers/map-safety.js";
+export { mapContextToEnvelope } from "./ucp/mappers/map-context.js";
+export { mapDisambiguationToEnvelope } from "./ucp/mappers/map-disambiguation.js";
+export { mapCompletionToEnvelope } from "./ucp/mappers/map-completion.js";
+export { mapIntentInterpretationToEnvelope } from "./ucp/mappers/map-intent-interpretation.js";
+export { mapChangeInterpretationToEnvelope } from "./ucp/mappers/map-change-interpretation.js";
+export { mapResponseToEnvelope } from "./ucp/mappers/map-response.js";
+export { mapDebugTraceToEnvelope } from "./ucp/mappers/map-debug-trace.js";
+export { runPRV } from "./prv/prv.js";
+export { runSafetyGate } from "./safety/safety-gate.js";
+export { DEFAULT_CONTRACT, DEFAULT_OBSERVED_INTENT_PATTERNS, createDefaultContract } from "./interaction/defaults.js";
+export { getAmbiguityPolicy, getExplanationPolicy, getUnsupportedGuidancePolicy } from "./interaction/selectors.js";
+export { applyInteractionEvent } from "./interaction/updater.js";
+export { observeIntentPattern } from "./interaction/observe.js";
+export { applyGuidanceOrdering, FAMILIARITY_THRESHOLD } from "./interaction/guidance-order.js";
+export { runContextAlignment } from "./understand/context/context-alignment.js";
+export { runDisambiguation } from "./understand/disambiguation/registry.js";
+export { runCompletion } from "./understand/completion/completion.js";
+export { interpretChange } from "./understand/interpretation/interpretation.js";
+export { parseChange } from "./understand/interpretation/parser.js";
+export { runIntentInterpretation, enrichGuidance } from "./understand/intent-interpretation/intent-interpretation.js";
+export { selectSilentGuidanceMode, getSilentGuidanceSteps } from "./understand/silent-guidance/index.js";
+export { runIntake, runIntakeWithTrace, runIntakeWithUCP } from "./intake/intake-service.js";
+export { formatIntakeResult } from "./present/format.js";
+export { presentFromInput, isReminderConfirmable, getReminderPrompt } from "./present/present-coordinator.js";
+export { presentReminder, renderReminder } from "./present/reminders/index.js";
+export { projectUCPBundle } from "./ucp/projection.js";
+export { createArtifactEnvelope, createExecutionTraceEnvelope } from "./ucp/envelope.js";
+export { mapArtifactToEnvelope } from "./ucp/mappers/map-artifact.js";
+export { mapExecutionTraceToEnvelope } from "./ucp/mappers/map-execution-trace.js";
+export { createReplayReportEnvelope } from "./ucp/envelope.js";
+export { mapReplayReportToEnvelope } from "./ucp/mappers/map-replay-report.js";
+export { LOG_FILENAME, INDEX_FILENAME, emptyIndex, ensureStoreDir, appendEnvelope, loadIndex, updateIndex, rebuildIndex, persistEnvelope, } from "./ucp/persistence/index.js";
+export { parseTimeText } from "./execution/reminders/index.js";
+export { validateExecutionRequest } from "./execution/reminders/index.js";
+export { buildExecutionRequest, executeReminder } from "./execution/reminders/index.js";
+export { executeFromPresent, isExecutionAccepted, getExecutionNote } from "./execution/reminders/index.js";
+export { createReminderExecutionEnvelope } from "./ucp/envelope.js";
+export { mapReminderExecutionToEnvelope } from "./ucp/mappers/map-reminder-execution.js";
+export { prepareCursorExecution, deliverCursorExecution, hasConflicts, isCursorExecutionAccepted, getCursorExecutionNote, } from "./execution/cursor/index.js";
+export { buildCursorHandoffArtifact, narrowArtifactScope, approveArtifact, evaluateOCDForHandoff, applyOCDClearance, acceptOCDConflict, validateHProvidedPath, CursorDeliveryGate, } from "./cursor/index.js";
+// ── UCP Phase 4B — query layer ────────────────────────────────────────────────
+// Read-only navigation over the persisted UCP envelope history.
+// All queries follow refs only — no inference, no caching, no mutation.
+export { readEnvelopeAt, readAllEnvelopes } from "./ucp/persistence/index.js";
+export { getEnvelopeById, getByType, getChain, getArtifactByRunId, getTraceByArtifactId, getReplayByArtifactId, getReminderExecutionByResponseId, getTimeline, } from "./ucp/persistence/index.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

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

package/dist/src/intake/classify-intent-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Intent state classifier — maps IntakeSignals to IntentStates.
+ *
+ * Deterministic, exhaustive mapping. No logic.
+ *
+ * `unknown` from disambiguation is no longer a public signal,
+ * so there is no case for it here.
+ *
+ * Mapping:
+ *   unsafe          → unsafe
+ *   non_literal     → non_literal
+ *   hard_mismatch   → ambiguous  (requires clarification)
+ *   ambiguous       → ambiguous
+ *   incomplete      → incomplete (intent clear, field missing)
+ *   guided_recovery → guided_recovery (vague intent, path available)
+ *   complete        → clear
+ */
+import type { IntakeSignal, IntentState } from "./types.js";
+export declare function classifyIntentState(signal: IntakeSignal): IntentState;
+//# sourceMappingURL=classify-intent-state.d.ts.map

package/dist/src/intake/classify-intent-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-intent-state.d.ts","sourceRoot":"","sources":["../../../src/intake/classify-intent-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAUrE"}

package/dist/src/intake/classify-intent-state.js

@@ -0,0 +1,29 @@
+/**
+ * Intent state classifier — maps IntakeSignals to IntentStates.
+ *
+ * Deterministic, exhaustive mapping. No logic.
+ *
+ * `unknown` from disambiguation is no longer a public signal,
+ * so there is no case for it here.
+ *
+ * Mapping:
+ *   unsafe          → unsafe
+ *   non_literal     → non_literal
+ *   hard_mismatch   → ambiguous  (requires clarification)
+ *   ambiguous       → ambiguous
+ *   incomplete      → incomplete (intent clear, field missing)
+ *   guided_recovery → guided_recovery (vague intent, path available)
+ *   complete        → clear
+ */
+export function classifyIntentState(signal) {
+    switch (signal.type) {
+        case "unsafe": return "unsafe";
+        case "non_literal": return "non_literal";
+        case "hard_mismatch": return "ambiguous";
+        case "ambiguous": return "ambiguous";
+        case "incomplete": return "incomplete";
+        case "guided_recovery": return "guided_recovery";
+        case "complete": return "clear";
+    }
+}
+//# sourceMappingURL=classify-intent-state.js.map

package/dist/src/intake/classify-intent-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-intent-state.js","sourceRoot":"","sources":["../../../src/intake/classify-intent-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,UAAU,mBAAmB,CAAC,MAAoB;IACtD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ,CAAC,CAAU,OAAO,QAAQ,CAAC;QACxC,KAAK,aAAa,CAAC,CAAK,OAAO,aAAa,CAAC;QAC7C,KAAK,eAAe,CAAC,CAAG,OAAO,WAAW,CAAC;QAC3C,KAAK,WAAW,CAAC,CAAO,OAAO,WAAW,CAAC;QAC3C,KAAK,YAAY,CAAC,CAAM,OAAO,YAAY,CAAC;QAC5C,KAAK,iBAAiB,CAAC,CAAC,OAAO,iBAAiB,CAAC;QACjD,KAAK,UAAU,CAAC,CAAQ,OAAO,OAAO,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/src/intake/intake-service.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Intake Service — the full Signal → Gate spine of UseSteady.
+ *
+ * Pipeline order (non-negotiable):
+ *   1. PRV              — lexical context-dependency check
+ *   2. Safety Gate      — unsafe inputs blocked here; never reach understanding
+ *   3. Context Alignment — semantic: social/mismatch classification
+ *   4. Disambiguation   — ambiguous term detection; unknown falls through
+ *   5. Completion       — executability authority, receives full context
+ *   6. Classify intent state
+ *   7. Plan response
+ *
+ * ── Public API ────────────────────────────────────────────────────────────────
+ *
+ *   runIntake(input, ctx)            → IntakeResult        (production use)
+ *   runIntakeWithTrace(input, ctx)   → { result, trace }   (observability / debug)
+ *
+ * Both call the same internal runPipeline. runIntake discards the trace.
+ * DebugTrace is zero-authority: it never affects the result.
+ *
+ * ── Contracts ──────────────────────────────────────────────────────────────────
+ *
+ *   CONTRACT 1: execute is only reachable via complete (step 5).
+ *               No other path produces execute.
+ *
+ *   CONTRACT 2: Completion receives UnderstandContext.
+ *               Context-dependent inputs ("run again") are resolvable in step 5.
+ *
+ *   CONTRACT 3: guidance is present if and only if mode === "guide".
+ *               No consumer re-runs completion to get next steps.
+ *
+ *   CONTRACT 4: PRV is lexical, Context Alignment is semantic.
+ *               No broad semantic reasoning in PRV.
+ *
+ *   CONTRACT 5: Public result exposes final outcome, not internal intermediates.
+ *               disambiguation `unknown` is not returned as a signal.
+ */
+import type { IntakeContext, IntakeResult } from "./types.js";
+import type { DebugTrace } from "./trace.js";
+/**
+ * Run the intake pipeline and return the result.
+ * Trace is computed internally but discarded.
+ * Use for all production code paths.
+ */
+export declare function runIntake(input: string, ctx: IntakeContext): IntakeResult;
+/**
+ * Run the intake pipeline and return both the result and the debug trace.
+ * Use for observability, debugging, and developer tooling only.
+ *
+ * CONTRACT: DebugTrace is zero-authority.
+ * It records what happened; it changes nothing.
+ * Any code that reads DebugTrace to make a decision is wrong.
+ */
+export declare function runIntakeWithTrace(input: string, ctx: IntakeContext): {
+    result: IntakeResult;
+    trace: DebugTrace;
+};
+import type { IntentEnvelope, PRVEnvelope, SafetyEnvelope, ContextAlignmentEnvelope, DisambiguationEnvelope, CompletionEnvelope, IntentInterpretationEnvelope, ChangeInterpretationEnvelope, ResponseEnvelope, DebugTraceEnvelope } from "../ucp/types.js";
+/**
+ * UCP bundle — all envelopes produced during one intake run.
+ *
+ * Optional fields are absent when the pipeline short-circuited before
+ * that step ran.  `intent` and `response` and `debugTrace` are always present.
+ *
+ * Ownership contract:
+ *   - Envelopes are read-only views of pipeline outputs.
+ *   - No envelope may mutate the pipeline.
+ *   - Consumers must read `response.payload.mode` — never derive decisions
+ *     from other envelopes.
+ */
+export type UCPBundle = {
+    readonly intent: IntentEnvelope;
+    readonly prv?: PRVEnvelope;
+    readonly safety?: SafetyEnvelope;
+    readonly context?: ContextAlignmentEnvelope;
+    readonly disambiguation?: DisambiguationEnvelope;
+    readonly completion?: CompletionEnvelope;
+    readonly intentInterpretation?: IntentInterpretationEnvelope;
+    readonly changeInterpretation?: ChangeInterpretationEnvelope;
+    readonly response: ResponseEnvelope;
+    readonly debugTrace: DebugTraceEnvelope;
+};
+export type RunIntakeWithUCPResult = {
+    readonly result: IntakeResult;
+    readonly trace: DebugTrace;
+    readonly ucp: UCPBundle;
+};
+/**
+ * Run the intake pipeline and return the full result, debug trace, AND a UCP bundle.
+ *
+ * CONTRACT:
+ *   - The authoritative result comes from runIntakeWithTrace (unchanged).
+ *   - UCP envelopes are built by re-running each pure pipeline step to obtain
+ *     exact native types for mapper fidelity.
+ *   - Re-running pure steps is safe because all steps are deterministic functions.
+ *   - The pipeline short-circuit logic is mirrored: envelopes are only created
+ *     for steps that ran.
+ *   - runIntakeWithUCP.result === runIntakeWithTrace.result for the same inputs.
+ *   - UCP presence does NOT affect mode, guidance, safety, or any decision.
+ *
+ * DO NOT use the ucp bundle for routing or decision-making.
+ * Mode is the only handoff authority — and mode lives in result.mode.
+ */
+export declare function runIntakeWithUCP(input: string, ctx: IntakeContext): RunIntakeWithUCPResult;
+//# sourceMappingURL=intake-service.d.ts.map

package/dist/src/intake/intake-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intake-service.d.ts","sourceRoot":"","sources":["../../../src/intake/intake-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAgB,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoQ7C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,GACjB;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAE7C;AAID,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,kBAAkB,EAClB,4BAA4B,EAC5B,4BAA4B,EAC5B,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAYzB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAgB,cAAc,CAAC;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAkB,WAAW,CAAC;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAe,cAAc,CAAC;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAc,wBAAwB,CAAC;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAO,sBAAsB,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAW,kBAAkB,CAAC;IAClD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,4BAA4B,CAAC;IAC7D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,4BAA4B,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAc,gBAAgB,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAY,kBAAkB,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAG,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAK,SAAS,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,aAAa,GACjB,sBAAsB,CA4HxB"}

package/dist/src/intake/intake-service.js

@@ -0,0 +1,407 @@
+/**
+ * Intake Service — the full Signal → Gate spine of UseSteady.
+ *
+ * Pipeline order (non-negotiable):
+ *   1. PRV              — lexical context-dependency check
+ *   2. Safety Gate      — unsafe inputs blocked here; never reach understanding
+ *   3. Context Alignment — semantic: social/mismatch classification
+ *   4. Disambiguation   — ambiguous term detection; unknown falls through
+ *   5. Completion       — executability authority, receives full context
+ *   6. Classify intent state
+ *   7. Plan response
+ *
+ * ── Public API ────────────────────────────────────────────────────────────────
+ *
+ *   runIntake(input, ctx)            → IntakeResult        (production use)
+ *   runIntakeWithTrace(input, ctx)   → { result, trace }   (observability / debug)
+ *
+ * Both call the same internal runPipeline. runIntake discards the trace.
+ * DebugTrace is zero-authority: it never affects the result.
+ *
+ * ── Contracts ──────────────────────────────────────────────────────────────────
+ *
+ *   CONTRACT 1: execute is only reachable via complete (step 5).
+ *               No other path produces execute.
+ *
+ *   CONTRACT 2: Completion receives UnderstandContext.
+ *               Context-dependent inputs ("run again") are resolvable in step 5.
+ *
+ *   CONTRACT 3: guidance is present if and only if mode === "guide".
+ *               No consumer re-runs completion to get next steps.
+ *
+ *   CONTRACT 4: PRV is lexical, Context Alignment is semantic.
+ *               No broad semantic reasoning in PRV.
+ *
+ *   CONTRACT 5: Public result exposes final outcome, not internal intermediates.
+ *               disambiguation `unknown` is not returned as a signal.
+ */
+import { interpretChange } from "../understand/interpretation/interpretation.js";
+import { enrichGuidance } from "../understand/intent-interpretation/intent-interpretation.js";
+import { applyGuidanceOrdering } from "../interaction/guidance-order.js";
+import { selectSilentGuidanceMode, getSilentGuidanceSteps, } from "../understand/silent-guidance/index.js";
+import { runPRV } from "../prv/prv.js";
+import { runSafetyGate } from "../safety/safety-gate.js";
+import { runContextAlignment } from "../understand/context/context-alignment.js";
+import { runDisambiguation } from "../understand/disambiguation/registry.js";
+import { runCompletion } from "../understand/completion/completion.js";
+import { safetyToSignal, contextAlignmentToSignal, disambiguationToSignal, completionToSignal, } from "./signal-extractor.js";
+import { classifyIntentState } from "./classify-intent-state.js";
+import { planResponse } from "./response-planner.js";
+function runPipeline(input, ctx) {
+    // Build UnderstandContext once — passed to context-aware layers.
+    const understandCtx = {
+        hasPriorSession: ctx.prvContext.hasPriorSession,
+        ...(ctx.prvContext.lastInput !== undefined ? { lastInput: ctx.prvContext.lastInput } : {}),
+        ...(ctx.prvContext.lastResult !== undefined ? { lastResult: ctx.prvContext.lastResult } : {}),
+    };
+    // ── Step 1: PRV ─────────────────────────────────────────────────────────────
+    const prvResult = runPRV(input, ctx.prvContext);
+    if (!prvResult.ok) {
+        const signal = { type: "hard_mismatch", source: "context" };
+        return {
+            result: { mode: "clarify", reason: prvResult.reason, signal, intentState: "ambiguous" },
+            trace: {
+                prvPassed: false,
+                safetyVerdict: "not_reached",
+                contextKind: "not_reached",
+                disambigKind: "not_reached",
+                completionKind: "not_reached",
+                bridgeFired: false,
+            },
+        };
+    }
+    // ── Step 2: Safety Gate ──────────────────────────────────────────────────────
+    const safetyResult = runSafetyGate(input);
+    const safetySignal = safetyToSignal(safetyResult);
+    if (safetySignal !== null) {
+        const state = classifyIntentState(safetySignal);
+        const decision = planResponse(state);
+        return {
+            result: {
+                mode: decision.mode,
+                reason: safetyResult.note ?? decision.reason,
+                signal: safetySignal,
+                intentState: state,
+            },
+            trace: {
+                prvPassed: true,
+                safetyVerdict: "block",
+                contextKind: "not_reached",
+                disambigKind: "not_reached",
+                completionKind: "not_reached",
+                bridgeFired: false,
+            },
+        };
+    }
+    // ── Step 3: Context Alignment ────────────────────────────────────────────────
+    const contextResult = runContextAlignment(input, understandCtx);
+    const contextSignal = contextAlignmentToSignal(contextResult);
+    if (contextSignal !== null) {
+        const state = classifyIntentState(contextSignal);
+        const decision = planResponse(state);
+        return {
+            result: {
+                mode: decision.mode,
+                reason: contextResult.kind === "hard_mismatch" ? contextResult.reason : decision.reason,
+                signal: contextSignal,
+                intentState: state,
+            },
+            trace: {
+                prvPassed: true,
+                safetyVerdict: "allow",
+                contextKind: contextResult.kind,
+                disambigKind: "not_reached",
+                completionKind: "not_reached",
+                bridgeFired: false,
+            },
+        };
+    }
+    // ── Step 4: Disambiguation ───────────────────────────────────────────────────
+    // `unknown` → null (falls through to completion per contract).
+    // `ambiguous` → short-circuit with clarify.
+    // We record the kind regardless, since both clear and unknown fall through.
+    const disambigResult = runDisambiguation(input);
+    const disambigSignal = disambiguationToSignal(disambigResult);
+    if (disambigSignal !== null) {
+        const state = classifyIntentState(disambigSignal);
+        const decision = planResponse(state);
+        return {
+            result: {
+                mode: decision.mode,
+                reason: disambigResult.kind === "ambiguous" ? disambigResult.reason : decision.reason,
+                signal: disambigSignal,
+                intentState: state,
+            },
+            trace: {
+                prvPassed: true,
+                safetyVerdict: "allow",
+                contextKind: "aligned",
+                disambigKind: disambigResult.kind,
+                completionKind: "not_reached",
+                bridgeFired: false,
+            },
+        };
+    }
+    // Record disambig kind for the trace even when falling through.
+    const tracedDisambigKind = disambigResult.kind;
+    // ── Step 5: Completion — authority on executability ──────────────────────────
+    // Receives full UnderstandContext so context-dependent inputs can be resolved.
+    const completionResult = runCompletion(input, understandCtx);
+    const completionSignal = completionToSignal(completionResult);
+    const state = classifyIntentState(completionSignal);
+    const decision = planResponse(state);
+    // CONTRACT: interpretation attempted when mode === "execute" (change interpretation, advisory).
+    if (completionResult.kind === "complete") {
+        const interpretation = interpretChange(input) ?? undefined;
+        const result = {
+            mode: decision.mode,
+            reason: decision.reason,
+            signal: completionSignal,
+            intentState: state,
+        };
+        return {
+            result: interpretation !== undefined ? { ...result, interpretation } : result,
+            trace: {
+                prvPassed: true,
+                safetyVerdict: "allow",
+                contextKind: "aligned",
+                disambigKind: tracedDisambigKind,
+                completionKind: "complete",
+                bridgeFired: false,
+            },
+        };
+    }
+    // CONTRACT: guidance present iff mode === "guide".
+    //
+    // For guided_recovery: run the Intent Interpretation Bridge to enrich guidance
+    // with intent classification and context-aware step labels.
+    //
+    // For incomplete: intent is already unambiguous (e.g. commit missing message).
+    // Bridge does not run — guidance is already specific, no interpretation needed.
+    //
+    // enrichGuidance returns null for non-guided_recovery, so the ?? fallback
+    // handles incomplete cleanly without branching.
+    const enrichedGuidance = enrichGuidance(input, completionResult, understandCtx) ?? {
+        missing: completionResult.missing,
+        nextSteps: completionResult.nextSteps,
+    };
+    // bridgeFired: bridge ran (guided_recovery OR incomplete) AND produced a classification.
+    // Both completion kinds lead to guide mode; both are eligible for bridge enrichment.
+    const bridgeEligible = completionResult.kind === "guided_recovery" || completionResult.kind === "incomplete";
+    const bridgeFired = bridgeEligible && enrichedGuidance.interpretation !== undefined;
+    // bridgeSilenceReason: set only when the bridge was eligible but no interpreter
+    // claimed the input. This is the observable runtime fact — it does not explain
+    // WHY no interpreter claimed it (that requires the formal human gate evaluation).
+    const bridgeSilenceReason = bridgeEligible && !bridgeFired ? "no_interpreter_claimed" : undefined;
+    // Phase 4C — Silent Guidance Mode (presentation-level template selection).
+    //
+    // For bridge-silent flows only, inspect the raw input for shape-level signals
+    // and replace the default code-patch nextSteps with mode-appropriate steps.
+    //
+    // CONTRACTS (non-negotiable):
+    //   - Only runs when bridgeSilenceReason === "no_interpreter_claimed"
+    //   - Does NOT produce a category, confidence, or interpretation
+    //   - Does NOT affect mode, signal, intentState, or missing[]
+    //   - Does NOT enter UCP envelopes
+    //   - Does NOT imply executability
+    //   - missing[] is always preserved unchanged
+    //   - interpretation is always preserved unchanged (undefined for silent flows)
+    const silentGuidanceMode = bridgeSilenceReason === "no_interpreter_claimed"
+        ? selectSilentGuidanceMode(input)
+        : undefined;
+    const postBridgeGuidance = silentGuidanceMode !== undefined
+        ? {
+            missing: enrichedGuidance.missing,
+            nextSteps: getSilentGuidanceSteps(silentGuidanceMode),
+            // interpretation is undefined for silent flows; spread only if present
+            ...(enrichedGuidance.interpretation !== undefined
+                ? { interpretation: enrichedGuidance.interpretation }
+                : {}),
+        }
+        : enrichedGuidance;
+    // B2 — Session-aware guidance ordering (purely presentational).
+    // Reorders steps (read_first first) and adjusts read_first label emphasis
+    // when the user is familiar with the current guidance category
+    // (FAMILIARITY_THRESHOLD observations of that category).
+    //
+    // CONTRACTS:
+    //   - Step count never changes (no add, no remove)
+    //   - missing[] never changes
+    //   - interpretation never changes
+    //   - mode, reason, intentState are already decided — this cannot affect them
+    const guidance = applyGuidanceOrdering(postBridgeGuidance, ctx.interactionContract.observedIntentPatterns);
+    return {
+        result: {
+            mode: decision.mode,
+            reason: completionResult.reason,
+            signal: completionSignal,
+            intentState: state,
+            guidance,
+        },
+        trace: {
+            prvPassed: true,
+            safetyVerdict: "allow",
+            contextKind: "aligned",
+            disambigKind: tracedDisambigKind,
+            completionKind: completionResult.kind,
+            bridgeFired,
+            ...(bridgeSilenceReason !== undefined ? { bridgeSilenceReason } : {}),
+            ...(silentGuidanceMode !== undefined ? { silentGuidanceMode } : {}),
+        },
+    };
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Run the intake pipeline and return the result.
+ * Trace is computed internally but discarded.
+ * Use for all production code paths.
+ */
+export function runIntake(input, ctx) {
+    return runPipeline(input, ctx).result;
+}
+/**
+ * Run the intake pipeline and return both the result and the debug trace.
+ * Use for observability, debugging, and developer tooling only.
+ *
+ * CONTRACT: DebugTrace is zero-authority.
+ * It records what happened; it changes nothing.
+ * Any code that reads DebugTrace to make a decision is wrong.
+ */
+export function runIntakeWithTrace(input, ctx) {
+    return runPipeline(input, ctx);
+}
+import { mapIntentToEnvelope } from "../ucp/mappers/map-intent.js";
+import { mapPRVToEnvelope } from "../ucp/mappers/map-prv.js";
+import { mapSafetyToEnvelope } from "../ucp/mappers/map-safety.js";
+import { mapContextToEnvelope } from "../ucp/mappers/map-context.js";
+import { mapDisambiguationToEnvelope } from "../ucp/mappers/map-disambiguation.js";
+import { mapCompletionToEnvelope } from "../ucp/mappers/map-completion.js";
+import { mapIntentInterpretationToEnvelope } from "../ucp/mappers/map-intent-interpretation.js";
+import { mapChangeInterpretationToEnvelope } from "../ucp/mappers/map-change-interpretation.js";
+import { mapResponseToEnvelope } from "../ucp/mappers/map-response.js";
+import { mapDebugTraceToEnvelope } from "../ucp/mappers/map-debug-trace.js";
+/**
+ * Run the intake pipeline and return the full result, debug trace, AND a UCP bundle.
+ *
+ * CONTRACT:
+ *   - The authoritative result comes from runIntakeWithTrace (unchanged).
+ *   - UCP envelopes are built by re-running each pure pipeline step to obtain
+ *     exact native types for mapper fidelity.
+ *   - Re-running pure steps is safe because all steps are deterministic functions.
+ *   - The pipeline short-circuit logic is mirrored: envelopes are only created
+ *     for steps that ran.
+ *   - runIntakeWithUCP.result === runIntakeWithTrace.result for the same inputs.
+ *   - UCP presence does NOT affect mode, guidance, safety, or any decision.
+ *
+ * DO NOT use the ucp bundle for routing or decision-making.
+ * Mode is the only handoff authority — and mode lives in result.mode.
+ */
+export function runIntakeWithUCP(input, ctx) {
+    // Step 0: Run the authoritative pipeline. This is the source of truth.
+    const { result, trace } = runPipeline(input, ctx);
+    // Intent envelope is always present — the raw input is always captured.
+    const intentEnvelope = mapIntentToEnvelope(input);
+    // Build UnderstandContext (mirrors the pipeline's internal construction).
+    const understandCtx = {
+        hasPriorSession: ctx.prvContext.hasPriorSession,
+        ...(ctx.prvContext.lastInput !== undefined ? { lastInput: ctx.prvContext.lastInput } : {}),
+        ...(ctx.prvContext.lastResult !== undefined ? { lastResult: ctx.prvContext.lastResult } : {}),
+    };
+    // ── Step 1: PRV ────────────────────────────────────────────────────────────
+    const prvResult = runPRV(input, ctx.prvContext);
+    const prvEnvelope = mapPRVToEnvelope(prvResult);
+    // Response refs: parentId + rootId always point to the intent envelope.
+    // This makes the response linkable via byParent and byRoot in the query layer.
+    const responseRefs = { parentId: intentEnvelope.id, rootId: intentEnvelope.id };
+    if (!prvResult.ok) {
+        // Pipeline short-circuited at PRV. Only intent + prv + response + trace.
+        return {
+            result,
+            trace,
+            ucp: {
+                intent: intentEnvelope,
+                prv: prvEnvelope,
+                response: mapResponseToEnvelope(result, responseRefs),
+                debugTrace: mapDebugTraceToEnvelope(trace),
+            },
+        };
+    }
+    // ── Step 2: Safety Gate ────────────────────────────────────────────────────
+    const safetyResult = runSafetyGate(input);
+    const safetyEnvelope = mapSafetyToEnvelope(safetyResult);
+    if (safetyResult.verdict === "block") {
+        return {
+            result,
+            trace,
+            ucp: {
+                intent: intentEnvelope,
+                prv: prvEnvelope,
+                safety: safetyEnvelope,
+                response: mapResponseToEnvelope(result, responseRefs),
+                debugTrace: mapDebugTraceToEnvelope(trace),
+            },
+        };
+    }
+    // ── Step 3: Context Alignment ──────────────────────────────────────────────
+    const contextResult = runContextAlignment(input, understandCtx);
+    const contextEnvelope = mapContextToEnvelope(contextResult);
+    if (contextResult.kind !== "aligned") {
+        return {
+            result,
+            trace,
+            ucp: {
+                intent: intentEnvelope,
+                prv: prvEnvelope,
+                safety: safetyEnvelope,
+                context: contextEnvelope,
+                response: mapResponseToEnvelope(result, responseRefs),
+                debugTrace: mapDebugTraceToEnvelope(trace),
+            },
+        };
+    }
+    // ── Step 4: Disambiguation ─────────────────────────────────────────────────
+    const disambigResult = runDisambiguation(input);
+    const disambigEnvelope = mapDisambiguationToEnvelope(disambigResult);
+    if (disambigResult.kind === "ambiguous") {
+        return {
+            result,
+            trace,
+            ucp: {
+                intent: intentEnvelope,
+                prv: prvEnvelope,
+                safety: safetyEnvelope,
+                context: contextEnvelope,
+                disambiguation: disambigEnvelope,
+                response: mapResponseToEnvelope(result, responseRefs),
+                debugTrace: mapDebugTraceToEnvelope(trace),
+            },
+        };
+    }
+    // ── Step 5: Completion ─────────────────────────────────────────────────────
+    const completionResult = runCompletion(input, understandCtx);
+    const completionEnvelope = mapCompletionToEnvelope(completionResult);
+    // ── Interpretation envelopes (advisory, present only when applicable) ──────
+    const changeInterpEnvelope = result.interpretation !== undefined
+        ? mapChangeInterpretationToEnvelope(result.interpretation)
+        : undefined;
+    const intentInterpEnvelope = result.guidance?.interpretation !== undefined
+        ? mapIntentInterpretationToEnvelope(result.guidance.interpretation)
+        : undefined;
+    return {
+        result,
+        trace,
+        ucp: {
+            intent: intentEnvelope,
+            prv: prvEnvelope,
+            safety: safetyEnvelope,
+            context: contextEnvelope,
+            disambiguation: disambigEnvelope,
+            completion: completionEnvelope,
+            ...(intentInterpEnvelope !== undefined ? { intentInterpretation: intentInterpEnvelope } : {}),
+            ...(changeInterpEnvelope !== undefined ? { changeInterpretation: changeInterpEnvelope } : {}),
+            response: mapResponseToEnvelope(result, responseRefs),
+            debugTrace: mapDebugTraceToEnvelope(trace),
+        },
+    };
+}
+//# sourceMappingURL=intake-service.js.map