agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/write/explain.js

@@ -0,0 +1,332 @@
+import path from "node:path";
+import { ArtifactSchemaValidator } from "../../hooks/validateArtifact/index.js";
+import { loadArtifactRegistry, resolveArtifactPath } from "../../registries/artifactRegistry.js";
+import { schemaBudget, projectedFields } from "./fields.js";
+import { loadMutationGrammar, } from "./grammar.js";
+import { operationSpec, mutationParityMatrix, writerOwnedFields, verbsForArtifact, } from "./operations.js";
+import { reject } from "./errors.js";
+import { structuredInputDescriptor, structuredInputSchemaProjection } from "./input.js";
+import { artifactSchemaFieldsForOperation } from "../../registries/artifactSchemaProjection.js";
+function defaultVerb(artifact) {
+    const verb = verbsForArtifact(artifact).find((candidate) => candidate !== "explain");
+    if (!verb)
+        reject({ class: "unsupported_target", message: `artifact "${artifact}" has no public mutation` });
+    return verb;
+}
+function entityBoundary(artifact, verb) {
+    if (artifact === "progress")
+        return "progress_cycle";
+    if (artifact === "health")
+        return "health_audit";
+    if (artifact === "plan")
+        return ["append", "update", "set-status", "supersede", "record-evaluation"].includes(verb) ? "plan_task" : "plan";
+    if (artifact === "objective")
+        return "objective";
+    if (artifact === "experiments")
+        return "experiment";
+    if (artifact === "todo")
+        return "todo_item";
+    if (artifact === "docs")
+        return "documentation_inventory_entry";
+    return verb === "append" ? "decision" : verb === "update" ? "decision_satisfaction" : "decision_revision";
+}
+function exposedFields(artifact, verb, spec, validator) {
+    let source = projectedFields(spec, validator);
+    return source.map((field) => ({
+        flag: field.flag,
+        field: field.field,
+        required: field.required === true,
+        type: field.kind,
+        ...(field.validValues ? { valid_values: field.validValues } : {}),
+        ...(field.repeatable ? { repeatable: true } : {}),
+        ...(field.description ? { description: artifact === "objective" && field.flag === "--id"
+                ? "Bare ten-letter objective ID returned by objective create or list."
+                : artifact === "plan" && field.flag === "--id" && ["update", "set-status", "supersede", "record-evaluation"].includes(verb)
+                    ? "Bare ten-letter task ID returned by plan task append or list."
+                    : artifact === "plan" && field.flag === "--plan"
+                        ? "Bare ten-letter plan ID returned by plan create or list."
+                        : artifact === "experiments" && field.flag === "--objective"
+                            ? "Bare ten-letter objective ID owning the experiment."
+                            : artifact === "experiments" && field.flag === "--id"
+                                ? "Existing bare ten-letter experiment ID for exact immutable replay."
+                                : field.description } : {}),
+        ...(field.kind === "date" ? { format: "YYYY-MM-DD" } : {}),
+        ...(field.kind === "datetime" ? { format: "YYYY-MM-DD HH:MM" } : {}),
+        ...(field.flag === "--timestamp" ? { default: "now" } : {}),
+        ...(field.flag === "--date" ? { default: "today" } : {}),
+    }));
+}
+function pathFor(artifact, verb, projectRoot) {
+    const record = loadArtifactRegistry().get(artifact);
+    if (!record)
+        reject({ class: "unsupported_target", message: `artifact "${artifact}" is not registered` });
+    const entityArtifact = artifact !== "glossary";
+    const resolved = entityArtifact
+        ? path.join(projectRoot, ".agentera", "entities", artifact, entityBoundary(artifact, verb), "<id>.yaml")
+        : resolveArtifactPath(record, projectRoot, { strictWrite: true });
+    return path.relative(projectRoot, resolved) || resolved;
+}
+function inputProjection(spec) {
+    return {
+        mode: spec.inputMode,
+        ...(spec.inputRoot ? { root: spec.inputRoot } : {}),
+        sources: spec.inputSources,
+        structured_sources: spec.structuredInputSources,
+        cli_owned_fields: spec.cliOwnedFields,
+        ...(spec.inputMode === "structured" ? {
+            flag: "--input",
+            stdin_value: "-",
+            parser: "yaml_or_json_mapping",
+        } : {}),
+    };
+}
+export function buildExplain(artifact, projectRoot, requestedVerb) {
+    const verb = (requestedVerb ?? defaultVerb(artifact));
+    const spec = operationSpec(artifact, verb);
+    const grammar = loadMutationGrammar();
+    const declaration = grammar.operations.find((operation) => operation.artifact === artifact && operation.verb === verb);
+    if (!spec || !declaration) {
+        reject({
+            class: "invalid_choice",
+            message: `verb "${verb}" does not apply to ${artifact}`,
+            valid_values: verbsForArtifact(artifact),
+        });
+    }
+    const record = loadArtifactRegistry().get(artifact);
+    if (!record)
+        reject({ class: "unsupported_target", message: `artifact "${artifact}" is not registered` });
+    const validator = new ArtifactSchemaValidator();
+    const result = {
+        schemaVersion: "agentera.stateWriteExplain.v1",
+        command: `state ${artifact} explain`,
+        requested_verb: verb,
+        artifact,
+        path: pathFor(artifact, verb, projectRoot),
+        verbs: verbsForArtifact(artifact),
+        contract_digest: grammar.contractDigest,
+        mutation_class: declaration.mutationClass,
+        selectors: declaration.selectors,
+        preconditions: declaration.preconditions,
+        owned_fields: declaration.ownedFields,
+        input: inputProjection(spec),
+        recovery: declaration.recovery,
+        examples: declaration.examples,
+        bounds: declaration.bounds,
+        next: {},
+        budget: schemaBudget(artifact, validator),
+        fields: exposedFields(artifact, verb, spec, validator),
+    };
+    const owned = writerOwnedFields(artifact);
+    if (owned.length)
+        result.writer_owned_fields = owned;
+    if (spec.compacts) {
+        result.compaction = `not applicable; each canonical ${artifact} entity is authority and no aggregate projection or numbered archive is written`;
+    }
+    if (spec.inputMode === "structured") {
+        const structured = structuredInputDescriptor(artifact, verb);
+        result.input_schema = {
+            flag: "--input",
+            sources: spec.inputSources,
+            parser: "yaml_or_json_mapping",
+            accepts_json: true,
+            root: spec.inputRoot,
+            cli_owned_fields: spec.cliOwnedFields,
+            defaulted_fields: artifact === "health" ? { date: "today" } : {},
+            groups: artifact === "glossary"
+                ? ["PROPOSAL", "CONFIRMATION"]
+                : artifact === "health"
+                    ? ["AUDIT", "DIMENSION", "FINDING", "TRENDS"]
+                    : artifact === "experiments"
+                        ? ["EXPERIMENT"]
+                        : artifact === "todo"
+                            ? ["TODO_PUBLIC", "TODO_OPERATIONAL"]
+                            : artifact === "progress"
+                                ? ["CYCLE", "CONTEXT", "GLOSSARY_CAVEAT"]
+                                : artifact === "decisions"
+                                    ? ["DECISION", "ALTERNATIVES"]
+                                    : ["HEADER", "PLAN", "SCOPE", "TASK"],
+        };
+        if (structured) {
+            const projection = structuredInputSchemaProjection(structured);
+            result.input_schema = {
+                ...result.input_schema,
+                structured_fields: projection.fields,
+                semantics: projection.semantics,
+                owned_fields: projection.owned_fields,
+                immutable_fields: projection.immutable_fields,
+                bounds: projection.bounds,
+                examples: projection.examples,
+            };
+        }
+        const artifactSchemaFields = artifactSchemaFieldsForOperation(validator.loadSchema(artifact), verb);
+        if (artifactSchemaFields.length > 0)
+            result.input_schema = {
+                ...result.input_schema,
+                artifact_schema_fields: artifactSchemaFields,
+            };
+        if (artifact === "progress" && verb === "append")
+            result.input_schema = { ...result.input_schema, record_fields: ["timestamp", "type", "phase", "what", "inspiration", "discovered", "verified", "next", "context", "glossary_caveat"] };
+        if (artifact === "decisions" && verb === "append")
+            result.input_schema = { ...result.input_schema, record_fields: ["date", "question", "context", "alternatives", "choice", "reasoning", "confidence", "feeds_into"] };
+        if (artifact === "decisions" && verb === "amend")
+            result.input_schema = { ...result.input_schema, record_fields: ["question", "context", "alternatives", "choice", "reasoning", "confidence", "feeds_into"] };
+        if (artifact === "plan" && verb === "append")
+            result.input_schema = { ...result.input_schema, record_fields: ["name", "depends_on", "acceptance", "evidence", "blocked_reason"] };
+        if (artifact === "plan" && verb === "update")
+            result.input_schema = { ...result.input_schema, record_fields: ["name", "depends_on", "acceptance", "evidence", "blocked_reason", "surprise"], clearable_patch_fields: ["depends_on", "acceptance", "evidence", "blocked_reason"] };
+        if (artifact === "todo") {
+            result.input_schema = {
+                ...result.input_schema,
+                typed_fields: ["kind", "target_version", "title", "requirements", "acceptance", "release_blocker", "severity", "readiness"],
+                clearable_patch_fields: ["target_version", "requirements", "acceptance", "readiness"],
+                full_record_required_fields: ["kind", "target_version", "title", "requirements", "acceptance", "release_blocker", "severity"],
+            };
+        }
+    }
+    if (artifact === "glossary") {
+        result.identity = {
+            display_name: record.displayName,
+            default_path: record.defaultPath,
+            authority: "artifact registry",
+        };
+        result.implementation_status = record.implementationStatus;
+        result.producer = [...record.producers].sort();
+        result.request_schema_version = "agentera.glossaryPublicationRequest.v1";
+        result.document_schema_version = "agentera.projectGlossary.v1";
+    }
+    result.guidance = decisionsGuidance(artifact, verb, artifact === "health", true);
+    result.example = exampleFor(artifact, verb);
+    return result;
+}
+export function buildExplainAll(artifact, projectRoot) {
+    const grammar = loadMutationGrammar();
+    const operations = verbsForArtifact(artifact)
+        .filter((verb) => verb !== "explain")
+        .map((verb) => buildExplain(artifact, projectRoot, verb));
+    return {
+        schemaVersion: "agentera.stateWriteExplainAll.v1",
+        command: `state ${artifact} explain --all`,
+        artifact,
+        authority: grammar.authority,
+        contract_digest: grammar.contractDigest,
+        verbs: operations.map((operation) => operation.requested_verb),
+        operations,
+        parity_matrix: mutationParityMatrix([artifact]),
+    };
+}
+function decisionsGuidance(artifact, verb, _entityHealth = false, entityArtifact = false) {
+    const base = [
+        "do not embed commit hashes; evidence belongs in the commit message (Decision 66)",
+        "fold the artifact write into the implementation commit per AGENTS.md",
+    ];
+    if (artifact === "glossary")
+        return [
+            "build is the only publisher; audit and discuss remain mutation-free",
+            "confirmation.confirmed_by must be user and must bind the exact proposal digest and timestamp",
+            "the writer revalidates every cited project source line and publishes approval plus entry as one atomic document",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "plan" && verb === "create")
+        return ["the CLI assigns bare ten-letter envelope IDs to the plan and each task and publishes one canonical file per entity", "task numbers and dependency values in this atomic input are create-local symbolic ordinals; the writer removes them and resolves dependencies to bare task IDs", "legacy composite header.id values are migration-only and never public selectors", ...base];
+    if (entityArtifact && artifact === "plan" && verb === "record-evaluation")
+        return [
+            "select one task entity with its bare ten-letter --id; numeric and composite selectors are unavailable",
+            "evaluate before completing a task during normal orchestration",
+            "a first PASS on an unevaluated complete replacement is recovery only when an open same-plan superseded predecessor names it in superseded_by",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "plan" && verb === "supersede")
+        return [
+            "select one task entity with its bare ten-letter --id; numeric and composite selectors are unavailable",
+            "each replacement must be complete with latest persisted PASS",
+            "if a non-PASS replacement is not already referenced by a historical superseded predecessor, reopen it, record PASS, complete it, and retry",
+            "if a referenced historical replacement is unevaluated complete, record its allowed first PASS while it remains complete, then retry",
+            "if a referenced historical replacement has an existing non-PASS evaluation, first-PASS recovery is unavailable; use another complete latest-PASS replacement, or keep or archive the plan without claiming completion as applicable",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "plan" && verb === "update")
+        return ["select one task entity with its bare ten-letter --id; supply an omission-preserving YAML/JSON task patch through --input", "task status, supersession, evaluation, and plan lifecycle remain flag-only transitions; surprise remains plan-level content", ...base];
+    if (entityArtifact && artifact === "plan" && verb === "set-status")
+        return ["select one task entity with its bare ten-letter --id; lifecycle status is a flag-only transition", ...base];
+    if (entityArtifact && artifact === "plan" && verb === "append")
+        return ["the CLI assigns a bare ten-letter ID to the new task entity", "supply one complete YAML/JSON task record through --input; dependencies must be bare ten-letter IDs in the selected plan", ...base];
+    if (entityArtifact && artifact === "plan")
+        return [
+            "the active plan entity is selected by lifecycle state",
+            ...(verb === "set-plan-status" ? ["open-to-complete requires every superseded_by replacement to be complete with latest persisted PASS; historical unevaluated complete replacements may record their allowed first PASS, then retry"] : []),
+            ...base,
+        ];
+    if (entityArtifact && artifact === "experiments")
+        return ["select the owner with its bare ten-letter --objective ID; numeric and composite selectors are unavailable", "omit --id for a new immutable experiment; pass an existing bare --id only for exact replay", ...base];
+    if (entityArtifact && artifact === "objective" && verb === "update")
+        return ["select one objective with its bare ten-letter --id; numeric selectors are unavailable", "the CLI preserves that ID while replacing the validated objective record", ...base];
+    if (entityArtifact && artifact === "objective")
+        return ["a bare ten-letter objective ID is assigned by the CLI; do not pass an identity", ...base];
+    if (entityArtifact && artifact === "todo" && verb === "update")
+        return [
+            "select one TODO item with its bare ten-letter --id; numeric, prefixed, composite, alias, and path identities are unavailable",
+            "the input document is a patch: omitted fields preserve state and only target_version, requirements, acceptance, and readiness accept typed clears",
+            "public fields are TODO.md-owned; readiness, dependencies, gates, and evidence are Agentera-owned",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "todo" && ["set-severity", "supersede", "resolve", "reopen"].includes(verb))
+        return [
+            "select one TODO item with its bare ten-letter --id; lifecycle transitions are flag-only and accept no --input record",
+            "supply a reason and YYYY-MM-DD date; supersede additionally requires a distinct existing replacement ID",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "todo")
+        return [
+            "a bare ten-letter TODO item ID is assigned by the CLI; status starts open",
+            "create requires a full typed TODO record; readiness is optional and absent means needs-triage",
+            "the public marker is rendered as [kind:target] and is not stored in title prose",
+            ...base,
+        ];
+    if (entityArtifact && artifact === "docs" && verb === "update")
+        return ["select one documentation inventory entry with its bare ten-letter --id; path remains record data, not identity", ...base];
+    if (entityArtifact && artifact === "docs")
+        return ["a bare ten-letter documentation inventory ID is assigned by the CLI; path remains record data", ...base];
+    if (artifact === "progress" && verb === "append")
+        return ["supply one progress cycle mapping with --input PATH or --input -; the writer assigns id, artifact, and publication_order", "record content flags are retired; inspect the structured record_fields in explain before writing", ...base];
+    if (artifact === "decisions" && verb === "append")
+        return ["a bare ten-letter ID is assigned by the CLI; do not pass an identity", "supply one decision record mapping with --input PATH or --input -; the writer assigns id and artifact", "record content flags are retired; satisfaction remains a separate flag-only transition", ...base];
+    if (artifact === "decisions" && verb === "update")
+        return ["select one base decision with its bare --id; numeric selectors are unavailable", "update replaces only that decision's authority-owned satisfaction entity after transition validation", ...base];
+    if (artifact === "decisions" && verb === "amend")
+        return ["select one base decision with its bare --id and current --base-sha256", "supply amendable decision content with --input PATH or --input -; record content flags are retired", "apply publishes one immutable revision entity; identical retries converge and same-base divergence conflicts", ...base];
+    return [entityArtifact ? "a bare ten-letter ID is assigned by the CLI; do not pass an identity" : "the writer assigns canonical identity", ...base];
+}
+export function exampleFor(artifact, verb) {
+    const declaration = loadMutationGrammar().operations.find((operation) => operation.artifact === artifact && operation.verb === verb);
+    if (declaration?.examples[0])
+        return declaration.examples[0];
+    return `agentera state ${artifact} ${verb} --format json`;
+}
+export function renderExplainText(explain) {
+    const lines = [
+        `usage: agentera state ${explain.artifact} ${explain.requested_verb ?? "explain --all"} [flags]`,
+        "",
+        `${explain.artifact} (${explain.path ?? "mutation grammar"})`,
+        `Class: ${String(explain.mutation_class ?? "all")}`,
+        `Contract digest: ${String(explain.contract_digest ?? "unknown")}`,
+    ];
+    const fields = Array.isArray(explain.fields) ? explain.fields : [];
+    if (fields.length) {
+        const required = fields.filter((field) => field.required);
+        const optional = fields.filter((field) => !field.required);
+        for (const [heading, entries] of [["Required", required], ["Optional", optional]]) {
+            if (!entries.length)
+                continue;
+            lines.push("", `${heading}:`);
+            for (const field of entries) {
+                const values = Array.isArray(field.valid_values) ? ` one of: ${field.valid_values.join(", ")}` : "";
+                lines.push(`  ${String(field.flag).padEnd(24)}${values || String(field.description ?? field.field)}`);
+            }
+        }
+    }
+    const input = explain.input;
+    if (input?.mode === "structured")
+        lines.push("", "Required:", "  --input PATH             YAML/JSON document; use - for stdin");
+    lines.push("", "Recovery:", `  ${String(explain.recovery ?? "Correct the input and retry; no state was changed.")}`, "", "Example:", `  ${String(explain.example ?? "")}`);
+    return lines.join("\n") + "\n";
+}

package/dist/state/write/fields.js

@@ -0,0 +1,61 @@
+import { ArtifactSchemaValidator } from "../../hooks/validateArtifact/index.js";
+function schemaEntry(schema, fieldPath) {
+    const leaf = fieldPath.split(".").at(-1);
+    for (const value of Object.values(schema)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        for (const entry of Object.values(value)) {
+            if (entry &&
+                typeof entry === "object" &&
+                !Array.isArray(entry) &&
+                String(entry.field ?? "") === leaf) {
+                return entry;
+            }
+        }
+    }
+    return null;
+}
+function valuesFromValidation(entry) {
+    if (!entry || !Array.isArray(entry.validation))
+        return undefined;
+    for (const raw of entry.validation) {
+        const match = /Must be one of:\s*(.+)$/i.exec(String(raw));
+        if (match)
+            return match[1]
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean);
+    }
+    return undefined;
+}
+export function projectedFields(spec, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(spec.artifact);
+    if (!schema)
+        return spec.fields;
+    return spec.fields.map((field) => {
+        const entry = schemaEntry(schema, field.field);
+        return {
+            ...field,
+            required: field.required ?? Boolean(entry?.required),
+            validValues: field.validValues ?? valuesFromValidation(entry),
+            description: field.description ?? (entry?.description ? String(entry.description) : undefined),
+        };
+    });
+}
+export function schemaBudget(artifact, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(artifact);
+    const result = {};
+    if (!schema ||
+        !schema.BUDGET ||
+        typeof schema.BUDGET !== "object" ||
+        Array.isArray(schema.BUDGET))
+        return result;
+    for (const entry of Object.values(schema.BUDGET)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const scope = String(entry.scope ?? "");
+        const key = scope.includes("full_file") ? "full_file_max_words" : "per_entry_max_words";
+        result[key] = typeof entry.max_words === "number" ? entry.max_words : null;
+    }
+    return result;
+}

package/dist/state/write/glossaryPublication.js

@@ -0,0 +1,263 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalTerminologyJson, validateTerminologyProposal, } from "../../audit/terminologyDrift.js";
+import { dumpYamlMapping, loadYamlMapping } from "../../core/yaml.js";
+import { loadArtifactRecord, resolveArtifactPath, } from "../../registries/artifactRegistry.js";
+import { GlossaryEntryBoundError, validateGlossaryEntry } from "../../registries/glossaryEntryContract.js";
+import { unicodeCaselessExact } from "../../registries/glossaryTermIdentity.js";
+import { containsGlossaryTerm } from "../../registries/glossaryTermOccurrence.js";
+import { assertValidatedProjectRoot } from "../projectRoot.js";
+import { reject } from "./errors.js";
+import { withStateMutation } from "./mutation.js";
+const REQUEST_VERSION = "agentera.glossaryPublicationRequest.v1";
+const DOCUMENT_VERSION = "agentera.projectGlossary.v1";
+const REQUEST_FIELDS = ["schema_version", "proposal", "confirmation"];
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactFields(value, allowed) {
+    return Object.keys(value).every((field) => allowed.includes(field));
+}
+function validTimestamp(value) {
+    if (typeof value !== "string")
+        return false;
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+    if (!match || Number.isNaN(Date.parse(value)))
+        return false;
+    const [, year, month, day, hour, minute, second, offsetHour = "00", offsetMinute = "00"] = match;
+    const calendar = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+    return calendar.getUTCFullYear() === Number(year)
+        && calendar.getUTCMonth() + 1 === Number(month)
+        && calendar.getUTCDate() === Number(day)
+        && Number(hour) <= 23
+        && Number(minute) <= 59
+        && Number(second) <= 59
+        && Number(offsetHour) <= 23
+        && Number(offsetMinute) <= 59;
+}
+function correction(message, classification = "schema_violation", recovery = "Rerun audit against current project files, obtain explicit user confirmation for the returned proposal_digest, and retry the same glossary publish command.") {
+    reject({
+        class: classification,
+        message,
+        recovery,
+        example: "agentera state glossary publish --input glossary-publication.yaml --format json",
+    });
+}
+function proposal(value) {
+    const validated = validateTerminologyProposal(value);
+    if (!validated.proposal) {
+        correction(`proposal is not canonical Audit output: ${validated.violations.join("; ")}`);
+    }
+    return validated.proposal;
+}
+function confirmation(value, digest) {
+    if (!mapping(value) || !exactFields(value, ["proposal_digest", "confirmed_by", "confirmed_at"])) {
+        correction("confirmation must contain only proposal_digest, confirmed_by, and confirmed_at");
+    }
+    if (value.confirmed_by !== "user") {
+        correction("confirmation.confirmed_by must be 'user'; generic consent or agent attribution is not approval");
+    }
+    if (!validTimestamp(value.confirmed_at)) {
+        correction("confirmation.confirmed_at must be a valid ISO 8601 timestamp with timezone");
+    }
+    if (value.proposal_digest !== digest) {
+        correction("confirmation.proposal_digest does not bind the submitted proposal");
+    }
+    return value;
+}
+function revalidateEvidence(root, proposalValue) {
+    const groups = [
+        { term: proposalValue.proposed_canonical_term, evidence: proposalValue.canonical_evidence },
+        ...proposalValue.variants,
+    ];
+    for (const group of groups) {
+        for (const record of group.evidence) {
+            assertValidatedProjectRoot(root);
+            const candidate = path.resolve(root.path, record.source_path);
+            let resolved;
+            try {
+                resolved = fs.realpathSync(candidate);
+            }
+            catch {
+                correction(`source evidence '${record.source_path}:${record.line}' is missing or unreadable`);
+            }
+            if (!resolved.startsWith(`${root.path}${path.sep}`) || !fs.statSync(resolved).isFile()) {
+                correction(`source evidence '${record.source_path}:${record.line}' escapes the project or is not a file`);
+            }
+            const canonicalPath = path.relative(root.path, resolved).split(path.sep).join(path.posix.sep);
+            if (canonicalPath !== record.source_path) {
+                correction(`source evidence '${record.source_path}:${record.line}' is not the canonical Audit-emitted project identity '${canonicalPath}:${record.line}'`);
+            }
+            const line = fs.readFileSync(resolved, "utf8").split(/\r?\n/)[record.line - 1];
+            const digest = line === undefined ? "" : crypto.createHash("sha256").update(line).digest("hex");
+            if (line === undefined || digest !== record.source_record_sha256 || !containsGlossaryTerm(line, group.term)) {
+                correction(`source evidence '${record.source_path}:${record.line}' is stale or no longer identifies '${group.term}'`);
+            }
+        }
+    }
+}
+function deriveEntry(proposalValue, confirmed) {
+    const source = proposalValue.canonical_evidence[0];
+    const date = confirmed.confirmed_at.slice(0, 10);
+    const entry = {
+        term: proposalValue.proposed_canonical_term,
+        meaning: proposalValue.concept,
+        confidence: proposalValue.confidence,
+        permanence: "stable",
+        temporal: { observed_at: date, last_confirmed_at: date },
+        provenance: {
+            kind: "project_file",
+            evidence: [{ source_path: source.source_path, source_record_sha256: source.source_record_sha256 }],
+        },
+    };
+    const violations = validateGlossaryEntry(entry, "project");
+    if (violations.length > 0)
+        correction(`derived project glossary entry is invalid: ${violations.join("; ")}`);
+    return entry;
+}
+function same(left, right) {
+    return canonicalTerminologyJson(left) === canonicalTerminologyJson(right);
+}
+function parseApproval(value, index) {
+    if (!mapping(value) || !exactFields(value, ["proposal_digest", "proposal", "confirmation"])) {
+        correction(`existing approvals[${index}] is malformed`, "conflict");
+    }
+    const proposed = proposal(value.proposal);
+    const confirmed = confirmation(value.confirmation, proposed.proposal_digest);
+    if (value.proposal_digest !== proposed.proposal_digest) {
+        correction(`existing approvals[${index}] has conflicting digest identity`, "conflict");
+    }
+    return {
+        approval: { proposal_digest: proposed.proposal_digest, proposal: proposed, confirmation: confirmed },
+        entry: deriveEntry(proposed, confirmed),
+    };
+}
+export function parseProjectGlossaryDocument(bytes, maxEntries = Number.POSITIVE_INFINITY) {
+    let value;
+    try {
+        value = loadYamlMapping(bytes);
+    }
+    catch (error) {
+        correction(`existing glossary document is malformed: ${error.message}`, "conflict");
+    }
+    if (!exactFields(value, ["schema_version", "approvals", "entries"]) || value.schema_version !== DOCUMENT_VERSION || !Array.isArray(value.approvals) || !Array.isArray(value.entries)) {
+        correction(`existing glossary document must use ${DOCUMENT_VERSION} with approvals and entries lists`, "conflict");
+    }
+    if (value.entries.length > maxEntries || value.approvals.length > maxEntries)
+        throw new GlossaryEntryBoundError("project glossary exceeds the consumer entry bound");
+    const approvals = value.approvals.map((item, index) => parseApproval(item, index));
+    const entries = value.entries;
+    if (entries.length !== approvals.length)
+        correction("existing glossary approvals and entries do not form complete publication pairs", "conflict");
+    const terminologyIdentities = [];
+    const digestIdentities = new Set();
+    for (const [index, item] of entries.entries()) {
+        if (!mapping(item))
+            correction(`existing entries[${index}] is malformed`, "conflict");
+        const violations = validateGlossaryEntry(item, "project");
+        if (violations.length > 0)
+            correction(`existing entries[${index}] is malformed: ${violations.join("; ")}`, "conflict");
+        if (!same(item, approvals[index].entry))
+            correction(`existing approval and entry at index ${index} do not match`, "conflict");
+        const canonical = String(item.term);
+        const digest = approvals[index].approval.proposal_digest;
+        if (digestIdentities.has(digest))
+            correction("existing glossary contains duplicate term or approval identity", "conflict");
+        digestIdentities.add(digest);
+        const terms = [canonical, ...approvals[index].approval.proposal.variants.map(({ term }) => term)];
+        for (const term of terms) {
+            const existing = terminologyIdentities.find((identity) => unicodeCaselessExact(identity.term, term));
+            if (existing) {
+                correction(`terminology identity collision for '${term}' between canonical sets '${existing.canonical}' and '${canonical}'`, "conflict", `Choose distinct canonical and variant terms for '${existing.canonical}' and '${canonical}', rerun audit, obtain confirmation for the corrected proposal, and retry the same glossary publish command.`);
+            }
+            terminologyIdentities.push({ term, canonical });
+        }
+    }
+    return {
+        schema_version: DOCUMENT_VERSION,
+        approvals: approvals.map(({ approval }) => approval),
+        entries: entries,
+    };
+}
+function validateCandidateBytes(bytes) {
+    return parseProjectGlossaryDocument(bytes);
+}
+export function loadProjectGlossaryDocument(projectRoot) {
+    const record = loadArtifactRecord("glossary");
+    if (!record)
+        correction("registered glossary artifact is unavailable");
+    const target = resolveArtifactPath(record, projectRoot);
+    if (!fs.existsSync(target))
+        return null;
+    return { path: target, document: parseProjectGlossaryDocument(fs.readFileSync(target, "utf8")) };
+}
+export function publishGlossary(req, root, options = {}) {
+    if (!req.input || !exactFields(req.input, REQUEST_FIELDS) || req.input.schema_version !== REQUEST_VERSION) {
+        correction(`publication request must use ${REQUEST_VERSION} and contain only proposal and confirmation`);
+    }
+    const proposed = proposal(req.input.proposal);
+    const confirmed = confirmation(req.input.confirmation, proposed.proposal_digest);
+    const entry = deriveEntry(proposed, confirmed);
+    const approval = {
+        proposal_digest: proposed.proposal_digest,
+        proposal: proposed,
+        confirmation: confirmed,
+    };
+    const record = loadArtifactRecord("glossary");
+    if (!record)
+        correction("registered glossary artifact is unavailable");
+    return withStateMutation(root.path, (transaction) => {
+        assertValidatedProjectRoot(root);
+        const target = resolveArtifactPath(record, root.path, { strictWrite: true });
+        const relativePath = path.relative(root.path, target).split(path.sep).join("/");
+        revalidateEvidence(root, proposed);
+        const previousBytes = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+        const current = previousBytes
+            ? parseProjectGlossaryDocument(previousBytes)
+            : { schema_version: DOCUMENT_VERSION, approvals: [], entries: [] };
+        const approvalIndex = current.approvals.findIndex((item) => item.proposal_digest === proposed.proposal_digest);
+        const termIndex = current.entries.findIndex((item) => unicodeCaselessExact(String(item.term), proposed.proposed_canonical_term));
+        if (approvalIndex >= 0 || termIndex >= 0) {
+            if (approvalIndex === termIndex && approvalIndex >= 0 && same(current.approvals[approvalIndex], approval) && same(current.entries[termIndex], entry)) {
+                return {
+                    schemaVersion: "agentera.stateWrite.v1",
+                    status: "pass",
+                    command: "state glossary publish",
+                    artifact: "glossary",
+                    path: relativePath,
+                    operation: { dry_run: req.dryRun, changed: false, idempotent_replay: true },
+                    candidate: current,
+                };
+            }
+            correction(`confirmed term '${proposed.proposed_canonical_term}' conflicts with existing approval or entry state`, "conflict");
+        }
+        const candidate = {
+            schema_version: DOCUMENT_VERSION,
+            approvals: [...current.approvals, approval],
+            entries: [...current.entries, entry],
+        };
+        const bytes = dumpYamlMapping(candidate);
+        validateCandidateBytes(bytes);
+        if (!req.dryRun) {
+            const stage = transaction.stageProjection(target, bytes);
+            try {
+                transaction.syncStaged(stage);
+                assertValidatedProjectRoot(root);
+                transaction.publishProjection(stage, target, previousBytes);
+            }
+            finally {
+                transaction.removeStage(stage);
+            }
+        }
+        return {
+            schemaVersion: "agentera.stateWrite.v1",
+            status: "pass",
+            command: "state glossary publish",
+            artifact: "glossary",
+            path: relativePath,
+            operation: { dry_run: req.dryRun, changed: true, idempotent_replay: false },
+            candidate,
+        };
+    }, options, root);
+}