@adammcarter/use-cases 0.1.0

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

@@ -0,0 +1,172 @@
+import type { ResolvedWorkspaceContext } from "../roots.js";
+import type { EvidenceSnapshot } from "../evidence/types.js";
+import type { HostSurface, LoadedUseCase, MatrixSnapshot, UseCaseV1 } from "../useCases/types.js";
+import type { PresentationFormat } from "./presentationFormat.js";
+export type PresentationMode = "showcase" | "walkthrough";
+export type PlanReadiness = "ready" | "ready_with_evidence_gaps" | "partial_due_to_integrity" | "blocked";
+export type PresentationPlanOutcome = "generated" | "no_eligible_items" | "integrity_blocked";
+export type DeliveryKind = "live_demo" | "evidence_review" | "explanation";
+export type PresentationPlanRequest = {
+    audience: string;
+    timeboxSeconds: number;
+    maxItems?: number;
+    hostSurface?: HostSurface;
+    changedPaths?: readonly string[];
+    requestedUseCaseIds?: readonly string[];
+    generatedAt?: string;
+    freshnessEvaluatedAt?: string;
+    strict?: boolean;
+};
+export type PresentationPlanSelectionOptions = {
+    context: ResolvedWorkspaceContext;
+    matrix: MatrixSnapshot;
+    evidence: EvidenceSnapshot;
+    request: PresentationPlanRequest;
+};
+export type PlanGap = {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "error";
+};
+export type RequiredEvidenceSummary = {
+    evidence_kind: string;
+    required_verifiers: string[];
+    minimum_count: number;
+    status: "candidate_observed" | "missing" | "unknown_due_to_integrity" | "not_applicable";
+};
+export type EvidenceReadiness = "available_current" | "available_stale" | "missing" | "invalid" | "unknown" | "ambiguous";
+export type PresentationPlanItem = {
+    plan_item_id: string;
+    /** The chosen presentation format -- the source of truth for how the item is shown. */
+    presentation_format: PresentationFormat;
+    /** Computed compatibility projection of `presentation_format` for legacy consumers. */
+    delivery_kind: DeliveryKind;
+    scenario_scope: "whole_use_case" | "explicit";
+    use_case_id: string;
+    scenario_ids: string[];
+    use_case_content_hash: string;
+    estimated_seconds: number;
+    estimate_source: "use_case" | "default_profile";
+    setup_steps: string[];
+    resolved_steps: string[];
+    expected_observations: string[];
+    teardown_steps: string[];
+    required_permissions: string[];
+    safety_constraints: string[];
+    verification_policy_snapshot: Record<string, unknown>;
+    approval_policy_snapshot: Record<string, unknown>;
+    approval_resolution_required_at_run_start: boolean;
+    required_evidence: RequiredEvidenceSummary[];
+    evidence_summary: {
+        readiness: EvidenceReadiness;
+        active_evidence_ids: string[];
+        basis: string;
+    };
+    freshness_summary: {
+        state: "current" | "needs_review" | "stale" | "unknown" | "invalidated";
+        basis: string;
+    };
+    known_gaps: PlanGap[];
+    selection_reasons: string[];
+    selection_reason_codes: string[];
+    score_components: Record<string, number>;
+};
+export type PresentationPlanSection = {
+    section_id: string;
+    title: string;
+    purpose: string;
+    item_ids: string[];
+};
+export type PresentationPlanExclusion = {
+    use_case_id: string;
+    reason_code: string;
+    reason: string;
+    blocking: boolean;
+};
+export type PresentationPlan = {
+    schema_version: 1;
+    plan_id: string;
+    plan_content_hash: string;
+    generated_at: string;
+    mode: PresentationMode;
+    complete: boolean;
+    prepared_not_performed: true;
+    readiness: PlanReadiness;
+    integrity_acknowledgement_required: boolean;
+    selection_method: "deterministic";
+    selection_profile: {
+        id: string;
+        version: 1;
+        digest: string;
+    };
+    input_snapshot: {
+        matrix_digest: string;
+        evidence_basis_digest: string;
+        changed_paths: string[];
+        freshness_policy: {
+            id: string;
+            digest: string;
+            evaluated_at: string;
+        };
+        host_surface: HostSurface;
+        workflow: {
+            effective_mode: string;
+            source: "default" | "workspace_config";
+            advisory: true;
+        };
+    };
+    workspace_snapshot: {
+        repository_id: string;
+        vcs: "git" | "none" | "unknown";
+        head_revision: string;
+        dirty: boolean;
+        working_tree_digest: string;
+        component_id: string;
+        captured_at: string;
+    };
+    environment_expectations: {
+        host_surfaces: HostSurface[];
+    };
+    audience: string;
+    timebox_seconds: number;
+    sections: PresentationPlanSection[];
+    selected_items: PresentationPlanItem[];
+    exclusions: PresentationPlanExclusion[];
+    known_gaps: PlanGap[];
+};
+export type CandidateSummary = {
+    considered: number;
+    eligible: number;
+    selected: number;
+    excluded: number;
+    excluded_by_reason: Record<string, number>;
+};
+export type PresentationPlanResult = {
+    schema_version: 1;
+    outcome: PresentationPlanOutcome;
+    plan: PresentationPlan | null;
+    candidate_summary: CandidateSummary;
+    input_integrity: {
+        matrix: "clean" | "partial" | "unusable";
+        evidence: "clean" | "partial" | "unusable";
+    };
+};
+export type PresentationCandidate = {
+    useCase: LoadedUseCase;
+    eligible: boolean;
+    exclusion?: PresentationPlanExclusion;
+    changed: boolean;
+    scoreComponents: Record<string, number>;
+    reasonCodes: string[];
+    reasons: string[];
+};
+export type SelectionProfile = {
+    id: "showcase-v1" | "walkthrough-v1";
+    mode: PresentationMode;
+    defaultTimeboxSeconds: number;
+    defaultMaxItems: number;
+    fallbackEstimateSeconds: number;
+};
+export type { EvidenceSnapshot, HostSurface, LoadedUseCase, MatrixSnapshot, UseCaseV1 };
+export type { PresentationFormat };
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/presentation/types.ts"],"names":[],"mappings":""}

package/packages/core/dist/redact.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Conservative, high-confidence secret redaction shared across the durable
+ * ledgers (captured command output, showcase observations, evidence summaries).
+ *
+ * The patterns are deliberately narrow so legitimate prose is not mangled:
+ * a keyword only matches when it is immediately followed by an assignment
+ * (`:`/`=`) and a value, and the token patterns require their well-known
+ * fixed prefixes plus a minimum length. No broad/greedy patterns.
+ */
+export declare function redactSecrets(value: string): string;
+//# sourceMappingURL=redact.d.ts.map

package/packages/core/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/packages/core/dist/redact.js

@@ -0,0 +1,17 @@
+/**
+ * Conservative, high-confidence secret redaction shared across the durable
+ * ledgers (captured command output, showcase observations, evidence summaries).
+ *
+ * The patterns are deliberately narrow so legitimate prose is not mangled:
+ * a keyword only matches when it is immediately followed by an assignment
+ * (`:`/`=`) and a value, and the token patterns require their well-known
+ * fixed prefixes plus a minimum length. No broad/greedy patterns.
+ */
+export function redactSecrets(value) {
+    return value
+        .replace(/\b(secret|token|password|api[_-]?key)\s*[:=]\s*[^\s]+/gi, (_match, label) => `${label}=[redacted]`)
+        .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "sk-[redacted]")
+        .replace(/\bgh[oprsu]_[A-Za-z0-9]{20,}\b/g, (match) => `${match.slice(0, 4)}[redacted]`)
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "AKIA[redacted]");
+}
+//# sourceMappingURL=redact.js.map

package/packages/core/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK;SACT,OAAO,CAAC,yDAAyD,EAAE,CAAC,MAAM,EAAE,KAAa,EAAE,EAAE,CAAC,GAAG,KAAK,aAAa,CAAC;SACpH,OAAO,CAAC,2BAA2B,EAAE,eAAe,CAAC;SACrD,OAAO,CAAC,iCAAiC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,CAAC;SACvF,OAAO,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAAC;AACxD,CAAC"}

package/packages/core/dist/roots.d.ts

@@ -0,0 +1,81 @@
+import { type Diagnostic } from "./schema/index.js";
+export type ResolveWorkspaceContextOptions = {
+    workspaceRoot?: string;
+    dataRootOverride?: string;
+    component?: string;
+    pluginRoot?: string;
+};
+export type ResolvedWorkspaceContext = {
+    plugin_root: string;
+    workspace_root: string;
+    data_root: string;
+    use_cases_root: string;
+    component_id: string;
+    config_path: string | null;
+    verifiers: ResolvedWorkspaceVerifiers;
+    release_gate?: WorkspaceReleaseGate;
+    provenance: {
+        workspace_root: "explicit" | "cwd";
+        data_root: "override" | "workspace_config" | "default";
+        use_cases_root: "workspace_config" | "default";
+        component_id: "option" | "workspace_config" | "default";
+    };
+    diagnostics: Diagnostic[];
+};
+export type WorkspaceVerifierEntry = {
+    kind: "script";
+    evidence_kind: string;
+    command: string[];
+    inputs?: string[];
+    timeout_seconds?: number;
+} | {
+    preset: string;
+    evidence_kind?: string;
+    inputs?: string[];
+    timeout_seconds?: number;
+};
+export type WorkspaceVerifiersConfig = {
+    default?: string;
+} & {
+    [verifierId: string]: WorkspaceVerifierEntry | string | undefined;
+};
+export type ResolvedWorkspaceVerifiers = {
+    default?: string;
+    verifiers: Record<string, WorkspaceVerifierEntry>;
+};
+export type WorkspaceReleaseGate = {
+    required_authority?: "ci";
+    require_protected_ref?: boolean;
+};
+export declare function resolveWorkspaceContext(options?: ResolveWorkspaceContextOptions): ResolvedWorkspaceContext;
+export declare const WORKSPACE_NOT_FOUND_CODE = "workspace.not_found";
+export declare function workspaceNotFoundDiagnostic(workspaceRoot: string): Diagnostic | null;
+export declare const CANONICAL_ID_PATTERN: RegExp;
+/** True when `value` is a string matching the canonical id pattern. */
+export declare function isValidId(value: unknown): value is string;
+/**
+ * Throw a stable `path.invalid_id` error (mapped to public `UCM_INVALID_ID`)
+ * when `value` is not a canonical id. Use this at every boundary where a
+ * user-supplied id becomes a filesystem path segment or a ledger lookup key,
+ * BEFORE the id is joined into a path, so traversal can never reach the disk.
+ */
+export declare function assertValidId(value: unknown, paramName: string): asserts value is string;
+/**
+ * True when `target` stays inside `root` after resolving symlinks. Both sides are
+ * realpath-resolved (root, and the existing prefix of target) so the check is
+ * symlink-safe AND immune to symlinked-tmpdir aliasing (e.g. macOS /var -> /private/var):
+ * a lexical-only compare would wrongly reject an in-workspace absolute path whose root
+ * was realpath'd to a different prefix. Resolving the target only stats the path — it
+ * never reads file contents — so an escaping path is rejected before it can be opened.
+ */
+export declare function isPathContained(root: string, target: string): boolean;
+/**
+ * SECURITY: bound a user-supplied file path to `root`, symlink-safe. Returns the
+ * resolved absolute path, or throws a stable `path.escape` (public UCM_PATH_ESCAPE)
+ * UseCasesPluginError when the path — after resolving symlinks on its existing
+ * prefix — escapes `root`. Use at every boundary where an attacker-
+ * controlled path (`--plan-file`, a host projection target, ...) becomes a
+ * filesystem read or write, BEFORE the path is opened.
+ */
+export declare function resolveContainedPath(root: string, candidate: string, message?: string): string;
+//# sourceMappingURL=roots.d.ts.map

package/packages/core/dist/roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roots.d.ts","sourceRoot":"","sources":["../src/roots.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,MAAM,8BAA8B,GAAG;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAI3B,SAAS,EAAE,0BAA0B,CAAC;IAKtC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,UAAU,EAAE;QACV,cAAc,EAAE,UAAU,GAAG,KAAK,CAAC;QACnC,SAAS,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;QACvD,cAAc,EAAE,kBAAkB,GAAG,SAAS,CAAC;QAC/C,YAAY,EAAE,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAAC;KACzD,CAAC;IACF,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAKF,MAAM,MAAM,sBAAsB,GAC9B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAIN,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG;IACF,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,GAAG,MAAM,GAAG,SAAS,CAAC;CACnE,CAAC;AAKF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACnD,CAAC;AAKF,MAAM,MAAM,oBAAoB,GAAG;IACjC,kBAAkB,CAAC,EAAE,IAAI,CAAC;IAC1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAUF,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,wBAAwB,CAuC1B;AAID,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAgB9D,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAIpF;AAwGD,eAAO,MAAM,oBAAoB,QAAoD,CAAC;AAEtF,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAOxF;AA+BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKrE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,SAAyC,GAC/C,MAAM,CAMR"}

package/packages/core/dist/roots.js

@@ -0,0 +1,220 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { UseCasesPluginError } from "./errors.js";
+import { diagnostic, parseYamlToJson, validateBySchemaId } from "./schema/index.js";
+import { DEFAULT_COMPONENT_ID } from "./version.js";
+export function resolveWorkspaceContext(options = {}) {
+    const workspaceRootInput = options.workspaceRoot ?? process.cwd();
+    const workspaceRoot = realpathIfExists(resolve(workspaceRootInput));
+    const pluginRoot = realpathIfExists(options.pluginRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "../../.."));
+    const configPath = join(workspaceRoot, "use-cases.yml");
+    const config = existsSync(configPath) ? readWorkspaceConfig(configPath, workspaceRoot) : null;
+    if (options.component && config?.value.component_id && options.component !== config.value.component_id) {
+        throw new UseCasesPluginError(`Unknown component '${options.component}'. Declared component is '${config.value.component_id}'.`, "component.unknown");
+    }
+    const dataRootValue = options.dataRootOverride ?? config?.value.data_root ?? ".";
+    const dataRoot = realpathIfExists(resolveRelative(workspaceRoot, dataRootValue));
+    const useCasesDir = config?.value.use_cases_dir ?? "use-cases";
+    const useCasesRoot = resolveRelative(dataRoot, useCasesDir);
+    ensureContained(dataRoot, useCasesRoot, "use_cases_dir escapes data_root");
+    return {
+        plugin_root: pluginRoot,
+        workspace_root: workspaceRoot,
+        data_root: dataRoot,
+        use_cases_root: useCasesRoot,
+        component_id: options.component ?? config?.value.component_id ?? DEFAULT_COMPONENT_ID,
+        config_path: existsSync(configPath) ? "use-cases.yml" : null,
+        verifiers: normalizeWorkspaceVerifiers(config?.value.verifiers),
+        release_gate: normalizeReleaseGate(config?.value.release_gate),
+        provenance: {
+            workspace_root: options.workspaceRoot ? "explicit" : "cwd",
+            data_root: options.dataRootOverride ? "override" : config?.value.data_root ? "workspace_config" : "default",
+            use_cases_root: config?.value.use_cases_dir ? "workspace_config" : "default",
+            component_id: options.component ? "option" : config?.value.component_id ? "workspace_config" : "default"
+        },
+        diagnostics: config?.diagnostics ?? []
+    };
+}
+// Canonical diagnostic code for a workspace root that does not exist on disk.
+// Single source of truth so the CLI and MCP transports emit an identical code.
+export const WORKSPACE_NOT_FOUND_CODE = "workspace.not_found";
+// Shared READ-side workspace-existence guard. A non-existent workspace root is a
+// user typo (a mistyped or stale --repo/repo), NOT a valid empty workspace: without
+// this guard the read-only matrix inspection surface (matrix validate/list/status)
+// reports a missing path as a clean, valid, zero-use-case matrix — a silent wrong
+// answer. Both transports' context resolvers call this (the CLI's
+// `resolveContextOrError` and the MCP's `contextFromArgs`) so a bad repo yields the
+// SAME `workspace.not_found` envelope on both — upholding the "envelopes match on
+// both transports" contract, and giving any future workspace tool the guard for
+// free. Returns the canonical diagnostic when the root is missing, else null.
+//
+// An existing-but-empty directory is still legitimate (the "not populated" case).
+// Deliberately NOT wired into the write/scaffold path (`uc init`), which
+// legitimately targets a not-yet-existing root and has its own existence handling.
+// `workspaceRoot` MUST already be resolved to an absolute path by the caller.
+export function workspaceNotFoundDiagnostic(workspaceRoot) {
+    return existsSync(workspaceRoot)
+        ? null
+        : diagnostic(WORKSPACE_NOT_FOUND_CODE, `repo path does not exist: ${workspaceRoot}`);
+}
+function readWorkspaceConfig(configPath, workspaceRoot) {
+    const source = readFileSync(configPath, "utf8");
+    const parsed = parseYamlToJson(source, "use-cases.yml");
+    if (!parsed.ok) {
+        throw new UseCasesPluginError("Unable to parse use-cases.yml.", "workspace_config.parse_error");
+    }
+    const validation = validateBySchemaId("https://use-cases.dev/schemas/v1/workspace-config.schema.json", parsed.value, "use-cases.yml");
+    if (!validation.ok) {
+        throw new UseCasesPluginError("Invalid use-cases.yml.", "workspace_config.schema_error");
+    }
+    if (!isRecord(parsed.value)) {
+        throw new UseCasesPluginError("Invalid use-cases.yml.", "workspace_config.schema_error");
+    }
+    const config = parsed.value;
+    for (const value of [config.data_root, config.use_cases_dir]) {
+        if (value) {
+            ensureRelativeSafe(value);
+        }
+    }
+    return {
+        value: config,
+        diagnostics: validation.diagnostics.map((diagnostic) => ({
+            ...diagnostic,
+            source_path: relative(workspaceRoot, configPath).split(sep).join("/")
+        }))
+    };
+}
+// Split the raw `verifiers` config into { default, verifiers } — the shape the
+// verifier resolver consumes. The schema guarantees entries are objects and
+// `default` is a string, but we re-check defensively (config may be hand-edited).
+function normalizeWorkspaceVerifiers(raw) {
+    if (!isRecord(raw)) {
+        return { verifiers: {} };
+    }
+    const verifiers = {};
+    for (const [id, entry] of Object.entries(raw)) {
+        if (id === "default") {
+            continue;
+        }
+        if (isRecord(entry)) {
+            verifiers[id] = entry;
+        }
+    }
+    return typeof raw.default === "string"
+        ? { default: raw.default, verifiers }
+        : { verifiers };
+}
+// Normalize the optional `release_gate` config into a clean policy, or undefined
+// when nothing meaningful is set. The schema already validates shape; we re-read
+// defensively (config may be hand-edited) and drop an empty/all-falsy object so
+// downstream sees `undefined` (== no requirement, behaviour unchanged).
+function normalizeReleaseGate(raw) {
+    if (!isRecord(raw)) {
+        return undefined;
+    }
+    const gate = {};
+    if (raw.required_authority === "ci") {
+        gate.required_authority = "ci";
+    }
+    if (raw.require_protected_ref === true) {
+        gate.require_protected_ref = true;
+    }
+    return gate.required_authority !== undefined || gate.require_protected_ref !== undefined
+        ? gate
+        : undefined;
+}
+function resolveRelative(root, value) {
+    return isAbsolute(value) ? resolve(value) : resolve(root, value);
+}
+function realpathIfExists(path) {
+    return existsSync(path) ? realpathSync(path) : path;
+}
+function ensureRelativeSafe(value) {
+    if (isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
+        throw new UseCasesPluginError(`Unsafe relative path '${value}'.`, "path.escape");
+    }
+}
+// The canonical id pattern, mirroring schemas/v1/common.schema.json $defs.id.
+// SECURITY: this is the single guard that keeps a user-supplied id (showcase run
+// id, plan item id, evidence id, ...) from becoming a path-traversal segment.
+// Because it forbids '/', '\\', '..', leading separators, and absolute paths, an
+// id that passes this check is always a single safe path segment. The drift test
+// in test/roots/idValidation.test.ts asserts this source equals the schema's.
+export const CANONICAL_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)*$/;
+/** True when `value` is a string matching the canonical id pattern. */
+export function isValidId(value) {
+    return typeof value === "string" && CANONICAL_ID_PATTERN.test(value);
+}
+/**
+ * Throw a stable `path.invalid_id` error (mapped to public `UCM_INVALID_ID`)
+ * when `value` is not a canonical id. Use this at every boundary where a
+ * user-supplied id becomes a filesystem path segment or a ledger lookup key,
+ * BEFORE the id is joined into a path, so traversal can never reach the disk.
+ */
+export function assertValidId(value, paramName) {
+    if (!isValidId(value)) {
+        throw new UseCasesPluginError(`Invalid ${paramName} '${String(value)}': must be a canonical id (lowercase, no path separators, no '..').`, "path.invalid_id");
+    }
+}
+function ensureContained(root, child, message) {
+    const relativePath = relative(root, child);
+    if (relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath))) {
+        return;
+    }
+    throw new UseCasesPluginError(message, "path.escape");
+}
+// Resolve the deepest existing ancestor of `target` to its realpath, then recombine
+// the not-yet-existing suffix. This lets a containment check see THROUGH a symlinked
+// parent directory (or a symlinked leaf) without requiring the leaf itself to exist,
+// so a write target whose parent escapes via a symlink is still caught. A realpath
+// failure (e.g. EACCES on an intermediate dir) returns the input unchanged; callers
+// compare against a realpath'd root, so an unresolved escape still fails containment.
+function realpathOfExistingPrefix(target) {
+    try {
+        if (existsSync(target)) {
+            return realpathSync(target);
+        }
+    }
+    catch {
+        return target;
+    }
+    const parent = dirname(target);
+    if (parent === target) {
+        return target;
+    }
+    return join(realpathOfExistingPrefix(parent), basename(target));
+}
+/**
+ * True when `target` stays inside `root` after resolving symlinks. Both sides are
+ * realpath-resolved (root, and the existing prefix of target) so the check is
+ * symlink-safe AND immune to symlinked-tmpdir aliasing (e.g. macOS /var -> /private/var):
+ * a lexical-only compare would wrongly reject an in-workspace absolute path whose root
+ * was realpath'd to a different prefix. Resolving the target only stats the path — it
+ * never reads file contents — so an escaping path is rejected before it can be opened.
+ */
+export function isPathContained(root, target) {
+    const realRoot = realpathIfExists(root);
+    const realTarget = realpathOfExistingPrefix(resolve(target));
+    const realRelative = relative(realRoot, realTarget);
+    return realRelative === "" || (!realRelative.startsWith("..") && !isAbsolute(realRelative));
+}
+/**
+ * SECURITY: bound a user-supplied file path to `root`, symlink-safe. Returns the
+ * resolved absolute path, or throws a stable `path.escape` (public UCM_PATH_ESCAPE)
+ * UseCasesPluginError when the path — after resolving symlinks on its existing
+ * prefix — escapes `root`. Use at every boundary where an attacker-
+ * controlled path (`--plan-file`, a host projection target, ...) becomes a
+ * filesystem read or write, BEFORE the path is opened.
+ */
+export function resolveContainedPath(root, candidate, message = "Path escapes the workspace boundary.") {
+    const resolved = isAbsolute(candidate) ? resolve(candidate) : resolve(root, candidate);
+    if (!isPathContained(root, resolved)) {
+        throw new UseCasesPluginError(message, "path.escape");
+    }
+    return resolved;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=roots.js.map

package/packages/core/dist/roots.js.map

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

package/packages/core/dist/schema/cliResult.d.ts

@@ -0,0 +1,34 @@
+import type { Diagnostic } from "./diagnostic.js";
+export type CliContext = {
+    workspace_root: string;
+    data_root: string;
+    component_id: string;
+    workspace_snapshot: {
+        repository_id: string;
+        vcs: "git" | "none" | "unknown";
+        head_revision: string;
+        dirty: boolean;
+        working_tree_digest: string;
+        component_id: string;
+        captured_at: string;
+    };
+};
+export type CliResult<T> = {
+    schema_version: 1;
+    protocol_version: 1;
+    command: string;
+    ok: boolean;
+    complete: boolean;
+    data: T;
+    diagnostics: Diagnostic[];
+    context: CliContext;
+};
+export declare function createCliResult<T>(command: string, data: T, options?: {
+    ok?: boolean;
+    complete?: boolean;
+    diagnostics?: Diagnostic[];
+    workspaceRoot?: string;
+    dataRoot?: string;
+    componentId?: string;
+}): CliResult<T>;
+//# sourceMappingURL=cliResult.d.ts.map

package/packages/core/dist/schema/cliResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliResult.d.ts","sourceRoot":"","sources":["../../src/schema/cliResult.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,GAAG,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;QAChC,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,OAAO,CAAC;QACf,mBAAmB,EAAE,MAAM,CAAC;QAC5B,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,cAAc,EAAE,CAAC,CAAC;IAClB,gBAAgB,EAAE,CAAC,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC;IACR,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,EACP,OAAO,GAAE;IACP,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,SAAS,CAAC,CAAC,CAAC,CAgCd"}

package/packages/core/dist/schema/cliResult.js

@@ -0,0 +1,35 @@
+import { DEFAULT_COMPONENT_ID } from "../version.js";
+export function createCliResult(command, data, options = {}) {
+    const workspaceRoot = options.workspaceRoot ?? process.cwd();
+    const dataRoot = options.dataRoot ?? workspaceRoot;
+    const componentId = options.componentId ?? DEFAULT_COMPONENT_ID;
+    const diagnostics = options.diagnostics ?? [];
+    // An error-severity diagnostic always means the command did not succeed, so
+    // the envelope's ok must be false regardless of the caller-provided value.
+    const hasError = diagnostics.some((item) => item.severity === "error");
+    const ok = hasError ? false : (options.ok ?? true);
+    return {
+        schema_version: 1,
+        protocol_version: 1,
+        command,
+        ok,
+        complete: options.complete ?? true,
+        data,
+        diagnostics,
+        context: {
+            workspace_root: workspaceRoot,
+            data_root: dataRoot,
+            component_id: componentId,
+            workspace_snapshot: {
+                repository_id: "unknown",
+                vcs: "unknown",
+                head_revision: "unknown",
+                dirty: false,
+                working_tree_digest: "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+                component_id: componentId,
+                captured_at: new Date(0).toISOString()
+            }
+        }
+    };
+}
+//# sourceMappingURL=cliResult.js.map

package/packages/core/dist/schema/cliResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliResult.js","sourceRoot":"","sources":["../../src/schema/cliResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA6BrD,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,IAAO,EACP,UAOI,EAAE;IAEN,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,aAAa,CAAC;IACnD,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAChE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;IAC9C,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IACnD,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,gBAAgB,EAAE,CAAC;QACnB,OAAO;QACP,EAAE;QACF,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,IAAI;QACJ,WAAW;QACX,OAAO,EAAE;YACP,cAAc,EAAE,aAAa;YAC7B,SAAS,EAAE,QAAQ;YACnB,YAAY,EAAE,WAAW;YACzB,kBAAkB,EAAE;gBAClB,aAAa,EAAE,SAAS;gBACxB,GAAG,EAAE,SAAS;gBACd,aAAa,EAAE,SAAS;gBACxB,KAAK,EAAE,KAAK;gBACZ,mBAAmB,EAAE,yEAAyE;gBAC9F,YAAY,EAAE,WAAW;gBACzB,WAAW,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;aACvC;SACF;KACF,CAAC;AACJ,CAAC"}