project-tiny-context-harness 0.8.16 → 0.11.0

package/dist/lib/context-router/context-route.js

@@ -0,0 +1,127 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { CONTEXT_ROUTE_BUDGETS, CONTEXT_ROUTE_SCHEMA_VERSION, } from "./context-route-budget.js";
+import { defaultEntries, emptyResult } from "./context-route-candidates.js";
+import { stableRouteBudgetExceeded } from "./context-route-order.js";
+import { matchContextAreas, normalizeRepositoryInputs, resolveManualIncludes, } from "./context-route-paths.js";
+import { scanContextCatalogFiles } from "./context-route-scan.js";
+import { selectContextRouteCandidates } from "./context-route-selection.js";
+import { buildContextRouteTerms } from "./context-route-terms.js";
+export async function routeContext(input) {
+    const caseSensitive = input.case_sensitive ?? false;
+    const maxSearchResults = input.max_search_results ?? CONTEXT_ROUTE_BUDGETS.output_matches;
+    const inputExceeded = [];
+    const taskBytes = Buffer.byteLength(input.task, "utf8");
+    let task = input.task;
+    if (taskBytes > CONTEXT_ROUTE_BUDGETS.task_utf8_bytes) {
+        inputExceeded.push({
+            budget: "task_utf8_bytes",
+            limit: CONTEXT_ROUTE_BUDGETS.task_utf8_bytes,
+            observed: taskBytes,
+        });
+        task = utf8Prefix(input.task, CONTEXT_ROUTE_BUDGETS.task_utf8_bytes);
+    }
+    let catalog;
+    try {
+        catalog = await loadContextCatalog(input.project_root);
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to load Context Catalog: ${message(error)}`, { cause: error });
+    }
+    const catalogValid = !catalog.diagnostics.some((entry) => entry.severity === "error");
+    const defaultContext = defaultEntries(catalog);
+    if (!catalogValid) {
+        return emptyResult({
+            catalog,
+            caseSensitive,
+            defaultContext,
+            exceeded: inputExceeded,
+        });
+    }
+    const paths = normalizeRepositoryInputs(input.paths ?? [], "--path");
+    const triggers = [
+        ...new Set(catalog.registered_contexts.flatMap((entry) => (entry.context?.triggers ?? []).map((trigger) => trigger.normalize("NFC")))),
+    ].sort(compareUtf8Paths);
+    const termBuild = buildContextRouteTerms({
+        task,
+        explicit_terms: input.explicit_terms ?? [],
+        paths,
+        manifest_triggers: triggers,
+        case_sensitive: caseSensitive,
+    });
+    inputExceeded.push(...termBuild.exceeded);
+    const pathResult = matchContextAreas(catalog, paths);
+    let includes;
+    try {
+        includes = await resolveManualIncludes(catalog, input.includes ?? []);
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to resolve route includes: ${message(error)}`, { cause: error });
+    }
+    let scanned;
+    try {
+        scanned = await scanContextCatalogFiles({
+            files: catalog.context_files,
+            terms: termBuild.terms,
+            case_sensitive: caseSensitive,
+            max_search_results: maxSearchResults,
+        });
+    }
+    catch (error) {
+        throw new CliCommandError(CLI_EXIT_CODES.io, `unable to scan Context files: ${message(error)}`, { cause: error });
+    }
+    const selected = selectContextRouteCandidates({
+        catalog,
+        default_context: defaultContext,
+        path_matches: pathResult.matches,
+        literal_matches: scanned.matches_by_path,
+        includes,
+        task,
+        case_sensitive: caseSensitive,
+    });
+    const scanExceeded = [...inputExceeded, ...scanned.scan.exceeded];
+    const scan = {
+        ...scanned.scan,
+        budget_exceeded: scanExceeded.length > 0,
+        exceeded: stableRouteBudgetExceeded(scanExceeded),
+    };
+    return {
+        schema_version: CONTEXT_ROUTE_SCHEMA_VERSION,
+        complete: !scan.budget_exceeded,
+        catalog_valid: true,
+        experimental: true,
+        authority: false,
+        workflow_search_replaced: false,
+        matching: {
+            literal: true,
+            unicode_normalization: "NFC",
+            case_sensitive: caseSensitive,
+        },
+        scan,
+        output_truncated: scanned.output_truncated,
+        default_context: defaultContext,
+        candidates: selected.registered,
+        unregistered_matches: selected.unregistered,
+        ambiguous: pathResult.ambiguous,
+        unresolved: pathResult.unresolved,
+        diagnostics: catalog.diagnostics,
+    };
+}
+function utf8Prefix(value, maximumBytes) {
+    let bytes = 0;
+    let result = "";
+    for (const point of Array.from(value)) {
+        const size = Buffer.byteLength(point, "utf8");
+        if (bytes + size > maximumBytes)
+            break;
+        result += point;
+        bytes += size;
+    }
+    return result;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-units-migration.d.ts

@@ -0,0 +1,13 @@
+import type { Migration } from "./migrations.js";
+type ConversionPlan = {
+    status: "absent";
+} | {
+    status: "safe";
+    content: string;
+} | {
+    status: "manual";
+    reason: string;
+};
+export declare const contextUnitsMigration: Migration;
+export declare function planContextUnitsConversion(content: string): ConversionPlan;
+export {};

package/dist/lib/context-units-migration.js

@@ -0,0 +1,217 @@
+import { parse } from "smol-toml";
+import path from "node:path";
+import { CONTEXT_MANIFEST_PATH } from "./context-manifest.js";
+import { parseContextManifest } from "./context-manifest-schema.js";
+import { loadContextCatalog } from "./context-catalog/catalog-load.js";
+import { pathExists, readText, writeTextIfChanged } from "./fs.js";
+const ID = "context-units-to-context";
+const INTRODUCED_IN = "0.10.0";
+const DESCRIPTION = "Convert provably simple legacy [[context_units]] tables to Schema v4 [[context]] tables without rewriting the Manifest.";
+const SCOPE = "project_context/context.toml";
+const CURRENT_FIELDS = new Set([
+    "path",
+    "role",
+    "read_when",
+    "read_policy",
+    "triggers",
+    "default_children",
+]);
+const LEGACY_ONLY_FIELDS = new Set(["id", "area"]);
+export const contextUnitsMigration = {
+    id: ID,
+    introducedIn: INTRODUCED_IN,
+    description: DESCRIPTION,
+    scope: SCOPE,
+    risk: "safe",
+    manualMessage: "Convert complex legacy Context tables manually; Tiny Context will not canonicalize or guess their fields.",
+    detect: async (projectRoot) => {
+        const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+        if (!(await pathExists(manifestPath)))
+            return [];
+        const plan = planContextUnitsConversion(await readText(manifestPath));
+        if (plan.status === "absent")
+            return [];
+        return [
+            planItem(plan.status === "safe" ? "safe_pending" : "manual_required", plan.status === "safe"
+                ? "Convert simple legacy Context tables with a bounded byte patch."
+                : plan.reason),
+        ];
+    },
+    apply: migrateContextUnits,
+    verify: verifyContextUnitsMigration,
+};
+export function planContextUnitsConversion(content) {
+    if (!/^[ \t]*\[\[[ \t]*context_units[ \t]*\]\]/mu.test(content))
+        return { status: "absent" };
+    let decoded;
+    try {
+        const value = parse(content);
+        if (!isRecord(value))
+            return {
+                status: "manual",
+                reason: "legacy Manifest root is not a TOML table",
+            };
+        decoded = value;
+    }
+    catch (error) {
+        return {
+            status: "manual",
+            reason: `legacy Manifest is not valid TOML: ${message(error)}`,
+        };
+    }
+    const units = decoded.context_units;
+    if (!Array.isArray(units) || units.some((entry) => !isRecord(entry)))
+        return {
+            status: "manual",
+            reason: "context_units must be an array of TOML tables",
+        };
+    const currentContexts = decoded.context;
+    if (currentContexts !== undefined &&
+        (!Array.isArray(currentContexts) ||
+            currentContexts.some((entry) => !isRecord(entry))))
+        return {
+            status: "manual",
+            reason: "current context tables are malformed",
+        };
+    const currentPaths = new Set((currentContexts ?? [])
+        .map((entry) => (typeof entry.path === "string" ? entry.path : null))
+        .filter((entry) => entry !== null));
+    const legacyPaths = new Set();
+    for (const unit of units) {
+        const unknown = Object.keys(unit).filter((key) => !CURRENT_FIELDS.has(key) && !LEGACY_ONLY_FIELDS.has(key));
+        if (unknown.length > 0)
+            return {
+                status: "manual",
+                reason: `legacy Context table has unsupported fields: ${unknown.join(", ")}`,
+            };
+        if (typeof unit.path !== "string" || typeof unit.role !== "string")
+            return {
+                status: "manual",
+                reason: "every legacy Context table requires string path and role fields",
+            };
+        if (legacyPaths.has(unit.path) || currentPaths.has(unit.path))
+            return {
+                status: "manual",
+                reason: `legacy Context path conflicts with another table: ${unit.path}`,
+            };
+        legacyPaths.add(unit.path);
+    }
+    const patched = patchSimpleLegacyTables(content);
+    if (patched.status === "manual")
+        return patched;
+    if (patched.status === "absent")
+        return {
+            status: "manual",
+            reason: "legacy Context tables disappeared during conversion planning",
+        };
+    const parsed = parseContextManifest(patched.content);
+    if (parsed.errors.length > 0)
+        return {
+            status: "manual",
+            reason: `converted Manifest is not valid Schema v4: ${parsed.errors[0]}`,
+        };
+    return patched;
+}
+async function migrateContextUnits(projectRoot, _root, report) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    const plan = planContextUnitsConversion(await readText(manifestPath));
+    if (plan.status === "absent") {
+        report.skipped.push(`${CONTEXT_MANIFEST_PATH}#context-units`);
+        return;
+    }
+    if (plan.status === "manual")
+        throw new Error(`${CONTEXT_MANIFEST_PATH} changed after upgrade planning or is not safely convertible: ${plan.reason}`);
+    if (await writeTextIfChanged(manifestPath, plan.content))
+        report.changed.push(`${CONTEXT_MANIFEST_PATH}#context-units-to-context`);
+    else
+        report.skipped.push(`${CONTEXT_MANIFEST_PATH}#context-units-to-context`);
+}
+async function verifyContextUnitsMigration(projectRoot) {
+    const manifestPath = path.join(projectRoot, CONTEXT_MANIFEST_PATH);
+    const content = await readText(manifestPath);
+    if (/^[ \t]*\[\[[ \t]*context_units[ \t]*\]\]/mu.test(content))
+        throw new Error("context-units-to-context migration verification failed");
+    const catalog = await loadContextCatalog(projectRoot);
+    const errors = catalog.diagnostics.filter((entry) => entry.severity === "error");
+    if (errors.length > 0)
+        throw new Error(`context-units-to-context produced an invalid Catalog: ${errors[0].message}`);
+}
+function patchSimpleLegacyTables(content) {
+    const eols = content.match(/\r\n|\r|\n/gu) ?? [];
+    if (new Set(eols).size > 1)
+        return {
+            status: "manual",
+            reason: "legacy Manifest has mixed line endings",
+        };
+    const eol = eols[0] ?? "\n";
+    const lines = content.split(eol);
+    let inLegacyTable = false;
+    let convertedTables = 0;
+    const output = [];
+    for (const line of lines) {
+        const table = /^[ \t]*\[\[[ \t]*([^\]]+?)[ \t]*\]\](?:[ \t]*#.*)?$/u.exec(line);
+        const otherTable = /^[ \t]*\[[^[]/u.test(line);
+        if (table) {
+            inLegacyTable = table[1].trim() === "context_units";
+            if (inLegacyTable) {
+                output.push(line.replace(/(\[\[[ \t]*)context_units([ \t]*\]\])/u, "$1context$2"));
+                convertedTables += 1;
+            }
+            else
+                output.push(line);
+            continue;
+        }
+        if (otherTable)
+            inLegacyTable = false;
+        if (!inLegacyTable || !line.trim() || line.trimStart().startsWith("#")) {
+            output.push(line);
+            continue;
+        }
+        const assignment = /^[ \t]*([A-Za-z][A-Za-z0-9_-]*)[ \t]*=(.*)$/u.exec(line);
+        if (!assignment)
+            return {
+                status: "manual",
+                reason: "legacy Context tables must use simple single-line field assignments",
+            };
+        const key = assignment[1];
+        if (!CURRENT_FIELDS.has(key) && !LEGACY_ONLY_FIELDS.has(key))
+            return {
+                status: "manual",
+                reason: `legacy Context table has unsupported source field: ${key}`,
+            };
+        try {
+            parse(line);
+        }
+        catch {
+            return {
+                status: "manual",
+                reason: `legacy Context field ${key} is not a complete single-line TOML value`,
+            };
+        }
+        if (!LEGACY_ONLY_FIELDS.has(key))
+            output.push(line);
+    }
+    if (convertedTables === 0)
+        return {
+            status: "manual",
+            reason: "no exact legacy table header was found",
+        };
+    return { status: "safe", content: output.join(eol) };
+}
+function planItem(status, reason) {
+    return {
+        id: ID,
+        introducedIn: INTRODUCED_IN,
+        description: DESCRIPTION,
+        scope: SCOPE,
+        status,
+        path: CONTEXT_MANIFEST_PATH,
+        message: reason,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/design-authority-binding.d.ts

@@ -0,0 +1,7 @@
+import { type DesignAuthorityHandoffBinding, type DesignAuthorityHandoffResolution } from "./design-authority-types.js";
+export declare function parseDesignAuthorityHandoffBinding(value: unknown, label: string): DesignAuthorityHandoffBinding;
+export declare function resolveDesignAuthorityHandoffBinding(input: {
+    repository: string;
+    style_dependency: "style-bearing" | "non-fidelity" | "mixed";
+    binding?: DesignAuthorityHandoffBinding;
+}): Promise<DesignAuthorityHandoffResolution>;

package/dist/lib/design-authority-binding.js

@@ -0,0 +1,96 @@
+import { loadCurrentDesignAuthorityClosure, inspectDesignAuthorityClosure, } from "./design-authority-closure.js";
+import { DESIGN_AUTHORITY_ENTRY_PATH, DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION, DESIGN_AUTHORITY_MANIFEST_PATH, isDesignAuthorityDigest, } from "./design-authority-types.js";
+import { designResourceShapeFail } from "./design-resource-handoff-shape-primitives.js";
+import { literal, object, string } from "./long-task-shape-primitives.js";
+export function parseDesignAuthorityHandoffBinding(value, label) {
+    const base = object(value, label, ["kind"], [
+        "format_version",
+        "entry_path",
+        "manifest_path",
+        "closure_digest",
+        "revision",
+        "rationale",
+    ]);
+    const kind = literal(base.kind, ["repository-closure", "not-applicable"], `${label}.kind`);
+    if (kind === "not-applicable") {
+        const row = object(value, label, ["kind", "rationale"]);
+        return {
+            kind,
+            rationale: string(row.rationale, `${label}.rationale`),
+        };
+    }
+    const row = object(value, label, [
+        "kind",
+        "format_version",
+        "entry_path",
+        "manifest_path",
+        "closure_digest",
+        "revision",
+    ]);
+    if (row.format_version !== DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION)
+        designResourceShapeFail(`${label}.format_version`, `must equal ${DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION}`);
+    if (row.entry_path !== DESIGN_AUTHORITY_ENTRY_PATH)
+        designResourceShapeFail(`${label}.entry_path`, `must equal ${DESIGN_AUTHORITY_ENTRY_PATH}`);
+    if (row.manifest_path !== null &&
+        row.manifest_path !== DESIGN_AUTHORITY_MANIFEST_PATH)
+        designResourceShapeFail(`${label}.manifest_path`, `must be null or ${DESIGN_AUTHORITY_MANIFEST_PATH}`);
+    if (!isDesignAuthorityDigest(row.closure_digest))
+        designResourceShapeFail(`${label}.closure_digest`, "must be a sha256:<64 lowercase hex> identity");
+    if (row.revision !== null && typeof row.revision !== "string")
+        designResourceShapeFail(`${label}.revision`, "must be a string or null");
+    if (typeof row.revision === "string" && !row.revision.trim())
+        designResourceShapeFail(`${label}.revision`, "must not be empty");
+    return {
+        kind,
+        format_version: DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION,
+        entry_path: DESIGN_AUTHORITY_ENTRY_PATH,
+        manifest_path: row.manifest_path,
+        closure_digest: row.closure_digest,
+        revision: row.revision,
+    };
+}
+export async function resolveDesignAuthorityHandoffBinding(input) {
+    if (!input.binding) {
+        const inspection = await inspectDesignAuthorityClosure(input.repository);
+        if (inspection.status !== "valid" || !inspection.identity)
+            invalid(`legacy_omission_without_current_authority:${inspection.diagnostics.length
+                ? inspection.diagnostics
+                    .map((item) => `${item.code}:${item.detail}`)
+                    .join("|")
+                : inspection.status}`);
+        if (inspection.mode !== "legacy")
+            invalid("legacy_omission_bundle_not_allowed");
+        return {
+            identity: inspection.identity,
+            member_paths: inspection.member_paths,
+            compatibility_derived: true,
+        };
+    }
+    if (input.binding.kind === "not-applicable") {
+        if (input.style_dependency !== "non-fidelity")
+            invalid("not_applicable_requires_non_fidelity");
+        return {
+            identity: null,
+            member_paths: [],
+            compatibility_derived: false,
+        };
+    }
+    const current = await loadCurrentDesignAuthorityClosure(input.repository);
+    for (const field of [
+        "format_version",
+        "entry_path",
+        "manifest_path",
+        "closure_digest",
+        "revision",
+    ])
+        if (current.identity[field] !== input.binding[field])
+            invalid(`identity_mismatch:${field}:${String(input.binding[field])}:${String(current.identity[field])}`);
+    return {
+        identity: current.identity,
+        member_paths: current.member_paths,
+        compatibility_derived: false,
+    };
+}
+function invalid(reason) {
+    throw new Error(`design_resource_handoff_invalid:project_design_authority:${reason}`);
+}

package/dist/lib/design-authority-closure.d.ts

@@ -0,0 +1,3 @@
+import { type DesignAuthorityClosureSnapshot, type DesignAuthorityInspection } from "./design-authority-types.js";
+export declare function inspectDesignAuthorityClosure(repositoryInput: string): Promise<DesignAuthorityInspection>;
+export declare function loadCurrentDesignAuthorityClosure(repository: string): Promise<DesignAuthorityClosureSnapshot>;

package/dist/lib/design-authority-closure.js

@@ -0,0 +1,201 @@
+import path from "node:path";
+import { digestDesignAuthorityMembers, enforceDesignAuthorityTotalLimit, projectDesignAuthorityMembers, } from "./design-authority-digest.js";
+import { acquireDesignAuthorityManifest, acquireDesignAuthorityText, designAuthorityPathExists, } from "./design-authority-files.js";
+import { declaredDesignAuthorityFormat } from "./design-authority-format.js";
+import { designAuthorityManifestProjection, parseDesignAuthorityManifest, } from "./design-authority-manifest.js";
+import { analyzeDesignAuthorityLinks } from "./design-authority-links.js";
+import { designAuthorityRevision, projectDesignAuthorityTokens, } from "./design-authority-tokens.js";
+import { DESIGN_AUTHORITY_ENTRY_PATH, DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION, DESIGN_AUTHORITY_LIMITS, DESIGN_AUTHORITY_MANIFEST_PATH, } from "./design-authority-types.js";
+export async function inspectDesignAuthorityClosure(repositoryInput) {
+    const repository = path.resolve(repositoryInput);
+    const entryExists = await designAuthorityPathExists(path.join(repository, DESIGN_AUTHORITY_ENTRY_PATH));
+    const manifestExists = await designAuthorityPathExists(path.join(repository, DESIGN_AUTHORITY_MANIFEST_PATH));
+    if (!entryExists && manifestExists)
+        return emptyInspection("invalid", "bundle", [
+            {
+                severity: "error",
+                code: "bundle_entry_missing",
+                path: DESIGN_AUTHORITY_ENTRY_PATH,
+                detail: `${DESIGN_AUTHORITY_MANIFEST_PATH} exists without the canonical DESIGN.md entry`,
+            },
+        ]);
+    if (!entryExists)
+        return emptyInspection("missing", "missing", [
+            {
+                severity: "warning",
+                code: "design_authority_missing",
+                path: DESIGN_AUTHORITY_ENTRY_PATH,
+                detail: "DESIGN.md does not exist",
+            },
+        ]);
+    try {
+        const snapshot = await buildDesignAuthorityClosure(repository);
+        return {
+            schema_version: 1,
+            status: snapshot.diagnostics.some((item) => item.severity === "error")
+                ? "invalid"
+                : "valid",
+            ...snapshot,
+        };
+    }
+    catch (error) {
+        return emptyInspection("invalid", manifestExists ? "bundle" : await declaredModeHint(repository), [
+            {
+                severity: "error",
+                code: "design_authority_invalid",
+                detail: message(error),
+            },
+        ]);
+    }
+}
+export async function loadCurrentDesignAuthorityClosure(repository) {
+    const inspection = await inspectDesignAuthorityClosure(repository);
+    if (inspection.status !== "valid" || !inspection.identity)
+        throw new Error(`design_authority_invalid:${inspection.diagnostics
+            .map((item) => `${item.code}:${item.detail}`)
+            .join("|")}`);
+    if (inspection.mode === "missing")
+        throw new Error("design_authority_invalid:missing_mode");
+    return {
+        mode: inspection.mode,
+        identity: inspection.identity,
+        manifest: inspection.manifest,
+        claimed_closure_digest: inspection.claimed_closure_digest,
+        members: inspection.members,
+        member_paths: inspection.member_paths,
+        generated_tokens: inspection.generated_tokens,
+        diagnostics: inspection.diagnostics,
+    };
+}
+async function buildDesignAuthorityClosure(repository) {
+    const entry = await acquireDesignAuthorityText(repository, DESIGN_AUTHORITY_ENTRY_PATH, "design_authority_entry");
+    const declaredFormat = declaredDesignAuthorityFormat(entry.content);
+    const manifest = await acquireDesignAuthorityManifest(repository);
+    if (declaredFormat === "bundle-v1" && !manifest)
+        invalid("bundle_manifest_missing");
+    if (declaredFormat === null && manifest)
+        invalid("bundle_marker_missing");
+    const digestMembers = [
+        { ...entry, kind: "entry" },
+    ];
+    const markdownSources = [{ path: entry.path, content: entry.content }];
+    let parsedManifest = null;
+    let claimedDigest = null;
+    if (manifest) {
+        parsedManifest = parseDesignAuthorityManifest(manifest.content);
+        claimedDigest = parsedManifest.closure_digest;
+        if (parsedManifest.authority_files.length +
+            parsedManifest.generated_files.length +
+            2 >
+            DESIGN_AUTHORITY_LIMITS.max_members)
+            invalid("member_limit_exceeded");
+        for (const file of parsedManifest.authority_files) {
+            const acquired = await acquireDesignAuthorityText(repository, file.path, "design_authority_member");
+            digestMembers.push({ ...acquired, kind: "authority" });
+            markdownSources.push({ path: acquired.path, content: acquired.content });
+        }
+        for (const file of parsedManifest.generated_files)
+            digestMembers.push({
+                ...(await acquireDesignAuthorityText(repository, file.path, "design_authority_generated")),
+                kind: "generated",
+            });
+        const projection = designAuthorityManifestProjection(parsedManifest);
+        digestMembers.push({
+            path: DESIGN_AUTHORITY_MANIFEST_PATH,
+            content: projection,
+            raw: Buffer.from(projection),
+            normalized: Buffer.from(projection),
+            kind: "manifest",
+        });
+    }
+    enforceDesignAuthorityTotalLimit(digestMembers);
+    const generatedTokens = projectDesignAuthorityTokens(entry.content);
+    const diagnostics = [];
+    if (parsedManifest?.generated_files.length) {
+        const generated = digestMembers.find((member) => member.kind === "generated");
+        if (!generatedTokens.success)
+            diagnostics.push({
+                severity: "error",
+                code: "design_authority_token_projection_failed",
+                path: DESIGN_AUTHORITY_ENTRY_PATH,
+                detail: generatedTokens.error,
+            });
+        else if (!generated.raw.equals(Buffer.from(generatedTokens.content)))
+            diagnostics.push({
+                severity: "error",
+                code: "design_authority_generated_tokens_stale",
+                path: generated.path,
+                detail: "bytes differ from the deterministic DESIGN.md DTCG projection",
+            });
+    }
+    const declared = new Set(digestMembers.map((member) => member.path));
+    diagnostics.push(...(await analyzeDesignAuthorityLinks({
+        repository,
+        sources: markdownSources,
+        declared_paths: declared,
+    })));
+    const computedDigest = digestDesignAuthorityMembers(digestMembers);
+    if (claimedDigest && claimedDigest !== computedDigest)
+        diagnostics.push({
+            severity: "error",
+            code: "design_authority_closure_digest_mismatch",
+            path: DESIGN_AUTHORITY_MANIFEST_PATH,
+            detail: `claimed=${claimedDigest}; computed=${computedDigest}`,
+        });
+    const members = projectDesignAuthorityMembers(digestMembers);
+    return {
+        mode: parsedManifest ? "bundle" : "legacy",
+        identity: {
+            format_version: DESIGN_AUTHORITY_IDENTITY_FORMAT_VERSION,
+            entry_path: DESIGN_AUTHORITY_ENTRY_PATH,
+            manifest_path: parsedManifest ? DESIGN_AUTHORITY_MANIFEST_PATH : null,
+            closure_digest: computedDigest,
+            revision: designAuthorityRevision(entry.content),
+        },
+        manifest: parsedManifest,
+        claimed_closure_digest: claimedDigest,
+        members,
+        member_paths: members.map((member) => member.path),
+        generated_tokens: generatedTokens.success ? generatedTokens.content : null,
+        diagnostics: diagnostics.sort(compareDiagnostic),
+    };
+}
+function compareDiagnostic(left, right) {
+    const severity = Buffer.from(left.severity, "utf8").compare(Buffer.from(right.severity, "utf8"));
+    if (severity)
+        return severity;
+    return Buffer.from(`${left.path ?? ""}\0${left.code}\0${left.detail}`).compare(Buffer.from(`${right.path ?? ""}\0${right.code}\0${right.detail}`));
+}
+function emptyInspection(status, mode, diagnostics) {
+    return {
+        schema_version: 1,
+        status,
+        mode,
+        identity: null,
+        manifest: null,
+        claimed_closure_digest: null,
+        members: [],
+        member_paths: [],
+        generated_tokens: null,
+        diagnostics,
+    };
+}
+async function declaredModeHint(repository) {
+    try {
+        const entry = await acquireDesignAuthorityText(repository, DESIGN_AUTHORITY_ENTRY_PATH, "design_authority_entry");
+        return declaredDesignAuthorityFormat(entry.content) === "bundle-v1"
+            ? "bundle"
+            : "legacy";
+    }
+    catch (error) {
+        return /bundle_(?:marker|entry)/u.test(message(error))
+            ? "bundle"
+            : "legacy";
+    }
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function invalid(reason) {
+    throw new Error(`design_authority_invalid:${reason}`);
+}

package/dist/lib/design-authority-delta-codec-primitives.d.ts

@@ -0,0 +1,10 @@
+export type DeltaRow = Record<string, unknown>;
+export declare function deltaRow(value: unknown, label: string, required: string[], optional?: string[]): DeltaRow;
+export declare function deltaArray(value: unknown, label: string): unknown[];
+export declare function deltaText(value: unknown, label: string): string;
+export declare function deltaOneOf<const T extends readonly string[]>(value: unknown, allowed: T, label: string): T[number];
+export declare function deltaExact<T extends string | number>(value: unknown, expected: T, label: string): T;
+export declare function deltaStringSet(value: unknown, label: string, allowEmpty?: boolean): string[];
+export declare function deltaSourceRefSet(value: unknown, label: string, allowEmpty?: boolean): string[];
+export declare function deltaCompare(left: string, right: string): number;
+export declare function deltaInvalid(label: string, reason: string): never;