@habitat-ai/service 0.2.0

package/dist/service/modules/catalog/model/policy/catalog.js

@@ -0,0 +1,607 @@
+import { Validator } from "typebox/schema";
+import { BlueprintDefinitionSchema, CompatibilityIndexSchema, CompatibilityRuleSourceSchema, HabitatInstanceManifestSchema, MAX_CATALOG_ISSUES, PolicyPackManifestSchema, PolicyPackPackageJsonSchema, } from "../dto/catalog.js";
+const MEMBER_PLACEHOLDER = "{member}";
+const GLOB_CHARACTERS = /[*?[\]!]/;
+const blueprintValidator = new Validator({}, BlueprintDefinitionSchema);
+const policyPackManifestValidator = new Validator({}, PolicyPackManifestSchema);
+const policyPackPackageJsonValidator = new Validator({}, PolicyPackPackageJsonSchema);
+const instanceValidator = new Validator({}, HabitatInstanceManifestSchema);
+const compatibilityIndexValidator = new Validator({}, CompatibilityIndexSchema);
+const compatibilityRuleValidator = new Validator({}, CompatibilityRuleSourceSchema);
+/** Validates the selected policy-pack filesystem locators. */
+export function admitPolicyPackSelection(selection, path) {
+    const issues = [];
+    if (!path.isAbsolute(selection.packageJsonPath)) {
+        issues.push(issue("authority-path-invalid", `${selection.name}/package.json`, "Selected policy-pack packageJsonPath must be absolute."));
+    }
+    if (!path.isAbsolute(selection.manifestPath)) {
+        issues.push(issue("authority-path-invalid", `${selection.name}/habitat-pack.json`, "Selected policy-pack manifestPath must be absolute."));
+    }
+    if (path.basename(selection.packageJsonPath) !== "package.json" ||
+        path.resolve(selection.manifestPath) !==
+            path.resolve(path.dirname(selection.packageJsonPath), "habitat-pack.json")) {
+        issues.push(issue("authority-path-invalid", `${selection.name}/habitat-pack.json`, "Selected policy-pack locators must identify sibling package.json and habitat-pack.json files."));
+    }
+    return issues.length > 0 ? { ok: false, issues } : { ok: true, selection };
+}
+/** Admits selected package.json identity through the existing TypeBox validator pattern. */
+export function admitPolicyPackPackageJson(value, expectedName, sourcePath) {
+    const admitted = admit(policyPackPackageJsonValidator, value, sourcePath);
+    if (!admitted.ok)
+        return admitted;
+    return admitted.value.name === expectedName
+        ? admitted
+        : {
+            ok: false,
+            issues: [
+                issue("authority-package-name-mismatch", sourcePath, `Selected package name "${expectedName}" does not equal package.json name "${admitted.value.name}".`),
+            ],
+        };
+}
+/** Admits the closed protocol envelope and refuses future member activation explicitly. */
+export function admitPolicyPackManifest(value, sourcePath) {
+    const admitted = admit(policyPackManifestValidator, value, sourcePath);
+    if (!admitted.ok)
+        return admitted;
+    return admitted.value.blueprints.length === 0
+        ? admitted
+        : {
+            ok: false,
+            issues: [
+                issue("authority-policy-pack-members-unsupported", sourcePath, "Policy-pack blueprint members are not admitted by this service version."),
+            ],
+        };
+}
+/** Admits unknown TOML output as one closed blueprint definition. */
+export function admitBlueprintSource(value, relativePath) {
+    const admitted = admit(blueprintValidator, value, relativePath);
+    return admitted.ok
+        ? { ok: true, source: { definition: admitted.value, relativePath } }
+        : admitted;
+}
+/** Admits unknown TOML output as one closed instance manifest. */
+export function admitInstanceSource(value, relativePath) {
+    const admitted = admit(instanceValidator, value, relativePath);
+    return admitted.ok ? { ok: true, source: { manifest: admitted.value, relativePath } } : admitted;
+}
+/** Admits unknown JSON output as the closed legacy index. */
+export function admitCompatibilityIndex(value, relativePath) {
+    return admit(compatibilityIndexValidator, value, relativePath);
+}
+/** Admits only the inert identity fields required from a legacy rule source. */
+export function admitCompatibilityRule(value, relativePath) {
+    const admitted = admit(compatibilityRuleValidator, value, relativePath);
+    return admitted.ok ? { ok: true, source: { rule: admitted.value, relativePath } } : admitted;
+}
+/** Collects filesystem paths that schema-admitted documents require the service to observe. */
+export function referencedRepositoryPaths(documents, path) {
+    const references = new Set();
+    for (const source of documents.blueprints) {
+        const directory = path.dirname(source.relativePath);
+        for (const rule of source.definition.rules) {
+            const asset = rule.runner.name === "habitat" ? rule.runner.structure : rule.runner.pattern;
+            if (relativePathIssues(asset, source.relativePath, path).length === 0) {
+                references.add(toRepositoryPath(path.join(directory, asset), path));
+            }
+        }
+    }
+    for (const source of documents.manifests) {
+        for (const rootPath of Object.values(source.manifest.roots)) {
+            if (relativePathIssues(rootPath, source.relativePath, path).length === 0) {
+                references.add(toRepositoryPath(rootPath, path));
+            }
+        }
+    }
+    const definitions = new Map(documents.blueprints.map((source) => [blueprintIdentity(source.definition), source]));
+    for (const source of documents.manifests) {
+        const definition = definitions.get(`${source.manifest.blueprint}@${source.manifest.blueprintVersion}`)?.definition;
+        if (!definition)
+            continue;
+        for (const selection of definition.instance.selections) {
+            const root = source.manifest.roots[selection.root];
+            const members = source.manifest.selections[selection.id];
+            if (root === undefined || members === undefined)
+                continue;
+            for (const member of members) {
+                const memberPath = path.join(root, selection.pathTemplate.replace(MEMBER_PLACEHOLDER, member));
+                if (relativePathIssues(toRepositoryPath(memberPath, path), source.relativePath, path)
+                    .length === 0) {
+                    references.add(toRepositoryPath(memberPath, path));
+                }
+            }
+        }
+    }
+    return [...references].sort(textOrder);
+}
+/** Resolves admitted documents and observed paths into the closed public catalog union. */
+export function resolveCatalog(documents, pathFacts, workspaceRoot, workspaceRealRoot, path) {
+    const issues = [];
+    const blueprints = [...documents.blueprints].sort(compareBlueprintSources);
+    const manifests = [...documents.manifests].sort((left, right) => textOrder(left.manifest.id, right.manifest.id));
+    issues.push(...duplicateIssues(blueprints.map((source) => ({
+        identity: blueprintIdentity(source.definition),
+        path: source.relativePath,
+    })), "authority-duplicate-blueprint", "blueprint"));
+    issues.push(...duplicateIssues(manifests.map((source) => ({ identity: source.manifest.id, path: source.relativePath })), "authority-duplicate-instance", "instance"));
+    for (const source of blueprints) {
+        issues.push(...validateBlueprint(source, path));
+    }
+    const compatibility = resolveCompatibility(documents, issues, path);
+    const ruleSources = [
+        ...blueprints.flatMap((source) => source.definition.rules.map((rule) => ({ identity: rule.id, path: source.relativePath }))),
+        ...compatibility.rules.map((rule) => ({ identity: rule.id, path: rule.manifestPath })),
+    ];
+    issues.push(...duplicateIssues(ruleSources, "authority-duplicate-rule", "rule"));
+    const definitions = new Map(blueprints.map((source) => [blueprintIdentity(source.definition), source]));
+    const resolvedInstances = [];
+    for (const source of manifests) {
+        const definitionSource = definitions.get(`${source.manifest.blueprint}@${source.manifest.blueprintVersion}`);
+        if (!definitionSource) {
+            const versions = blueprints
+                .filter((candidate) => candidate.definition.id === source.manifest.blueprint)
+                .map((candidate) => candidate.definition.version);
+            issues.push(issue(versions.length > 0 ? "authority-version-mismatch" : "authority-blueprint-missing", source.relativePath, versions.length > 0
+                ? `Blueprint "${source.manifest.blueprint}" has versions ${versions.join(", ")}, not requested version ${source.manifest.blueprintVersion}.`
+                : `Blueprint "${source.manifest.blueprint}" is not registered.`));
+            continue;
+        }
+        const resolved = resolveInstance(definitionSource, source, pathFacts, workspaceRoot, workspaceRealRoot, path);
+        issues.push(...resolved.issues);
+        if (resolved.instance)
+            resolvedInstances.push(resolved.instance);
+    }
+    for (const source of blueprints) {
+        for (const rule of source.definition.rules) {
+            const assetPath = ruleAssetPath(source, rule, path);
+            issues.push(...pathFactIssues(assetPath, "file", source.relativePath, pathFacts, workspaceRoot, workspaceRealRoot, path));
+        }
+    }
+    if (issues.length > 0)
+        return rejected(issues);
+    const instances = resolvedInstances.sort((left, right) => textOrder(left.id, right.id));
+    const applications = [];
+    for (const instance of instances) {
+        const definitionSource = definitions.get(`${instance.blueprint}@${instance.blueprintVersion}`);
+        if (!definitionSource)
+            continue;
+        for (const rule of definitionSource.definition.rules) {
+            const assetPath = ruleAssetPath(definitionSource, rule, path);
+            const asset = {
+                provenance: {
+                    kind: "local",
+                    authorityRoot: workspaceRoot,
+                    relativePath: definitionSource.relativePath,
+                },
+                relativePath: assetPath,
+                absolutePath: path.resolve(workspaceRoot, assetPath),
+            };
+            const common = {
+                ownerProject: instance.ownerProject,
+                instanceId: instance.id,
+                blueprint: instance.blueprint,
+                blueprintVersion: instance.blueprintVersion,
+                ruleId: rule.id,
+                manifestPath: instance.manifestPath,
+                lane: rule.lane,
+                message: rule.message,
+                remediate: rule.remediate,
+                provenance: asset.provenance,
+            };
+            if (rule.runner.name === "habitat") {
+                applications.push({
+                    ...common,
+                    runner: {
+                        name: "habitat",
+                        mode: "structure",
+                        structure: asset,
+                        rootBindings: definitionSource.definition.instance.roots.map((root) => {
+                            const binding = instance.roots.find((candidate) => candidate.id === root.id);
+                            return binding
+                                ? {
+                                    rootRole: root.id,
+                                    required: root.required,
+                                    kind: root.kind,
+                                    path: binding.path,
+                                }
+                                : { rootRole: root.id, required: root.required, kind: root.kind };
+                        }),
+                    },
+                });
+                continue;
+            }
+            const entries = [];
+            for (const rootRole of rule.runner.acquisition.rootRoles) {
+                const root = instance.roots.find((candidate) => candidate.id === rootRole);
+                if (root) {
+                    entries.push({
+                        source: { kind: "root-role", id: rootRole },
+                        kind: root.kind,
+                        path: root.path,
+                    });
+                }
+            }
+            for (const selectionId of rule.runner.acquisition.selections) {
+                const selection = instance.selections.find((candidate) => candidate.id === selectionId);
+                for (const member of selection?.members ?? []) {
+                    entries.push({
+                        source: { kind: "selection", id: selectionId, member: member.id },
+                        kind: member.kind,
+                        path: member.path,
+                    });
+                }
+            }
+            applications.push({
+                ...common,
+                runner: {
+                    name: "grit",
+                    pattern: asset,
+                    patternName: rule.runner.patternName,
+                    acquisition: { kind: rule.runner.acquisition.kind, entries },
+                },
+            });
+        }
+    }
+    applications.sort((left, right) => textOrder(left.ruleId, right.ruleId) || textOrder(left.instanceId, right.instanceId));
+    return deepFreeze({
+        _tag: "Resolved",
+        catalog: {
+            schemaVersion: 3,
+            policyPack: {
+                name: documents.policyPack.name,
+                version: documents.policyPack.version,
+                protocolVersion: documents.policyPack.protocolVersion,
+                blueprints: [],
+            },
+            blueprints: blueprints.map((source) => ({
+                definition: source.definition,
+                provenance: {
+                    kind: "local",
+                    authorityRoot: workspaceRoot,
+                    relativePath: source.relativePath,
+                },
+            })),
+            instances,
+            applications,
+            compatibility,
+        },
+    });
+}
+/** Constructs a bounded, sorted rejected result for operational failures. */
+export function rejected(issues) {
+    const stable = stableIssues(issues);
+    return {
+        _tag: "Rejected",
+        issues: stable.length > 0
+            ? stable
+            : [issue("authority-resolution-failed", "", "Catalog resolution failed.")],
+    };
+}
+function resolveCompatibility(documents, issues, path) {
+    if (!documents.compatibilityIndex) {
+        return { schemaVersion: 2, ownerRoots: {}, rules: [] };
+    }
+    const ownerRoots = Object.fromEntries(Object.entries(documents.compatibilityIndex.ownerRoots).sort(([left], [right]) => textOrder(left, right)));
+    for (const [owner, root] of Object.entries(ownerRoots)) {
+        issues.push(...relativePathIssues(root, `.habitat/index.json#ownerRoots:${owner}`, path));
+    }
+    const rules = [...documents.compatibilityRules]
+        .sort((left, right) => textOrder(left.rule.id, right.rule.id) || textOrder(left.relativePath, right.relativePath))
+        .map((source) => {
+        if (!Object.hasOwn(ownerRoots, source.rule.ownerProject)) {
+            issues.push(issue("authority-compatibility-invalid", source.relativePath, `Legacy rule ownerProject "${source.rule.ownerProject}" has no owner root.`));
+        }
+        return {
+            id: source.rule.id,
+            ownerProject: source.rule.ownerProject,
+            manifestPath: source.relativePath,
+        };
+    });
+    return { schemaVersion: 2, ownerRoots, rules };
+}
+function validateBlueprint(source, path) {
+    const issues = [];
+    const kind = source.relativePath.split("/")[2];
+    if (kind !== source.definition.id) {
+        issues.push(issue("authority-definition-kind-mismatch", source.relativePath, `Blueprint path kind "${kind ?? ""}" does not equal definition id "${source.definition.id}".`));
+    }
+    issues.push(...sortedUniqueIssues(source.definition.instance.roots.map((root) => root.id), source.relativePath, "root roles"), ...sortedUniqueIssues(source.definition.instance.selections.map((selection) => selection.id), source.relativePath, "selection axes"), ...sortedUniqueIssues(source.definition.rules.map((rule) => rule.id), source.relativePath, "rule ids"));
+    const roots = new Map(source.definition.instance.roots.map((root) => [root.id, root]));
+    const anchor = roots.get(source.definition.instance.anchorRoot);
+    if (!anchor || !anchor.required || anchor.kind !== "directory") {
+        issues.push(issue("authority-definition-invalid", source.relativePath, `anchorRoot "${source.definition.instance.anchorRoot}" must name a required directory root role.`));
+    }
+    for (const selection of source.definition.instance.selections) {
+        const sourcePath = `${source.relativePath}#selection:${selection.id}`;
+        if (roots.get(selection.root)?.kind !== "directory") {
+            issues.push(issue("authority-definition-invalid", sourcePath, `Selection "${selection.id}" must name a known directory root role.`));
+        }
+        try {
+            new RegExp(selection.memberPattern);
+        }
+        catch (error) {
+            issues.push(issue("authority-definition-invalid", sourcePath, `Invalid memberPattern: ${renderCause(error)}`));
+        }
+        issues.push(...pathTemplateIssues(selection.pathTemplate, sourcePath, path));
+    }
+    const selectionIds = new Set(source.definition.instance.selections.map((selection) => selection.id));
+    for (const rule of source.definition.rules) {
+        const sourcePath = `${source.relativePath}#rule:${rule.id}`;
+        const asset = rule.runner.name === "habitat" ? rule.runner.structure : rule.runner.pattern;
+        issues.push(...relativePathIssues(asset, sourcePath, path));
+        if (rule.runner.name === "habitat")
+            continue;
+        issues.push(...sortedUniqueIssues(rule.runner.acquisition.rootRoles, sourcePath, "acquisition rootRoles"), ...sortedUniqueIssues(rule.runner.acquisition.selections, sourcePath, "acquisition selections"));
+        if (rule.runner.acquisition.rootRoles.length === 0 &&
+            rule.runner.acquisition.selections.length === 0) {
+            issues.push(issue("authority-rule-invalid", sourcePath, `Grit rule "${rule.id}" requires an acquisition source.`));
+        }
+        for (const rootRole of rule.runner.acquisition.rootRoles) {
+            if (!roots.has(rootRole)) {
+                issues.push(issue("authority-rule-invalid", sourcePath, `Unknown acquisition root role "${rootRole}".`));
+            }
+        }
+        for (const selectionId of rule.runner.acquisition.selections) {
+            const selection = source.definition.instance.selections.find((item) => item.id === selectionId);
+            if (!selectionIds.has(selectionId)) {
+                issues.push(issue("authority-rule-invalid", sourcePath, `Unknown acquisition selection "${selectionId}".`));
+            }
+            else if (selection?.kind !== "file") {
+                issues.push(issue("authority-rule-invalid", sourcePath, `Acquisition selection "${selectionId}" must resolve files.`));
+            }
+        }
+    }
+    return issues;
+}
+function resolveInstance(definitionSource, source, pathFacts, workspaceRoot, workspaceRealRoot, path) {
+    const issues = [];
+    const definition = definitionSource.definition;
+    const roots = new Map(definition.instance.roots.map((root) => [root.id, root]));
+    const selections = new Map(definition.instance.selections.map((selection) => [selection.id, selection]));
+    for (const rootId of Object.keys(source.manifest.roots).sort(textOrder)) {
+        if (!roots.has(rootId)) {
+            issues.push(issue("authority-manifest-invalid", source.relativePath, `Unknown root role "${rootId}".`));
+        }
+    }
+    for (const root of definition.instance.roots) {
+        if (root.required && !Object.hasOwn(source.manifest.roots, root.id)) {
+            issues.push(issue("authority-manifest-invalid", source.relativePath, `Missing required root role "${root.id}".`));
+        }
+    }
+    for (const selectionId of Object.keys(source.manifest.selections).sort(textOrder)) {
+        if (!selections.has(selectionId)) {
+            issues.push(issue("authority-manifest-invalid", source.relativePath, `Unknown selection axis "${selectionId}".`));
+        }
+    }
+    const anchorPath = source.manifest.roots[definition.instance.anchorRoot];
+    const manifestDirectory = toRepositoryPath(path.dirname(source.relativePath), path);
+    if (anchorPath !== undefined && toRepositoryPath(anchorPath, path) !== manifestDirectory) {
+        issues.push(issue("authority-anchor-mismatch", source.relativePath, `dirname(habitat.toml) is "${manifestDirectory}", but anchor root binds "${anchorPath}".`));
+    }
+    const resolvedRoots = [];
+    for (const root of definition.instance.roots) {
+        const boundPath = source.manifest.roots[root.id];
+        if (boundPath === undefined)
+            continue;
+        issues.push(...relativePathIssues(boundPath, source.relativePath, path));
+        issues.push(...pathFactIssues(boundPath, root.kind, source.relativePath, pathFacts, workspaceRoot, workspaceRealRoot, path));
+        resolvedRoots.push({ ...root, path: toRepositoryPath(boundPath, path) });
+    }
+    const resolvedSelections = [];
+    for (const selection of definition.instance.selections) {
+        const members = source.manifest.selections[selection.id];
+        if (members === undefined)
+            continue;
+        issues.push(...sortedUniqueIssues(members, source.relativePath, `members of "${selection.id}"`));
+        const rootPath = source.manifest.roots[selection.root];
+        if (rootPath === undefined) {
+            issues.push(issue("authority-manifest-invalid", source.relativePath, `Selection "${selection.id}" requires bound root role "${selection.root}".`));
+            continue;
+        }
+        let expression;
+        try {
+            expression = new RegExp(selection.memberPattern);
+        }
+        catch {
+            continue;
+        }
+        const resolvedMembers = [];
+        for (const member of members) {
+            if (!expression.test(member)) {
+                issues.push(issue("authority-manifest-invalid", source.relativePath, `Selection member "${member}" does not match ${selection.memberPattern}.`));
+                continue;
+            }
+            const memberPath = toRepositoryPath(path.join(rootPath, selection.pathTemplate.replace(MEMBER_PLACEHOLDER, member)), path);
+            issues.push(...relativePathIssues(memberPath, source.relativePath, path));
+            issues.push(...pathFactIssues(memberPath, selection.kind, source.relativePath, pathFacts, workspaceRoot, workspaceRealRoot, path, rootPath));
+            resolvedMembers.push({ id: member, kind: selection.kind, path: memberPath });
+        }
+        resolvedSelections.push({ id: selection.id, root: selection.root, members: resolvedMembers });
+    }
+    for (const rule of definition.rules) {
+        if (rule.runner.name !== "grit")
+            continue;
+        for (const rootRole of rule.runner.acquisition.rootRoles) {
+            if (roots.has(rootRole) && !Object.hasOwn(source.manifest.roots, rootRole)) {
+                issues.push(issue("authority-manifest-invalid", source.relativePath, `Grit rule "${rule.id}" requires bound acquisition root role "${rootRole}".`));
+            }
+        }
+        for (const selectionId of rule.runner.acquisition.selections) {
+            if (selections.has(selectionId) && !Object.hasOwn(source.manifest.selections, selectionId)) {
+                issues.push(issue("authority-manifest-invalid", source.relativePath, `Grit rule "${rule.id}" requires bound acquisition selection "${selectionId}".`));
+            }
+        }
+    }
+    if (issues.length > 0)
+        return { issues };
+    return {
+        issues: [],
+        instance: {
+            id: source.manifest.id,
+            ownerProject: source.manifest.ownerProject,
+            blueprint: source.manifest.blueprint,
+            blueprintVersion: source.manifest.blueprintVersion,
+            manifestPath: source.relativePath,
+            roots: resolvedRoots,
+            selections: resolvedSelections,
+        },
+    };
+}
+function pathFactIssues(relativePath, expectedKind, sourcePath, facts, workspaceRoot, workspaceRealRoot, path, confinementRoot) {
+    const normalized = toRepositoryPath(relativePath, path);
+    const lexicalIssues = relativePathIssues(normalized, sourcePath, path);
+    if (lexicalIssues.length > 0)
+        return lexicalIssues;
+    const absolute = path.resolve(workspaceRoot, normalized);
+    if (!isContained(workspaceRoot, absolute, path)) {
+        return [
+            issue("authority-path-escape", sourcePath, `Path "${normalized}" escapes the workspace.`),
+        ];
+    }
+    if (confinementRoot !== undefined) {
+        const confinementAbsolute = path.resolve(workspaceRoot, confinementRoot);
+        if (!isContained(confinementAbsolute, absolute, path)) {
+            return [
+                issue("authority-path-escape", sourcePath, `Path "${normalized}" escapes selection root "${confinementRoot}".`),
+            ];
+        }
+    }
+    const fact = facts.get(normalized);
+    if (!fact || fact.kind === "missing") {
+        return [
+            issue("authority-path-missing", sourcePath, fact?.detail ?? `Admitted ${expectedKind} does not exist: "${normalized}".`),
+        ];
+    }
+    if (fact.filesystemError) {
+        return [
+            issue("authority-filesystem-failed", sourcePath, fact.detail ?? `Unable to inspect admitted path "${normalized}".`),
+        ];
+    }
+    if (fact.kind !== expectedKind) {
+        return [
+            issue("authority-path-kind-mismatch", sourcePath, `Admitted path "${normalized}" is ${fact.kind}, expected ${expectedKind}.`),
+        ];
+    }
+    if (!fact.realPath) {
+        return [
+            issue("authority-path-missing", sourcePath, fact.detail ?? `Unable to resolve admitted path "${normalized}".`),
+        ];
+    }
+    if (!isContained(workspaceRealRoot, fact.realPath, path)) {
+        return [
+            issue("authority-path-escape", sourcePath, `Path "${normalized}" escapes through a symbolic link.`),
+        ];
+    }
+    if (confinementRoot !== undefined) {
+        const rootFact = facts.get(toRepositoryPath(confinementRoot, path));
+        if (rootFact?.realPath && !isContained(rootFact.realPath, fact.realPath, path)) {
+            return [
+                issue("authority-path-escape", sourcePath, `Path "${normalized}" escapes selection root through a symbolic link.`),
+            ];
+        }
+    }
+    return [];
+}
+function ruleAssetPath(source, rule, path) {
+    const asset = rule.runner.name === "habitat" ? rule.runner.structure : rule.runner.pattern;
+    return toRepositoryPath(path.join(path.dirname(source.relativePath), asset), path);
+}
+function relativePathIssues(candidate, sourcePath, path) {
+    const invalid = candidate.includes("\\") ||
+        path.isAbsolute(candidate) ||
+        candidate.includes("//") ||
+        candidate.endsWith("/") ||
+        (candidate !== "." && toRepositoryPath(path.normalize(candidate), path) !== candidate) ||
+        candidate.split("/").some((segment) => segment === "" || segment === "..") ||
+        GLOB_CHARACTERS.test(candidate) ||
+        /[{}]/.test(candidate);
+    return invalid
+        ? [
+            issue("authority-path-invalid", sourcePath, `Path must be normalized, repository-relative, traversal-free, and non-glob: "${candidate}".`),
+        ]
+        : [];
+}
+function pathTemplateIssues(template, sourcePath, path) {
+    const placeholderCount = template.split(MEMBER_PLACEHOLDER).length - 1;
+    const substituted = template.replaceAll(MEMBER_PLACEHOLDER, "member");
+    const issues = relativePathIssues(substituted, sourcePath, path);
+    if (placeholderCount !== 1 || /[{}]/.test(template.replace(MEMBER_PLACEHOLDER, ""))) {
+        issues.push(issue("authority-definition-invalid", sourcePath, `pathTemplate must contain exactly one ${MEMBER_PLACEHOLDER} placeholder.`));
+    }
+    return issues;
+}
+function sortedUniqueIssues(values, sourcePath, label) {
+    const expected = [...new Set(values)].sort(textOrder);
+    return expected.length === values.length &&
+        values.every((value, index) => value === expected[index])
+        ? []
+        : [issue("authority-order-invalid", sourcePath, `${label} must be sorted and unique.`)];
+}
+function duplicateIssues(entries, code, label) {
+    const paths = new Map();
+    for (const entry of entries) {
+        paths.set(entry.identity, [...(paths.get(entry.identity) ?? []), entry.path]);
+    }
+    return [...paths.entries()]
+        .filter(([, sources]) => sources.length > 1)
+        .sort(([left], [right]) => textOrder(left, right))
+        .map(([identity, sources]) => issue(code, [...sources].sort(textOrder)[0] ?? "", `Duplicate ${label} identity "${identity}" at ${[...sources].sort(textOrder).join(", ")}.`));
+}
+function admit(validator, value, sourcePath) {
+    if (validator.Check(value)) {
+        return { ok: true, value };
+    }
+    const [, errors] = validator.Errors(value);
+    return {
+        ok: false,
+        issues: errors
+            .slice(0, MAX_CATALOG_ISSUES)
+            .map((error) => issue("authority-schema-invalid", sourcePath, error.message)),
+    };
+}
+function compareBlueprintSources(left, right) {
+    return (textOrder(left.definition.id, right.definition.id) ||
+        left.definition.version - right.definition.version);
+}
+function blueprintIdentity(definition) {
+    return `${definition.id}@${definition.version}`;
+}
+function isContained(root, target, path) {
+    const relative = path.relative(root, target);
+    return (relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+}
+function toRepositoryPath(value, path) {
+    return path.sep === "/" ? value : value.split(path.sep).join("/");
+}
+function stableIssues(issues) {
+    const unique = new Map();
+    for (const candidate of issues) {
+        const bounded = {
+            code: candidate.code,
+            path: candidate.path.slice(0, 4_096),
+            message: candidate.message.slice(0, 8_192),
+        };
+        unique.set(`${bounded.code}\0${bounded.path}\0${bounded.message}`, bounded);
+    }
+    return [...unique.values()]
+        .sort((left, right) => textOrder(left.path, right.path) ||
+        textOrder(left.code, right.code) ||
+        textOrder(left.message, right.message))
+        .slice(0, MAX_CATALOG_ISSUES);
+}
+function issue(code, path, message) {
+    return { code, path, message };
+}
+function textOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function renderCause(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return Object.freeze(value);
+}

package/dist/service/modules/catalog/model/policy/check.d.ts

@@ -0,0 +1,57 @@
+import type { RuleEvaluationFinding } from "@habitat-ai/resource-rule-evaluation";
+import type { HabitatCatalog } from "../dto/catalog.js";
+import type { CheckApplicationReport, CheckCatalogInput, CheckCatalogResult, CheckSelectionIssue } from "../dto/check.js";
+import type { HabitatStructureApplication, StructureDiagnostic } from "./structure.js";
+type RuleApplication = HabitatCatalog["applications"][number];
+type ResolvedGritRunner = Extract<RuleApplication["runner"], {
+    name: "grit";
+}>;
+type GritCheckRunner = Omit<ResolvedGritRunner, "acquisition"> & {
+    readonly acquisition: Omit<ResolvedGritRunner["acquisition"], "kind"> & {
+        readonly kind: "check";
+    };
+};
+/** Resolved application mechanically executable by the Grit check resource. */
+export type GritCheckApplication = Omit<RuleApplication, "runner"> & {
+    readonly runner: GritCheckRunner;
+};
+/** Runner set executable by catalog.check. */
+export type ExecutableCheckApplication = GritCheckApplication | HabitatStructureApplication;
+type GritCheckApplicationReport = Extract<CheckApplicationReport, {
+    runner: "grit";
+}>;
+type StructureCheckApplicationReport = Extract<CheckApplicationReport, {
+    runner: "habitat";
+}>;
+type CheckSelection = {
+    readonly ok: true;
+    readonly applications: readonly ExecutableCheckApplication[];
+} | {
+    readonly ok: false;
+    readonly issues: readonly CheckSelectionIssue[];
+};
+/** Selects the closed executable Grit-check and native structure application set. */
+export declare function selectCheckApplications(catalog: HabitatCatalog, input: CheckCatalogInput): CheckSelection;
+/** Extracts the first closed Grit fence from one admitted pattern asset. */
+export declare function extractGritProgram(contents: string): {
+    readonly ok: true;
+    readonly program: string;
+} | {
+    readonly ok: false;
+    readonly detail: string;
+};
+/** Produces one semantic report from trusted, repository-relative findings. */
+export declare function evaluatedApplication(application: GritCheckApplication, findings: readonly RuleEvaluationFinding[]): GritCheckApplicationReport;
+/** Produces one deterministic operational-error report for an application. */
+export declare function failedApplication(application: GritCheckApplication, reason: Extract<GritCheckApplicationReport["disposition"], {
+    kind: "failed";
+}>["reason"], detail: string): GritCheckApplicationReport;
+/** Produces one native Habitat report from pure structure diagnostics. */
+export declare function evaluatedStructureApplication(application: HabitatStructureApplication, diagnostics: readonly StructureDiagnostic[]): StructureCheckApplicationReport;
+/** Produces one deterministic native Habitat operational-error report. */
+export declare function failedStructureApplication(application: HabitatStructureApplication, reason: Extract<StructureCheckApplicationReport["disposition"], {
+    kind: "failed";
+}>["reason"], detail: string): StructureCheckApplicationReport;
+/** Completes a check from already ordered application reports. */
+export declare function completedCheck(applications: readonly CheckApplicationReport[]): CheckCatalogResult;
+export {};