@adammcarter/use-cases 0.1.0

package/packages/core/dist/useCases/mutateUseCaseMatrix.js

@@ -0,0 +1,198 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, relative, sep } from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { computeSemanticHash, diagnostic, validateBySchemaId } from "../schema/index.js";
+import { loadUseCaseMatrix } from "./loadUseCaseMatrix.js";
+const USE_CASE_FILE_SCHEMA_ID = "https://use-cases.dev/schemas/v1/use-case-file.schema.json";
+const RECORDED_AT = "1970-01-01T00:00:00.000Z";
+export function mutateUseCaseMatrix(options) {
+    const matrix = loadUseCaseMatrix({ context: options.context });
+    if (!matrix.complete) {
+        return blocked(options, "matrix.mutation_incomplete_matrix", "Use cases must be complete before mutation.");
+    }
+    if (options.operation === "upsert") {
+        return upsertUseCase(options);
+    }
+    return removeUseCase(options);
+}
+function upsertUseCase(options) {
+    if (!options.targetFile || !options.useCase) {
+        return blocked(options, "matrix.mutation_invalid_arguments", "Missing targetFile or useCase.");
+    }
+    const id = typeof options.useCase.id === "string" ? options.useCase.id : null;
+    if (!id) {
+        return blocked(options, "matrix.mutation_missing_use_case_id", "Use case JSON must include an id.");
+    }
+    const target = resolveTargetFile(options.context, options.targetFile);
+    if ("diagnostic" in target) {
+        return blocked(options, target.diagnostic.code, target.diagnostic.message, id);
+    }
+    const parsed = readUseCaseFile(target.fullPath, target.sourcePath);
+    if ("diagnostic" in parsed) {
+        return blocked(options, parsed.diagnostic.code, parsed.diagnostic.message, id, target.sourcePath);
+    }
+    const existingIndex = parsed.document.use_cases.findIndex((item) => item.id === id);
+    const existing = existingIndex >= 0 ? parsed.document.use_cases[existingIndex] : null;
+    const beforeHash = existing ? computeSemanticHash(existing) : null;
+    if (existing && options.expectedSemanticHash && options.expectedSemanticHash !== beforeHash) {
+        return blocked(options, "matrix.mutation_hash_mismatch", "Existing use-case hash did not match expected hash.", id, target.sourcePath, beforeHash);
+    }
+    const nextUseCase = options.useCase;
+    if (existingIndex >= 0) {
+        parsed.document.use_cases[existingIndex] = nextUseCase;
+    }
+    else {
+        parsed.document.use_cases.push(nextUseCase);
+    }
+    const validation = validateBySchemaId(USE_CASE_FILE_SCHEMA_ID, parsed.document, target.sourcePath);
+    if (!validation.ok) {
+        return {
+            schema_version: 1,
+            operation: "upsert",
+            status: "blocked",
+            use_case_id: id,
+            file_path: target.sourcePath,
+            before_hash: beforeHash,
+            after_hash: null,
+            diagnostics: validation.diagnostics
+        };
+    }
+    writeUseCaseFile(target.fullPath, parsed.document);
+    return {
+        schema_version: 1,
+        operation: "upsert",
+        status: existing ? "updated" : "created",
+        use_case_id: id,
+        file_path: target.sourcePath,
+        before_hash: beforeHash,
+        after_hash: computeSemanticHash(nextUseCase),
+        diagnostics: []
+    };
+}
+function removeUseCase(options) {
+    if (!options.useCaseId || !options.reason) {
+        return blocked(options, "matrix.mutation_invalid_arguments", "Missing useCaseId or reason.");
+    }
+    const matrix = loadUseCaseMatrix({ context: options.context });
+    const resolved = matrix.resolveUseCase(options.useCaseId);
+    if (resolved.kind !== "resolved") {
+        return blocked(options, "matrix.mutation_unresolved_use_case", `Use case '${options.useCaseId}' is ${resolved.kind}.`, options.useCaseId);
+    }
+    const sourcePath = resolved.useCase.source.path;
+    const fullPath = join(options.context.data_root, sourcePath.split("/").join(sep));
+    const parsed = readUseCaseFile(fullPath, sourcePath);
+    if ("diagnostic" in parsed) {
+        return blocked(options, parsed.diagnostic.code, parsed.diagnostic.message, options.useCaseId, sourcePath);
+    }
+    const existingIndex = parsed.document.use_cases.findIndex((item) => item.id === options.useCaseId);
+    if (existingIndex < 0) {
+        return blocked(options, "matrix.mutation_unresolved_use_case", `Use case '${options.useCaseId}' was not found in its source file.`, options.useCaseId, sourcePath);
+    }
+    const existing = parsed.document.use_cases[existingIndex];
+    const beforeHash = computeSemanticHash(existing);
+    if (options.expectedSemanticHash && options.expectedSemanticHash !== beforeHash) {
+        return blocked(options, "matrix.mutation_hash_mismatch", "Existing use-case hash did not match expected hash.", options.useCaseId, sourcePath, beforeHash);
+    }
+    const next = {
+        ...existing,
+        lifecycle: "removed",
+        extensions: {
+            ...asRecord(existing.extensions),
+            "use-cases/removal": {
+                ...asRecord(asRecord(existing.extensions)["use-cases/removal"]),
+                reason: options.reason,
+                actor: options.actor ?? "agent",
+                recorded_at: RECORDED_AT
+            }
+        }
+    };
+    parsed.document.use_cases[existingIndex] = next;
+    const validation = validateBySchemaId(USE_CASE_FILE_SCHEMA_ID, parsed.document, sourcePath);
+    if (!validation.ok) {
+        return {
+            schema_version: 1,
+            operation: "remove",
+            status: "blocked",
+            use_case_id: options.useCaseId,
+            file_path: sourcePath,
+            before_hash: beforeHash,
+            after_hash: null,
+            diagnostics: validation.diagnostics
+        };
+    }
+    writeUseCaseFile(fullPath, parsed.document);
+    return {
+        schema_version: 1,
+        operation: "remove",
+        status: "removed",
+        use_case_id: options.useCaseId,
+        file_path: sourcePath,
+        before_hash: beforeHash,
+        after_hash: computeSemanticHash(next),
+        diagnostics: []
+    };
+}
+function resolveTargetFile(context, requestedPath) {
+    const normalized = requestedPath.replaceAll("\\", "/");
+    if (isAbsolute(normalized) || normalized.split("/").includes("..")) {
+        return { diagnostic: diagnostic("matrix.mutation_path_escape", "Target file must stay under use-cases.", requestedPath) };
+    }
+    if (![".yml", ".yaml"].includes(extname(normalized))) {
+        return { diagnostic: diagnostic("matrix.mutation_invalid_file", "Target file must be .yml or .yaml.", requestedPath) };
+    }
+    const stripped = normalized.startsWith("use-cases/") ? normalized.slice("use-cases/".length) : normalized;
+    const fullPath = join(context.use_cases_root, stripped);
+    const rel = relative(context.use_cases_root, fullPath);
+    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+        return { diagnostic: diagnostic("matrix.mutation_path_escape", "Target file must stay under use-cases.", requestedPath) };
+    }
+    return {
+        fullPath,
+        sourcePath: relative(context.data_root, fullPath).split(sep).join("/")
+    };
+}
+function readUseCaseFile(fullPath, sourcePath) {
+    if (!existsSync(fullPath)) {
+        return { diagnostic: diagnostic("matrix.mutation_file_missing", "Target use-case file does not exist.", sourcePath) };
+    }
+    const source = readFileSync(fullPath, "utf8");
+    const parsed = parseDocument(source, {
+        merge: false,
+        prettyErrors: false,
+        schema: "core",
+        uniqueKeys: true
+    });
+    const problems = [...parsed.errors, ...parsed.warnings];
+    if (problems.length > 0) {
+        return {
+            diagnostic: diagnostic("matrix.mutation_parse_error", problems[0]?.message ?? "Could not parse target YAML.", sourcePath)
+        };
+    }
+    const value = parsed.toJSON();
+    if (!value || !Array.isArray(value.use_cases)) {
+        return { diagnostic: diagnostic("matrix.mutation_invalid_file", "Target file is not a use-case file.", sourcePath) };
+    }
+    return { document: value };
+}
+function writeUseCaseFile(fullPath, document) {
+    mkdirSync(dirname(fullPath), { recursive: true });
+    const tempPath = `${fullPath}.tmp-${process.pid}`;
+    writeFileSync(tempPath, stringify(document, { lineWidth: 0 }));
+    renameSync(tempPath, fullPath);
+}
+function blocked(options, code, message, useCaseId = options.useCaseId ?? null, filePath = null, beforeHash = null) {
+    return {
+        schema_version: 1,
+        operation: options.operation,
+        status: "blocked",
+        use_case_id: useCaseId,
+        file_path: filePath,
+        before_hash: beforeHash,
+        after_hash: null,
+        diagnostics: [diagnostic(code, message, filePath, useCaseId)]
+    };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+//# sourceMappingURL=mutateUseCaseMatrix.js.map

package/packages/core/dist/useCases/mutateUseCaseMatrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutateUseCaseMatrix.js","sourceRoot":"","sources":["../../src/useCases/mutateUseCaseMatrix.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,kBAAkB,EAAmB,MAAM,oBAAoB,CAAC;AAC1G,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,MAAM,uBAAuB,GAAG,4DAA4D,CAAC;AAC7F,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAkC/C,MAAM,UAAU,mBAAmB,CAAC,OAA+B;IACjE,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC,OAAO,EAAE,mCAAmC,EAAE,6CAA6C,CAAC,CAAC;IAC9G,CAAC;IAED,IAAI,OAAO,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACnC,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,aAAa,CAAC,OAA+B;IACpD,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,OAAO,CAAC,OAAO,EAAE,mCAAmC,EAAE,gCAAgC,CAAC,CAAC;IACjG,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9E,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,OAAO,OAAO,CAAC,OAAO,EAAE,qCAAqC,EAAE,mCAAmC,CAAC,CAAC;IACtG,CAAC;IAED,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACtE,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACnE,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACpG,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,MAAM,QAAQ,GAAG,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtF,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,IAAI,QAAQ,IAAI,OAAO,CAAC,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;QAC5F,OAAO,OAAO,CAAC,OAAO,EAAE,+BAA+B,EAAE,qDAAqD,EAAE,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACrJ,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,OAAoB,CAAC;IACjD,IAAI,aAAa,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,WAAW,CAAC;IACzD,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IACD,MAAM,UAAU,GAAG,kBAAkB,CAAC,uBAAuB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IACnG,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO;YACL,cAAc,EAAE,CAAC;YACjB,SAAS,EAAE,QAAQ;YACnB,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,EAAE;YACf,SAAS,EAAE,MAAM,CAAC,UAAU;YAC5B,WAAW,EAAE,UAAU;YACvB,UAAU,EAAE,IAAI;YAChB,WAAW,EAAE,UAAU,CAAC,WAAW;SACpC,CAAC;IACJ,CAAC;IAED,gBAAgB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnD,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,SAAS,EAAE,QAAQ;QACnB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACxC,WAAW,EAAE,EAAE;QACf,SAAS,EAAE,MAAM,CAAC,UAAU;QAC5B,WAAW,EAAE,UAAU;QACvB,UAAU,EAAE,mBAAmB,CAAC,WAAW,CAAC;QAC5C,WAAW,EAAE,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,OAA+B;IACpD,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC1C,OAAO,OAAO,CAAC,OAAO,EAAE,mCAAmC,EAAE,8BAA8B,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,OAAO,EAAE,qCAAqC,EAAE,aAAa,OAAO,CAAC,SAAS,QAAQ,QAAQ,CAAC,IAAI,GAAG,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5I,CAAC;IAED,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACrD,IAAI,YAAY,IAAI,MAAM,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5G,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACnG,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,OAAO,EAAE,qCAAqC,EAAE,aAAa,OAAO,CAAC,SAAS,qCAAqC,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACrK,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,OAAO,CAAC,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,KAAK,UAAU,EAAE,CAAC;QAChF,OAAO,OAAO,CAAC,OAAO,EAAE,+BAA+B,EAAE,qDAAqD,EAAE,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC7J,CAAC;IAED,MAAM,IAAI,GAAG;QACX,GAAG,QAAQ;QACX,SAAS,EAAE,SAAkB;QAC7B,UAAU,EAAE;YACV,GAAG,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC;YAChC,mBAAmB,EAAE;gBACnB,GAAG,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,mBAAmB,CAAC,CAAC;gBAC/D,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO;gBAC/B,WAAW,EAAE,WAAW;aACzB;SACF;KACF,CAAC;IACF,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IAChD,MAAM,UAAU,GAAG,kBAAkB,CAAC,uBAAuB,EAAE,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC5F,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,OAAO;YACL,cAAc,EAAE,CAAC;YACjB,SAAS,EAAE,QAAQ;YACnB,MAAM,EAAE,SAAS;YACjB,WAAW,EAAE,OAAO,CAAC,SAAS;YAC9B,SAAS,EAAE,UAAU;YACrB,WAAW,EAAE,UAAU;YACvB,UAAU,EAAE,IAAI;YAChB,WAAW,EAAE,UAAU,CAAC,WAAW;SACpC,CAAC;IACJ,CAAC;IAED,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,SAAS,EAAE,QAAQ;QACnB,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,OAAO,CAAC,SAAS;QAC9B,SAAS,EAAE,UAAU;QACrB,WAAW,EAAE,UAAU;QACvB,UAAU,EAAE,mBAAmB,CAAC,IAAI,CAAC;QACrC,WAAW,EAAE,EAAE;KAChB,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAiC,EAAE,aAAqB;IAGjF,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvD,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,6BAA6B,EAAE,wCAAwC,EAAE,aAAa,CAAC,EAAE,CAAC;IAC5H,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,8BAA8B,EAAE,oCAAoC,EAAE,aAAa,CAAC,EAAE,CAAC;IACzH,CAAC;IACD,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IAC1G,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,6BAA6B,EAAE,wCAAwC,EAAE,aAAa,CAAC,EAAE,CAAC;IAC5H,CAAC;IACD,OAAO;QACL,QAAQ;QACR,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;KACvE,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB,EAAE,UAAkB;IAG3D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,8BAA8B,EAAE,sCAAsC,EAAE,UAAU,CAAC,EAAE,CAAC;IACxH,CAAC;IACD,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE;QACnC,KAAK,EAAE,KAAK;QACZ,YAAY,EAAE,KAAK;QACnB,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,UAAU,EAAE,UAAU,CAAC,6BAA6B,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,8BAA8B,EAAE,UAAU,CAAC;SAC1H,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAyB,CAAC;IACrD,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,8BAA8B,EAAE,qCAAqC,EAAE,UAAU,CAAC,EAAE,CAAC;IACvH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB,EAAE,QAA6B;IACvE,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,GAAG,QAAQ,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IAClD,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,OAAO,CACd,OAA+B,EAC/B,IAAY,EACZ,OAAe,EACf,YAA2B,OAAO,CAAC,SAAS,IAAI,IAAI,EACpD,WAA0B,IAAI,EAC9B,aAA4B,IAAI;IAEhC,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,SAAS;QACtB,SAAS,EAAE,QAAQ;QACnB,WAAW,EAAE,UAAU;QACvB,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC;AAGD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;AACtH,CAAC"}

package/packages/core/dist/useCases/query.d.ts

@@ -0,0 +1,12 @@
+import type { HostSurface, LoadedUseCase, MatrixSnapshot, UseCaseV1 } from "./types.js";
+export type UseCaseQuery = {
+    valueTiers?: readonly UseCaseV1["value_tier"][];
+    journeyRoles?: readonly UseCaseV1["journey_role"][];
+    lifecycles?: readonly UseCaseV1["lifecycle"][];
+    hostSurfaces?: readonly HostSurface[];
+    tagsAny?: readonly string[];
+    tagsAll?: readonly string[];
+    changedPaths?: readonly string[];
+};
+export declare function queryUseCases(snapshot: MatrixSnapshot, query?: UseCaseQuery): LoadedUseCase[];
+//# sourceMappingURL=query.d.ts.map

package/packages/core/dist/useCases/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/useCases/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExF,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,CAAC,EAAE,SAAS,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;IAChD,YAAY,CAAC,EAAE,SAAS,SAAS,CAAC,cAAc,CAAC,EAAE,CAAC;IACpD,UAAU,CAAC,EAAE,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;IAC/C,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAGF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,KAAK,GAAE,YAAiB,GAAG,aAAa,EAAE,CASjG"}

package/packages/core/dist/useCases/query.js

@@ -0,0 +1,47 @@
+//: @use-case: matrix.product.coverage_by_value_and_journey
+export function queryUseCases(snapshot, query = {}) {
+    return snapshot.addressableUseCases
+        .filter((item) => matchesValueTier(item, query))
+        .filter((item) => matchesJourneyRole(item, query))
+        .filter((item) => matchesLifecycle(item, query))
+        .filter((item) => matchesHostSurface(item, query))
+        .filter((item) => matchesTags(item, query))
+        .filter((item) => matchesChangedPaths(item, query))
+        .sort((left, right) => left.value.id.localeCompare(right.value.id));
+}
+//: @use-case: end matrix.product.coverage_by_value_and_journey
+function matchesValueTier(item, query) {
+    return !query.valueTiers?.length || query.valueTiers.includes(item.value.value_tier);
+}
+function matchesJourneyRole(item, query) {
+    return !query.journeyRoles?.length || query.journeyRoles.includes(item.value.journey_role);
+}
+function matchesLifecycle(item, query) {
+    return !query.lifecycles?.length || query.lifecycles.includes(item.value.lifecycle);
+}
+function matchesHostSurface(item, query) {
+    if (!query.hostSurfaces?.length) {
+        return true;
+    }
+    if (!item.value.host_applicability?.length) {
+        return true;
+    }
+    return item.value.host_applicability.some((host) => host.supported && query.hostSurfaces?.includes(host.host_surface));
+}
+function matchesTags(item, query) {
+    const tags = new Set(item.value.tags ?? []);
+    const anyOk = !query.tagsAny?.length || query.tagsAny.some((tag) => tags.has(tag));
+    const allOk = !query.tagsAll?.length || query.tagsAll.every((tag) => tags.has(tag));
+    return anyOk && allOk;
+}
+function matchesChangedPaths(item, query) {
+    if (!query.changedPaths?.length) {
+        return true;
+    }
+    const changed = new Set(query.changedPaths.map(normalizePath));
+    return (item.value.source_refs ?? []).some((sourceRef) => sourceRef.kind === "file" && changed.has(normalizePath(sourceRef.path)));
+}
+function normalizePath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+//# sourceMappingURL=query.js.map

package/packages/core/dist/useCases/query.js.map

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

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

@@ -0,0 +1,149 @@
+import type { Diagnostic } from "../schema/index.js";
+import type { ResolvedWorkspaceContext } from "../roots.js";
+export type MatrixIntegrityState = "clean" | "partial" | "unusable";
+export type MatrixFileStatus = "loaded" | "parse_error" | "schema_error" | "unknown_version" | "duplicate_id" | "broken_reference" | "ambiguous_reference" | "path_escape" | "symlink_rejected" | "io_error" | "resource_limit_exceeded";
+export type HostSurface = "claude.cli" | "claude.desktop" | "codex.cli" | "copilot.cli" | "copilot.github" | "opencode.cli" | "unknown";
+export type UseCaseV1 = {
+    id: string;
+    title: string;
+    lifecycle: "planned" | "active" | "deprecated" | "removed";
+    value_tier: "critical" | "core" | "supporting" | "long_tail";
+    journey_role: "golden" | "alternate" | "edge" | "negative" | "failure";
+    usage_frequency: "common" | "occasional" | "rare";
+    tags?: string[];
+    source_refs?: Array<{
+        kind: "file";
+        path: string;
+    }>;
+    related_use_cases?: string[];
+    scenarios?: Array<{
+        id: string;
+        kind: string;
+    }>;
+    host_applicability?: Array<{
+        host_surface: HostSurface;
+        supported: boolean;
+        notes?: string;
+    }>;
+    [key: string]: unknown;
+};
+export type FeatureV1 = {
+    id: string;
+    name: string;
+    summary: string;
+};
+export type LoadedUseCase = {
+    value: UseCaseV1;
+    feature: FeatureV1;
+    semanticHash: string;
+    source: {
+        path: string;
+        jsonPointer: string;
+        fileByteHash: string;
+    };
+};
+export type MatrixFileResult = {
+    path: string;
+    status: MatrixFileStatus;
+    semantic_hash?: string;
+    file_hash?: string;
+};
+export type AmbiguousIdGroup = {
+    entity_kind: "use_case";
+    id: string;
+    source_paths: string[];
+};
+export type MatrixStructuralCounts = {
+    files_discovered: number;
+    files_loaded: number;
+    files_excluded: number;
+    use_case_candidates: number;
+    use_cases_addressable: number;
+    use_cases_ambiguous: number;
+    use_cases_structurally_clean: number;
+    broken_references: number;
+};
+export type UseCaseResolution = {
+    kind: "resolved";
+    id: string;
+    useCase: LoadedUseCase;
+} | {
+    kind: "missing";
+    id: string;
+} | {
+    kind: "ambiguous";
+    id: string;
+    candidates: LoadedUseCase[];
+};
+export type ScenarioResolution = {
+    kind: "resolved";
+    useCaseId: string;
+    scenarioId: string;
+    useCase: LoadedUseCase;
+} | {
+    kind: "missing";
+    useCaseId: string;
+    scenarioId: string;
+} | {
+    kind: "ambiguous";
+    useCaseId: string;
+    scenarioId: string;
+    candidates: LoadedUseCase[];
+};
+export type MatrixSnapshot = {
+    context: ResolvedWorkspaceContext;
+    complete: boolean;
+    integrity: {
+        state: MatrixIntegrityState;
+        populated: boolean;
+        blockingDiagnosticCount: number;
+    };
+    files: MatrixFileResult[];
+    candidates: LoadedUseCase[];
+    addressableUseCases: LoadedUseCase[];
+    ambiguousUseCaseIds: AmbiguousIdGroup[];
+    diagnostics: Diagnostic[];
+    counts: MatrixStructuralCounts;
+    resolveUseCase(id: string): UseCaseResolution;
+    resolveScenario(useCaseId: string, scenarioId: string): ScenarioResolution;
+};
+export type MatrixValidationResultData = {
+    schema_version: 1;
+    complete: boolean;
+    valid: boolean;
+    integrity: {
+        state: MatrixIntegrityState;
+        populated: boolean;
+        blocking_diagnostic_count: number;
+    };
+    files: Array<{
+        path: string;
+        status: MatrixFileStatus;
+        semantic_hash?: string;
+        file_hash?: string;
+    }>;
+    counts: MatrixStructuralCounts;
+    ambiguous_ids: AmbiguousIdGroup[];
+};
+export type MatrixListResultData = {
+    schema_version: 1;
+    complete: boolean;
+    integrity: MatrixValidationResultData["integrity"];
+    use_cases: Array<{
+        id: string;
+        title: string;
+        feature_id: string;
+        lifecycle: UseCaseV1["lifecycle"];
+        value_tier: UseCaseV1["value_tier"];
+        journey_role: UseCaseV1["journey_role"];
+        source_path: string;
+        semantic_hash: string;
+        host_surfaces: HostSurface[];
+        tags: string[];
+    }>;
+    counts: {
+        returned: number;
+        total_addressable: number;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

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

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

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

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

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

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

package/packages/core/dist/useCases/validateUseCaseFile.d.ts

@@ -0,0 +1,9 @@
+import { type Diagnostic } from "../schema/index.js";
+import type { LoadedUseCase, MatrixFileResult } from "./types.js";
+export type UseCaseFileValidationResult = {
+    file: MatrixFileResult;
+    candidates: LoadedUseCase[];
+    diagnostics: Diagnostic[];
+};
+export declare function validateUseCaseFile(filePath: string, sourcePath: string): UseCaseFileValidationResult;
+//# sourceMappingURL=validateUseCaseFile.d.ts.map

package/packages/core/dist/useCases/validateUseCaseFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateUseCaseFile.d.ts","sourceRoot":"","sources":["../../src/useCases/validateUseCaseFile.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAa,aAAa,EAAE,gBAAgB,EAAa,MAAM,YAAY,CAAC;AAExF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,2BAA2B,CAsF7B"}

package/packages/core/dist/useCases/validateUseCaseFile.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { TextDecoder } from "node:util";
+import { computeSemanticHash, diagnostic, parseYamlToJson, validateBySchemaId } from "../schema/index.js";
+export function validateUseCaseFile(filePath, sourcePath) {
+    let bytes;
+    try {
+        bytes = readFileSync(filePath);
+    }
+    catch (error) {
+        return failedFile("io_error", sourcePath, messageFor(error));
+    }
+    const fileHash = hashBytes(bytes);
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        return failedFile("parse_error", sourcePath, messageFor(error), fileHash);
+    }
+    const parsed = parseYamlToJson(source, sourcePath);
+    if (!parsed.ok) {
+        return {
+            file: { path: sourcePath, status: "parse_error", file_hash: fileHash },
+            candidates: [],
+            diagnostics: parsed.diagnostics.map((diagnostic) => ({
+                ...diagnostic,
+                code: diagnostic.code === "parse_error" ? "parse_error" : diagnostic.code
+            }))
+        };
+    }
+    const versionDiagnostic = versionDispatch(parsed.value, sourcePath);
+    if (versionDiagnostic) {
+        return {
+            file: {
+                path: sourcePath,
+                status: versionDiagnostic.code === "unknown_version" ? "unknown_version" : "schema_error",
+                semantic_hash: computeSemanticHash(parsed.value),
+                file_hash: fileHash
+            },
+            candidates: [],
+            diagnostics: [versionDiagnostic]
+        };
+    }
+    const schemaResult = validateBySchemaId("https://use-cases.dev/schemas/v1/use-case-file.schema.json", parsed.value, sourcePath);
+    if (!schemaResult.ok) {
+        return {
+            file: {
+                path: sourcePath,
+                status: "schema_error",
+                semantic_hash: computeSemanticHash(parsed.value),
+                file_hash: fileHash
+            },
+            candidates: [],
+            diagnostics: schemaResult.diagnostics.map((diagnostic) => ({
+                ...diagnostic,
+                code: diagnostic.code === "schema_version.required" ? "schema_error" : diagnostic.code
+            }))
+        };
+    }
+    const value = parsed.value;
+    return {
+        file: {
+            path: sourcePath,
+            status: "loaded",
+            semantic_hash: computeSemanticHash(parsed.value),
+            file_hash: fileHash
+        },
+        candidates: value.use_cases.map((useCase, index) => ({
+            value: useCase,
+            feature: value.feature,
+            semanticHash: computeSemanticHash(useCase),
+            source: {
+                path: sourcePath,
+                jsonPointer: `/use_cases/${index}`,
+                fileByteHash: fileHash
+            }
+        })),
+        diagnostics: []
+    };
+}
+function versionDispatch(value, sourcePath) {
+    if (!isRecord(value) || !("schema_version" in value) || typeof value.schema_version !== "number") {
+        return diagnostic("schema_error", "Use-case file must declare numeric schema_version: 1.", sourcePath);
+    }
+    if (value.schema_version !== 1) {
+        return diagnostic("unknown_version", `Unsupported use-case schema_version ${value.schema_version}.`, sourcePath);
+    }
+    return null;
+}
+function failedFile(status, sourcePath, message, fileHash) {
+    return {
+        file: { path: sourcePath, status, file_hash: fileHash },
+        candidates: [],
+        diagnostics: [diagnostic(status, message, sourcePath)]
+    };
+}
+function hashBytes(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function messageFor(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=validateUseCaseFile.js.map

package/packages/core/dist/useCases/validateUseCaseFile.js.map

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

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

@@ -0,0 +1,9 @@
+export declare const PRODUCT_NAME = "@adammcarter/use-cases";
+export declare const UCM_VERSION = "0.1.0";
+export declare const DEFAULT_COMPONENT_ID = "use-cases";
+export type VersionInfo = {
+    name: typeof PRODUCT_NAME;
+    version: typeof UCM_VERSION;
+};
+export declare function getVersionInfo(): VersionInfo;
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,2BAA2B,CAAC;AACrD,eAAO,MAAM,WAAW,UAAU,CAAC;AAOnC,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,OAAO,YAAY,CAAC;IAC1B,OAAO,EAAE,OAAO,WAAW,CAAC;CAC7B,CAAC;AAEF,wBAAgB,cAAc,IAAI,WAAW,CAK5C"}

package/packages/core/dist/version.js

@@ -0,0 +1,17 @@
+// The public PRODUCT identity (shown by `--version`, MCP serverInfo, npm package).
+// Renamed to Use Cases for public v1.
+export const PRODUCT_NAME = "@adammcarter/use-cases";
+export const UCM_VERSION = "0.1.0";
+// The DEFAULT workspace component id used when a repo's config does not set one.
+// This is matrix DATA (it appears in this repo's rows, bindings, proofs, and many
+// fixtures), distinct from the product name above. Migrated to the new identity
+// during the dogfood/re-prove phase: the self-matrix is regenerated under this id
+// and re-proven, so no previously valid signed proof is silently carried over.
+export const DEFAULT_COMPONENT_ID = "use-cases";
+export function getVersionInfo() {
+    return {
+        name: PRODUCT_NAME,
+        version: UCM_VERSION
+    };
+}
+//# sourceMappingURL=version.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,sCAAsC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC,iFAAiF;AACjF,kFAAkF;AAClF,gFAAgF;AAChF,kFAAkF;AAClF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAC;AAOhD,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,WAAW;KACrB,CAAC;AACJ,CAAC"}