@adammcarter/use-cases 0.1.0

package/packages/core/dist/presentation/items.js

@@ -0,0 +1,228 @@
+import { choosePresentationFormat, formatToDeliveryKind } from "./presentationFormat.js";
+import { expectedObservations, policySnapshot, resolvedSteps, verificationRequirements } from "./planHelpers.js";
+/**
+ * Item transforms & plan-content assembly: turning a selected candidate into a
+ * fully-resolved plan item (delivery kind, presentation format, required
+ * evidence, evidence/freshness summaries, gaps) plus the per-mode section and
+ * plan-level gap construction that depend on the resolved items.
+ */
+export function toPlanItem(candidate, evidence, profile, _hostSurface) {
+    const useCase = candidate.useCase;
+    const evidenceSummary = evidenceForUseCase(evidence, useCase);
+    const requiredEvidence = requiredEvidenceFor(useCase, evidenceSummary.status);
+    const gaps = gapsForItem(useCase, evidenceSummary.readiness, requiredEvidence);
+    const baseDeliveryKind = baseDeliveryKindFor(useCase, profile.mode);
+    const presentationFormat = choosePresentationFormat({
+        baseDeliveryKind,
+        needsUser: needsUserActor(useCase),
+        // v1: auto-selection emits testing / reviewing / explaining / user_led.
+        // `comparing` and `inspecting` are reachable only via hand-authored plans
+        // until row affordances (isContrast / artifact hints) land -- see the spec
+        // open questions.
+        isContrast: false
+    });
+    const deliveryKind = formatToDeliveryKind(presentationFormat, baseDeliveryKind);
+    return {
+        plan_item_id: `item.${useCase.value.id}`,
+        presentation_format: presentationFormat,
+        delivery_kind: deliveryKind,
+        scenario_scope: useCase.value.scenarios?.length ? "explicit" : "whole_use_case",
+        use_case_id: useCase.value.id,
+        scenario_ids: (useCase.value.scenarios ?? []).map((scenario) => scenario.id),
+        use_case_content_hash: useCase.semanticHash,
+        estimated_seconds: profile.fallbackEstimateSeconds,
+        estimate_source: "default_profile",
+        setup_steps: [],
+        resolved_steps: resolvedSteps(useCase),
+        expected_observations: expectedObservations(useCase),
+        teardown_steps: [],
+        required_permissions: [],
+        safety_constraints: [],
+        verification_policy_snapshot: policySnapshot(useCase.value.verification_policy),
+        approval_policy_snapshot: policySnapshot(useCase.value.approval_policy),
+        approval_resolution_required_at_run_start: policySnapshot(useCase.value.approval_policy).mode === "ask",
+        required_evidence: requiredEvidence,
+        evidence_summary: {
+            readiness: evidenceSummary.readiness,
+            active_evidence_ids: evidenceSummary.activeEvidenceIds,
+            basis: evidenceSummary.basis
+        },
+        freshness_summary: {
+            state: evidenceSummary.freshnessState,
+            basis: evidenceSummary.freshnessBasis
+        },
+        known_gaps: gaps,
+        selection_reasons: candidate.reasons,
+        selection_reason_codes: candidate.reasonCodes,
+        score_components: candidate.scoreComponents
+    };
+}
+/**
+ * The base (verification-derived) delivery kind for an item before a
+ * presentation format is chosen. Showcase prefers live-where-safe: it keeps
+ * `live_demo` whenever the row carries live_demo verification, otherwise it
+ * falls back to the same projection walkthrough uses. This replaces the old
+ * hard `showcase ? "live_demo"` force so destructive / external / human-judgment
+ * rows get an honest base kind.
+ */
+function baseDeliveryKindFor(useCase, mode) {
+    if (mode === "showcase") {
+        const requirements = verificationRequirements(useCase);
+        if (requirements.some((requirement) => requirement.evidence_kind === "live_demo")) {
+            return "live_demo";
+        }
+    }
+    return deliveryKindFor(useCase);
+}
+/**
+ * True when an item needs a human actor: any verification requirement that
+ * lists `user` among its required verifiers, or an approval policy in `ask`
+ * mode. Such items are presented with the `user_led` (Over to you) format.
+ */
+function needsUserActor(useCase) {
+    const requirements = verificationRequirements(useCase);
+    if (requirements.some((requirement) => requirement.required_verifiers.includes("user"))) {
+        return true;
+    }
+    return policySnapshot(useCase.value.approval_policy).mode === "ask";
+}
+function deliveryKindFor(useCase) {
+    const requirements = verificationRequirements(useCase);
+    if (requirements.some((requirement) => requirement.evidence_kind === "live_demo")) {
+        return "live_demo";
+    }
+    if (requirements.length > 0) {
+        return "evidence_review";
+    }
+    return "explanation";
+}
+function evidenceForUseCase(evidence, useCase) {
+    if (!evidence.complete && evidence.integrity.unknownScopeDamage) {
+        return {
+            readiness: "unknown",
+            activeEvidenceIds: [],
+            status: "unknown_due_to_integrity",
+            basis: "evidence_integrity_incomplete",
+            freshnessState: "unknown",
+            freshnessBasis: "evidence_integrity_incomplete"
+        };
+    }
+    const matching = evidence.aggregates.filter((aggregate) => aggregate.status === "active" &&
+        aggregate.targetLinks.some((target) => target.use_case_id === useCase.value.id));
+    if (matching.length === 0) {
+        return {
+            readiness: "missing",
+            activeEvidenceIds: [],
+            status: "missing",
+            basis: "no_active_evidence",
+            freshnessState: "unknown",
+            freshnessBasis: "missing_evidence"
+        };
+    }
+    const semanticMatches = matching.some((aggregate) => aggregate.targetLinks.some((target) => target.use_case_id === useCase.value.id && target.use_case_semantic_hash === useCase.semanticHash));
+    return {
+        readiness: semanticMatches ? "available_current" : "available_stale",
+        activeEvidenceIds: matching.map((aggregate) => aggregate.evidenceId),
+        status: "candidate_observed",
+        basis: semanticMatches ? "active_evidence_semantic_hash_match" : "active_evidence_semantic_hash_mismatch",
+        freshnessState: semanticMatches ? "current" : "needs_review",
+        freshnessBasis: semanticMatches ? "policy_match" : "use_case_semantic_hash_mismatch"
+    };
+}
+function requiredEvidenceFor(useCase, status) {
+    const requirements = verificationRequirements(useCase);
+    if (requirements.length === 0) {
+        return [
+            {
+                evidence_kind: "manual_observation",
+                required_verifiers: [],
+                minimum_count: 1,
+                status: "not_applicable"
+            }
+        ];
+    }
+    return requirements.map((requirement) => ({
+        evidence_kind: requirement.evidence_kind,
+        required_verifiers: requirement.required_verifiers,
+        minimum_count: requirement.minimum_count,
+        status
+    }));
+}
+function gapsForItem(useCase, readiness, requiredEvidence) {
+    const gaps = [];
+    if (requiredEvidence.some((requirement) => requirement.status === "missing")) {
+        gaps.push({
+            code: "evidence_missing",
+            message: "Required evidence is missing; live performance is still required.",
+            severity: "warning"
+        });
+    }
+    if (readiness === "available_stale") {
+        gaps.push({
+            code: "evidence_needs_review",
+            message: "Existing evidence targets an older use-case semantic hash.",
+            severity: "warning"
+        });
+    }
+    if (useCase.value.approval_policy && policySnapshot(useCase.value.approval_policy).mode === "ask") {
+        gaps.push({
+            code: "approval_resolution_required",
+            message: "Approval policy must be resolved during the later live run.",
+            severity: "info"
+        });
+    }
+    if (gaps.length === 0) {
+        gaps.push({
+            code: "prepared_not_performed",
+            message: "This is a prepared plan and has not been performed.",
+            severity: "info"
+        });
+    }
+    return gaps;
+}
+export function planGaps(incompleteInput) {
+    return incompleteInput
+        ? [
+            {
+                code: "input_integrity_partial",
+                message: "The plan was generated from partial input and requires acknowledgement before execution.",
+                severity: "warning"
+            }
+        ]
+        : [
+            {
+                code: "prepared_not_performed",
+                message: "The plan is prepared only; no live run has been performed.",
+                severity: "info"
+            }
+        ];
+}
+export function sectionsFor(mode, selectedItems) {
+    if (mode === "showcase") {
+        return [
+            {
+                section_id: "section.primary-path",
+                title: "Primary path",
+                purpose: "Show the highest-value user-visible behavior.",
+                item_ids: selectedItems.map((item) => item.plan_item_id)
+            }
+        ];
+    }
+    const primary = selectedItems.filter((item) => item.use_case_id.includes(".golden")).map((item) => item.plan_item_id);
+    const coverage = selectedItems.filter((item) => !primary.includes(item.plan_item_id)).map((item) => item.plan_item_id);
+    return [
+        {
+            section_id: "section.primary-path",
+            title: "Primary path",
+            purpose: "Establish the main product value.",
+            item_ids: primary.length > 0 ? primary : selectedItems.slice(0, 1).map((item) => item.plan_item_id)
+        },
+        {
+            section_id: "section.coverage",
+            title: "Coverage",
+            purpose: "Walk through alternate, edge, negative, and failure behavior.",
+            item_ids: coverage.length > 0 ? coverage : selectedItems.map((item) => item.plan_item_id)
+        }
+    ];
+}
+//# sourceMappingURL=items.js.map

package/packages/core/dist/presentation/items.js.map

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

package/packages/core/dist/presentation/ordering.d.ts

@@ -0,0 +1,8 @@
+import type { PresentationCandidate } from "./types.js";
+/**
+ * Walkthrough ordering: arrange eligible candidates into a narrative order —
+ * a golden critical/core item first, then one of each coverage journey role
+ * (alternate, edge, negative, failure), then the remainder by comparator order.
+ */
+export declare function orderWalkthrough(candidates: PresentationCandidate[]): PresentationCandidate[];
+//# sourceMappingURL=ordering.d.ts.map

package/packages/core/dist/presentation/ordering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordering.d.ts","sourceRoot":"","sources":["../../src/presentation/ordering.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,qBAAqB,EAAE,GAAG,qBAAqB,EAAE,CAkB7F"}

package/packages/core/dist/presentation/ordering.js

@@ -0,0 +1,31 @@
+import { compareCandidates } from "./scoring.js";
+/**
+ * Walkthrough ordering: arrange eligible candidates into a narrative order —
+ * a golden critical/core item first, then one of each coverage journey role
+ * (alternate, edge, negative, failure), then the remainder by comparator order.
+ */
+export function orderWalkthrough(candidates) {
+    const ordered = [];
+    const used = new Set();
+    const sorted = candidates.slice().sort(compareCandidates);
+    takeFirst(sorted, used, ordered, (candidate) => candidate.useCase.value.journey_role === "golden" &&
+        (candidate.useCase.value.value_tier === "critical" || candidate.useCase.value.value_tier === "core"));
+    for (const role of ["alternate", "edge", "negative", "failure"]) {
+        takeFirst(sorted, used, ordered, (candidate) => candidate.useCase.value.journey_role === role);
+    }
+    for (const candidate of sorted) {
+        if (!used.has(candidate.useCase.value.id)) {
+            used.add(candidate.useCase.value.id);
+            ordered.push(candidate);
+        }
+    }
+    return ordered;
+}
+function takeFirst(candidates, used, ordered, predicate) {
+    const match = candidates.find((candidate) => !used.has(candidate.useCase.value.id) && predicate(candidate));
+    if (match) {
+        used.add(match.useCase.value.id);
+        ordered.push(match);
+    }
+}
+//# sourceMappingURL=ordering.js.map

package/packages/core/dist/presentation/ordering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ordering.js","sourceRoot":"","sources":["../../src/presentation/ordering.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD;;;;GAIG;AAEH,MAAM,UAAU,gBAAgB,CAAC,UAAmC;IAClE,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1D,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAC7C,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,QAAQ;QACjD,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,UAAU,IAAI,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,KAAK,MAAM,CAAC,CACrG,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,CAAU,EAAE,CAAC;QACzE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC;IACjG,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,SAAS,CAChB,UAAmC,EACnC,IAAiB,EACjB,OAAgC,EAChC,SAAwD;IAExD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5G,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/packages/core/dist/presentation/planHelpers.d.ts

@@ -0,0 +1,26 @@
+import type { LoadedUseCase } from "../useCases/types.js";
+/**
+ * Low-level, dependency-free helpers shared across the presentation planning
+ * modules: path normalisation, use-case fact extraction (steps / observations /
+ * verification requirements) and small type guards. These have no dependency on
+ * the other presentation modules, so they can be imported anywhere without risk
+ * of an import cycle.
+ */
+export declare function resolvedSteps(useCase: LoadedUseCase): string[];
+export declare function expectedObservations(useCase: LoadedUseCase): string[];
+export declare function verificationRequirements(useCase: LoadedUseCase): Array<{
+    evidence_kind: string;
+    required_verifiers: string[];
+    minimum_count: number;
+}>;
+export declare function normalizePaths(paths: readonly string[]): string[];
+export declare function normalizePath(path: string): string;
+export declare function uniqueStrings(values: string[]): string[];
+export declare function policySnapshot(value: unknown): Record<string, unknown>;
+export declare function isRequirement(value: unknown): value is {
+    evidence_kind: string;
+    required_verifiers: string[];
+    minimum_count: number;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=planHelpers.d.ts.map

package/packages/core/dist/presentation/planHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planHelpers.d.ts","sourceRoot":"","sources":["../../src/presentation/planHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;GAMG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAW9D;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,EAAE,CAUrE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,aAAa,GAAG,KAAK,CAAC;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAYD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEjE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAExD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;CACvB,CAQA;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE"}

package/packages/core/dist/presentation/planHelpers.js

@@ -0,0 +1,62 @@
+/**
+ * Low-level, dependency-free helpers shared across the presentation planning
+ * modules: path normalisation, use-case fact extraction (steps / observations /
+ * verification requirements) and small type guards. These have no dependency on
+ * the other presentation modules, so they can be imported anywhere without risk
+ * of an import cycle.
+ */
+export function resolvedSteps(useCase) {
+    const scenarioSteps = (useCase.value.scenarios ?? []).flatMap((scenario) => {
+        if ("steps" in scenario && Array.isArray(scenario.steps)) {
+            return scenario.steps;
+        }
+        const given = "given" in scenario && Array.isArray(scenario.given) ? scenario.given : [];
+        const when = "when" in scenario && Array.isArray(scenario.when) ? scenario.when : [];
+        const then = "then" in scenario && Array.isArray(scenario.then) ? scenario.then : [];
+        return [...given, ...when, ...then];
+    });
+    return scenarioSteps.filter((step) => typeof step === "string" && step.length > 0);
+}
+export function expectedObservations(useCase) {
+    const scenarioOutcomes = (useCase.value.scenarios ?? []).flatMap((scenario) => "observable_outcomes" in scenario && Array.isArray(scenario.observable_outcomes)
+        ? scenario.observable_outcomes
+        : []);
+    const useCaseOutcomes = Array.isArray(useCase.value.observable_outcomes) ? useCase.value.observable_outcomes : [];
+    return uniqueStrings([...scenarioOutcomes, ...useCaseOutcomes].filter((outcome) => typeof outcome === "string" && outcome.length > 0));
+}
+export function verificationRequirements(useCase) {
+    const policy = policySnapshot(useCase.value.verification_policy);
+    if (policy.mode !== "requirements" || !Array.isArray(policy.requirements)) {
+        return [];
+    }
+    return policy.requirements
+        .filter(isRequirement)
+        .map((requirement) => ({
+        evidence_kind: requirement.evidence_kind,
+        required_verifiers: requirement.required_verifiers,
+        minimum_count: requirement.minimum_count
+    }));
+}
+export function normalizePaths(paths) {
+    return paths.map(normalizePath).sort();
+}
+export function normalizePath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+export function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
+export function policySnapshot(value) {
+    return isRecord(value) ? value : { mode: "none" };
+}
+export function isRequirement(value) {
+    return (isRecord(value) &&
+        typeof value.evidence_kind === "string" &&
+        Array.isArray(value.required_verifiers) &&
+        value.required_verifiers.every((item) => typeof item === "string") &&
+        typeof value.minimum_count === "number");
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=planHelpers.js.map

package/packages/core/dist/presentation/planHelpers.js.map

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

package/packages/core/dist/presentation/presentationFormat.d.ts

@@ -0,0 +1,39 @@
+import type { DeliveryKind } from "./types.js";
+/**
+ * The six presentation formats. The agent picks exactly one per item up front
+ * and surfaces it to the user with a fixed, scannable header + body.
+ */
+export type PresentationFormat = "testing" | "comparing" | "inspecting" | "reviewing" | "user_led" | "explaining";
+export type FormatActor = "agent" | "user";
+export type FormatMeta = {
+    emoji: string;
+    verb: string;
+    descriptor: string;
+    actor: FormatActor;
+};
+/**
+ * Single source of truth for the format emoji + header copy. The emoji are
+ * load-bearing and live ONLY here; every other module references this table so
+ * render and selection stay consistent.
+ */
+export declare const FORMAT_META: Record<PresentationFormat, FormatMeta>;
+/**
+ * Project a chosen format onto the legacy `delivery_kind` enum. `user_led` has
+ * no native delivery_kind, so it falls back to the verification-derived base
+ * kind supplied by selection.
+ */
+export declare function formatToDeliveryKind(format: PresentationFormat, baseDeliveryKind: DeliveryKind): DeliveryKind;
+/** The default format for a verification-derived delivery kind. */
+export declare function defaultFormatForDeliveryKind(kind: DeliveryKind): PresentationFormat;
+export type ChoosePresentationFormatOptions = {
+    baseDeliveryKind: DeliveryKind;
+    needsUser?: boolean;
+    isContrast?: boolean;
+};
+/**
+ * Pick a presentation format from the base delivery kind plus two affordances:
+ * `needsUser` (human-in-the-loop) wins first, then `isContrast` (guardrail /
+ * before-after), otherwise the default-for-delivery-kind.
+ */
+export declare function choosePresentationFormat(options: ChoosePresentationFormatOptions): PresentationFormat;
+//# sourceMappingURL=presentationFormat.d.ts.map

package/packages/core/dist/presentation/presentationFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentationFormat.d.ts","sourceRoot":"","sources":["../../src/presentation/presentationFormat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,WAAW,GACX,YAAY,GACZ,WAAW,GACX,UAAU,GACV,YAAY,CAAC;AAEjB,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAO9D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,YAAY,GAAG,YAAY,CAa7G;AAED,mEAAmE;AACnE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,CASnF;AAED,MAAM,MAAM,+BAA+B,GAAG;IAC5C,gBAAgB,EAAE,YAAY,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,kBAAkB,CAQrG"}

package/packages/core/dist/presentation/presentationFormat.js

@@ -0,0 +1,58 @@
+/**
+ * Single source of truth for the format emoji + header copy. The emoji are
+ * load-bearing and live ONLY here; every other module references this table so
+ * render and selection stay consistent.
+ */
+export const FORMAT_META = {
+    testing: { emoji: "🧪", verb: "Testing", descriptor: "runs it live", actor: "agent" },
+    comparing: { emoji: "⚖️", verb: "Comparing", descriptor: "guardrail / before-after", actor: "agent" },
+    inspecting: { emoji: "🔎", verb: "Inspecting", descriptor: "examine the real artifact", actor: "agent" },
+    reviewing: { emoji: "📜", verb: "Reviewing", descriptor: "cite an earlier run", actor: "agent" },
+    user_led: { emoji: "🙋", verb: "Over to you", descriptor: "needs the human", actor: "user" },
+    explaining: { emoji: "💬", verb: "Explaining", descriptor: "description only", actor: "agent" }
+};
+/**
+ * Project a chosen format onto the legacy `delivery_kind` enum. `user_led` has
+ * no native delivery_kind, so it falls back to the verification-derived base
+ * kind supplied by selection.
+ */
+export function formatToDeliveryKind(format, baseDeliveryKind) {
+    switch (format) {
+        case "testing":
+        case "comparing":
+            return "live_demo";
+        case "inspecting":
+        case "reviewing":
+            return "evidence_review";
+        case "explaining":
+            return "explanation";
+        case "user_led":
+            return baseDeliveryKind;
+    }
+}
+/** The default format for a verification-derived delivery kind. */
+export function defaultFormatForDeliveryKind(kind) {
+    switch (kind) {
+        case "live_demo":
+            return "testing";
+        case "evidence_review":
+            return "reviewing";
+        case "explanation":
+            return "explaining";
+    }
+}
+/**
+ * Pick a presentation format from the base delivery kind plus two affordances:
+ * `needsUser` (human-in-the-loop) wins first, then `isContrast` (guardrail /
+ * before-after), otherwise the default-for-delivery-kind.
+ */
+export function choosePresentationFormat(options) {
+    if (options.needsUser) {
+        return "user_led";
+    }
+    if (options.isContrast) {
+        return "comparing";
+    }
+    return defaultFormatForDeliveryKind(options.baseDeliveryKind);
+}
+//# sourceMappingURL=presentationFormat.js.map

package/packages/core/dist/presentation/presentationFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presentationFormat.js","sourceRoot":"","sources":["../../src/presentation/presentationFormat.ts"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAA2C;IACjE,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE;IACrF,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,0BAA0B,EAAE,KAAK,EAAE,OAAO,EAAE;IACrG,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,2BAA2B,EAAE,KAAK,EAAE,OAAO,EAAE;IACxG,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE;IAChG,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,EAAE;IAC5F,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,KAAK,EAAE,OAAO,EAAE;CAChG,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA0B,EAAE,gBAA8B;IAC7F,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,SAAS,CAAC;QACf,KAAK,WAAW;YACd,OAAO,WAAW,CAAC;QACrB,KAAK,YAAY,CAAC;QAClB,KAAK,WAAW;YACd,OAAO,iBAAiB,CAAC;QAC3B,KAAK,YAAY;YACf,OAAO,aAAa,CAAC;QACvB,KAAK,UAAU;YACb,OAAO,gBAAgB,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,4BAA4B,CAAC,IAAkB;IAC7D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,WAAW;YACd,OAAO,SAAS,CAAC;QACnB,KAAK,iBAAiB;YACpB,OAAO,WAAW,CAAC;QACrB,KAAK,aAAa;YAChB,OAAO,YAAY,CAAC;IACxB,CAAC;AACH,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAwC;IAC/E,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,4BAA4B,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAChE,CAAC"}

package/packages/core/dist/presentation/renderCard.d.ts

@@ -0,0 +1,37 @@
+import type { PresentationPlanItem } from "./types.js";
+/**
+ * A recorded outcome for an item, supplied at render time. Absent => the
+ * prepared / open card (no live claim). All non-ASCII glyphs in this module are
+ * written as `\u` escapes so the canonical emoji stay solely in FORMAT_META.
+ */
+export type RenderResult = {
+    /** A live status. Only Testing / Comparing may carry one. */
+    status?: "pass" | "fail";
+    /** What was actually observed. */
+    got?: string;
+    /** The recorded evidence id backing a `pass`. A pass checkmark requires this. */
+    evidenceId?: string;
+    /** True only when a human answered an "Over to you" prompt. */
+    answeredByHuman?: boolean;
+};
+/** Thrown when a render would let the header verb lie. */
+export declare class HonestyRuleError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Render the fixed, scannable card for a plan item. Pure and deterministic.
+ * Enforces the render-time honesty rule: the emoji + verb is a promise that
+ * cannot be broken (a failed live test cannot become an explanation; a `pass`
+ * checkmark needs real recorded evidence; an "Over to you" prompt can only be
+ * answered by a human).
+ *
+ * Trust boundary: this is a pure function over the supplied `result`. It cannot
+ * see a result that the caller withholds (a recorded live failure rendered with
+ * no result reads as pending), and it trusts `answeredByHuman` as supplied. The
+ * upstream guarantee -- that a result/answer is bound to a real recorded,
+ * human-origin run event -- is enforced by the evidence/showcase ledger and the
+ * deferred per-claim evidence-verifier contract (see the spec), not here.
+ */
+export declare function renderCard(item: PresentationPlanItem, result?: RenderResult): string;
+//# sourceMappingURL=renderCard.d.ts.map

package/packages/core/dist/presentation/renderCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderCard.d.ts","sourceRoot":"","sources":["../../src/presentation/renderCard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,0DAA0D;AAC1D,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADrB,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,MAAM;CAKxB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CASpF"}