usesteady 0.1.0-alpha.1

package/dist/src/ucp/projection.js

@@ -0,0 +1,139 @@
+/**
+ * UCP Seam Projection — Phase 2 integration layer.
+ *
+ * UCPSeamProjection is the formal shape the shell layer exposes to surfaces
+ * (CLI, web UI, or any other consumer). It is PROVABLY derived from a
+ * UCPBundle — never constructed independently.
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────────
+ *
+ * Before Phase 2, the seam exposed `PresentationOutput` — a manually maintained
+ * type that mirrored intake results but had no formal link to UCP.
+ *
+ * UCPSeamProjection replaces that. Every field maps to a specific envelope:
+ *
+ *   mode           ← bundle.response.payload.mode
+ *   badge          ← derived from mode (display only)
+ *   headline       ← bundle.intentInterpretation?.payload.summary
+ *                    OR bundle.changeInterpretation?.payload.summary
+ *                    OR bundle.response.payload.reason
+ *   category       ← human label from intentInterpretation or changeInterpretation
+ *   confidence     ← human label from intentInterpretation or changeInterpretation
+ *   steps          ← bundle.response.payload.guidance.nextSteps[].label  (enriched form)
+ *   missing        ← bundle.response.payload.guidance.missing
+ *   certaintyLevel ← derived: execute+change→certain, guide+intent→inferred, else→unknown
+ *   debugTrace     ← bundle.debugTrace.payload (all trace fields from the envelope)
+ *
+ *   envelopeIds    ← { intentId, responseId, traceId } from bundle envelope .id fields
+ *                    This is the PROOF FIELD.
+ *                    A consumer can verify that this projection came from a real UCPBundle
+ *                    by checking that envelopeIds.responseId is a valid sha256 hex string
+ *                    and matches bundle.response.id for the same input.
+ *
+ * ── Invariants ────────────────────────────────────────────────────────────────
+ *
+ *   1. projectUCPBundle is a pure function. Same bundle → same projection.
+ *   2. mode is sourced from bundle.response.payload.mode — it cannot drift.
+ *   3. envelopeIds are content-addressed. Same input → same IDs.
+ *   4. No field may be invented. Every field is derived from a named envelope.
+ *   5. A renderer MUST route on projection.mode, never on any other field.
+ *
+ * ── What this is NOT ──────────────────────────────────────────────────────────
+ *
+ *   Not a pipeline layer. Not a decision layer. Not a transport format.
+ *   It is a formal, testable projection function: f(UCPBundle) → UCPSeamProjection.
+ */
+// ─── Display name maps ────────────────────────────────────────────────────────
+const MODE_BADGES = {
+    refuse: "REFUSE",
+    ignore: "IGNORE",
+    clarify: "CLARIFY",
+    guide: "GUIDE",
+    execute: "EXECUTE",
+};
+const CONFIDENCE_LABELS = {
+    high: "High confidence",
+    medium: "Medium confidence",
+    low: "Low confidence",
+};
+const INTENT_CATEGORY_LABELS = {
+    visual_color: "Color / style change",
+    text_change: "Text / copy change",
+    config_change: "Configuration change",
+    workflow_operation: "Workflow operation",
+    unknown: "Unclassified",
+};
+const CHANGE_CATEGORY_LABELS = {
+    tailwind_color_change: "Tailwind color change",
+    css_color_change: "CSS color change",
+    text_literal_change: "Text / copy change",
+    config_value_change: "Configuration value change",
+};
+// ─── Projection function ──────────────────────────────────────────────────────
+/**
+ * Project a UCPBundle into a UCPSeamProjection.
+ *
+ * Pure function — same bundle → same projection, always.
+ * No side effects. No I/O. No randomness.
+ *
+ * Every output field documents its source envelope in the type definition above.
+ */
+export function projectUCPBundle(bundle) {
+    // ── Source: response envelope (always present) ─────────────────────────────
+    const mode = bundle.response.payload.mode;
+    const badge = MODE_BADGES[mode];
+    const reason = bundle.response.payload.reason;
+    // ── Source: interpretation envelopes (optional) ────────────────────────────
+    const intentInterp = bundle.intentInterpretation?.payload;
+    const changeInterp = bundle.changeInterpretation?.payload;
+    // ── Headline: first non-null interpretation summary, then reason ───────────
+    const headline = intentInterp !== undefined ? intentInterp.summary :
+        changeInterp !== undefined ? changeInterp.summary :
+            reason;
+    // ── Category and confidence: from whichever interpretation envelope fired ──
+    const category = intentInterp !== undefined ? INTENT_CATEGORY_LABELS[intentInterp.category] :
+        changeInterp !== undefined ? CHANGE_CATEGORY_LABELS[changeInterp.category] :
+            undefined;
+    const confidence = intentInterp !== undefined ? CONFIDENCE_LABELS[intentInterp.confidence] :
+        changeInterp !== undefined ? CONFIDENCE_LABELS[changeInterp.confidence] :
+            undefined;
+    // ── Certainty: derived from mode + interpretation presence ─────────────────
+    const certaintyLevel = mode === "execute" && changeInterp !== undefined ? "certain" :
+        mode === "guide" && intentInterp !== undefined ? "inferred" :
+            "unknown";
+    // ── Steps and missing: from the response envelope's enriched guidance ─────
+    //
+    // IMPORTANT: we use bundle.response.payload.guidance rather than
+    // bundle.completion.payload.nextSteps because:
+    //   - completion envelope = raw CompletionResult (before enrichGuidance)
+    //   - response envelope   = final IntakeResult guidance (after enrichGuidance
+    //                           + applyGuidanceOrdering, including interpretation
+    //                           labels and session-based ordering)
+    //
+    // The response envelope is the canonical, enriched form the renderer sees.
+    const responseGuidance = bundle.response.payload.guidance;
+    const steps = responseGuidance !== undefined ? responseGuidance.nextSteps.map((s) => s.label) : undefined;
+    const missing = responseGuidance !== undefined ? [...responseGuidance.missing] : undefined;
+    // ── Debug trace: from debug trace envelope payload ─────────────────────────
+    const debugTrace = bundle.debugTrace.payload;
+    // ── Proof field: content-addressed envelope IDs ────────────────────────────
+    const envelopeIds = {
+        intentId: bundle.intent.id,
+        responseId: bundle.response.id,
+        traceId: bundle.debugTrace.id,
+    };
+    // ── Assemble output (exactOptionalPropertyTypes-safe spreading) ────────────
+    return {
+        mode,
+        badge,
+        headline,
+        certaintyLevel,
+        ...(category !== undefined ? { category } : {}),
+        ...(confidence !== undefined ? { confidence } : {}),
+        ...(steps !== undefined ? { steps } : {}),
+        ...(missing !== undefined ? { missing } : {}),
+        debugTrace,
+        envelopeIds,
+    };
+}
+//# sourceMappingURL=projection.js.map

package/dist/src/ucp/projection.js.map

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