agentera 3.0.0-dev.6 → 3.0.0-dev.69

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);
+}

package/dist/state/write/grammar.js

@@ -0,0 +1,285 @@
+import crypto from "node:crypto";
+import { projectRuntimeOperationExamples, projectRuntimeOperationRecovery, } from "../../core/developmentInvocation.js";
+import { resolveSourceRoot } from "../../core/sourceRoot.js";
+import { loadStateStorageAuthority } from "../stateStorageAuthority.js";
+import { runtimeOperationSpec, runtimeOperationSpecs } from "./runtimeOperations.js";
+export const MUTATION_CLASSES = [
+    "record_payload",
+    "simple_transition",
+    "batch_transaction",
+];
+export const MUTATION_INPUT_MODES = [
+    "none",
+    "structured",
+    "flags_until_conversion",
+];
+let cache;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`invalid mutation grammar: ${path} must be a non-empty string`);
+    return value;
+}
+function strings(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`invalid mutation grammar: ${path} must be a string list`);
+    return [...value];
+}
+function clonePlain(value) {
+    if (Array.isArray(value))
+        return value.map(clonePlain);
+    if (mapping(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePlain(item)]));
+    return value;
+}
+function fields(value, path) {
+    if (!Array.isArray(value))
+        throw new Error(`invalid mutation grammar: ${path} must be a list`);
+    const seenFlags = new Set();
+    const seenFields = new Set();
+    return value.map((raw, index) => {
+        const fieldPath = `${path}[${index}]`;
+        if (!mapping(raw))
+            throw new Error(`invalid mutation grammar: ${fieldPath} must be a mapping`);
+        const flag = requiredString(raw.flag, `${fieldPath}.flag`);
+        const field = requiredString(raw.field, `${fieldPath}.field`);
+        const kind = requiredString(raw.kind, `${fieldPath}.kind`);
+        if (!["string", "boolean", "integer", "string_list", "date", "datetime"].includes(kind))
+            throw new Error(`invalid mutation grammar: ${fieldPath}.kind '${kind}' is unsupported`);
+        if (seenFlags.has(flag) || seenFields.has(field))
+            throw new Error(`invalid mutation grammar: duplicate field ${flag}/${field} in ${path}`);
+        seenFlags.add(flag);
+        seenFields.add(field);
+        const validValues = raw.valid_values === undefined ? undefined : strings(raw.valid_values, `${fieldPath}.valid_values`);
+        const validValuesSource = raw.valid_values_source === undefined ? undefined : requiredString(raw.valid_values_source, `${fieldPath}.valid_values_source`);
+        if (validValues && validValuesSource)
+            throw new Error(`invalid mutation grammar: ${fieldPath} cannot declare both valid_values and valid_values_source`);
+        return {
+            flag,
+            field,
+            kind,
+            required: raw.required === true,
+            ...(raw.repeatable === true ? { repeatable: true } : {}),
+            ...(validValues ? { validValues } : {}),
+            ...(validValuesSource ? { validValuesSource } : {}),
+            ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+        };
+    });
+}
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (mapping(value)) {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return crypto.createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function parseOperation(raw, index) {
+    const p = `mutation_grammar.operations[${index}]`;
+    if (!mapping(raw))
+        throw new Error(`invalid mutation grammar: ${p} must be a mapping`);
+    const artifact = requiredString(raw.artifact, `${p}.artifact`);
+    const verb = requiredString(raw.verb, `${p}.verb`);
+    const runtime = runtimeOperationSpec(artifact, verb);
+    if (!runtime)
+        throw new Error(`invalid mutation grammar: ${p} operation '${artifact}.${verb}' is not code-owned`);
+    const mutationClass = requiredString(raw.class, `${p}.class`);
+    if (!MUTATION_CLASSES.includes(mutationClass))
+        throw new Error(`invalid mutation grammar: ${p}.class '${mutationClass}' is unsupported`);
+    if (!mapping(raw.input))
+        throw new Error(`invalid mutation grammar: ${p}.input must be a mapping`);
+    const inputMode = requiredString(raw.input.mode, `${p}.input.mode`);
+    if (!MUTATION_INPUT_MODES.includes(inputMode))
+        throw new Error(`invalid mutation grammar: ${p}.input.mode '${inputMode}' is unsupported`);
+    const input = {
+        mode: inputMode,
+        ...(raw.input.root === undefined ? {} : { root: requiredString(raw.input.root, `${p}.input.root`) }),
+        ...(raw.input.optional === true ? { optional: true } : {}),
+        sources: strings(raw.input.sources, `${p}.input.sources`),
+        ...(raw.input.structured_sources === undefined
+            ? (inputMode === "structured" ? { structuredSources: strings(raw.input.sources, `${p}.input.sources`) } : {})
+            : { structuredSources: strings(raw.input.structured_sources, `${p}.input.structured_sources`) }),
+        cliOwnedFields: strings(raw.input.cli_owned_fields, `${p}.input.cli_owned_fields`),
+    };
+    if (raw.input.optional !== undefined && raw.input.optional !== true)
+        throw new Error(`invalid mutation grammar: ${p}.input.optional must be true when present`);
+    if (inputMode === "structured" && (!input.root || input.sources.length === 0))
+        throw new Error(`invalid mutation grammar: ${p} structured input needs a root and source`);
+    if (inputMode === "none" && (input.sources.length > 0 || input.root !== undefined))
+        throw new Error(`invalid mutation grammar: ${p} none input cannot declare sources or a root`);
+    const operation = {
+        artifact,
+        verb,
+        mutationClass,
+        selectors: strings(raw.selectors, `${p}.selectors`),
+        preconditions: strings(raw.preconditions, `${p}.preconditions`),
+        ownedFields: strings(raw.owned_fields, `${p}.owned_fields`),
+        input,
+        recovery: projectRuntimeOperationRecovery(raw.recovery, artifact, verb),
+        examples: projectRuntimeOperationExamples(raw.examples, artifact, verb),
+        bounds: mapping(raw.bounds) ? clonePlain(raw.bounds) : (() => { throw new Error(`invalid mutation grammar: ${p}.bounds must be a mapping`); })(),
+        fields: fields(raw.fields, `${p}.fields`),
+        allowForce: raw.allow_force === true,
+        compacts: raw.compacts === true,
+    };
+    if (operation.examples.length === 0)
+        throw new Error(`invalid mutation grammar: ${p}.examples must not be empty`);
+    const selectors = new Set(operation.selectors);
+    for (const selector of selectors) {
+        if (!selector.startsWith("--"))
+            throw new Error(`invalid mutation grammar: ${p}.selectors must contain flags`);
+    }
+    return operation;
+}
+function runtimeFieldProjection(field) {
+    return {
+        flag: field.flag,
+        field: field.field,
+        kind: field.kind,
+        required: field.required === true,
+        repeatable: field.repeatable === true,
+        ...(field.validValuesSource
+            ? { valid_values_source: field.validValuesSource }
+            : field.validValues
+                ? { valid_values: field.validValues }
+                : {}),
+    };
+}
+function declaredFieldProjection(field) {
+    return runtimeFieldProjection(field);
+}
+function operationParityProjection(operation) {
+    return {
+        artifact: operation.artifact,
+        verb: operation.verb,
+        selectors: operation.selectors,
+        owned_fields: operation.ownedFields,
+        input: {
+            mode: operation.input.mode,
+            ...(operation.input.root ? { root: operation.input.root } : {}),
+            ...(operation.input.optional ? { optional: true } : {}),
+            sources: operation.input.sources,
+            structured_sources: operation.input.structuredSources ?? [],
+            cli_owned_fields: operation.input.cliOwnedFields,
+        },
+        fields: operation.fields.map(declaredFieldProjection),
+        recovery: operation.recovery,
+        examples: operation.examples,
+        projection: { format_values: runtimeOperationSpec(operation.artifact, operation.verb)?.projection.formatValues ?? [] },
+        allow_force: operation.allowForce,
+        compacts: operation.compacts,
+        bounds: operation.input.mode === "structured"
+            ? { max_input_utf8_bytes: operation.bounds.max_input_utf8_bytes }
+            : { max_input_utf8_bytes: 0 },
+    };
+}
+function runtimeParityProjection(operation) {
+    return {
+        artifact: operation.artifact,
+        verb: operation.verb,
+        selectors: operation.selectors,
+        owned_fields: operation.ownedFields,
+        input: {
+            mode: operation.inputMode,
+            ...(operation.inputRoot ? { root: operation.inputRoot } : {}),
+            ...(operation.inputOptional ? { optional: true } : {}),
+            sources: operation.inputSources,
+            structured_sources: operation.structuredInputSources,
+            cli_owned_fields: operation.cliOwnedFields,
+        },
+        fields: operation.fields.map(runtimeFieldProjection),
+        recovery: operation.projection.recovery.runtime,
+        examples: operation.projection.examples.map(({ runtime }) => runtime),
+        projection: { format_values: operation.projection.formatValues },
+        allow_force: operation.allowForce,
+        compacts: operation.compacts,
+        bounds: { max_input_utf8_bytes: operation.inputMaxBytes },
+    };
+}
+export function validateMutationGrammarParity(operations, authorityPath = "references/artifacts/state-storage-authority.yaml") {
+    const runtime = runtimeOperationSpecs();
+    const runtimeByKey = new Map(runtime.map((operation) => [`${operation.artifact}.${operation.verb}`, operation]));
+    const declaredByKey = new Map(operations.map((operation) => [`${operation.artifact}.${operation.verb}`, operation]));
+    const keys = [...new Set([...runtimeByKey.keys(), ...declaredByKey.keys()])].sort();
+    const mismatches = [];
+    for (const key of keys) {
+        const code = runtimeByKey.get(key);
+        const declared = declaredByKey.get(key);
+        if (!code || !declared) {
+            mismatches.push(`${key}: operation is ${code ? "missing from discovery" : "not code-owned"}`);
+            continue;
+        }
+        const expected = canonicalJson(runtimeParityProjection(code));
+        const actual = canonicalJson(operationParityProjection(declared));
+        if (expected !== actual)
+            mismatches.push(`${key}: discovery does not match code-owned runtime grammar`);
+    }
+    if (mismatches.length) {
+        throw new Error(`mutation grammar parity failure for '${authorityPath}': ${mismatches.join("; ")}`);
+    }
+}
+function parseGrammar(document, authority) {
+    const raw = document.mutation_grammar;
+    if (!mapping(raw))
+        throw new Error(`invalid mutation grammar in '${authority}': mutation_grammar is missing`);
+    const schemaVersion = requiredString(raw.schema_version, "mutation_grammar.schema_version");
+    if (schemaVersion !== "agentera.stateMutationGrammar.v1")
+        throw new Error(`invalid mutation grammar: unsupported schema version '${schemaVersion}'`);
+    const operationClasses = strings(raw.operation_classes, "mutation_grammar.operation_classes");
+    if (operationClasses.some((value) => !MUTATION_CLASSES.includes(value)))
+        throw new Error("invalid mutation grammar: operation_classes contains an unsupported class");
+    if (!mapping(raw.structured_input))
+        throw new Error("invalid mutation grammar: structured_input must be a mapping");
+    if (!Array.isArray(raw.operations))
+        throw new Error("invalid mutation grammar: operations must be a list");
+    const operations = raw.operations.map(parseOperation);
+    const seen = new Set();
+    for (const operation of operations) {
+        const key = `${operation.artifact}.${operation.verb}`;
+        if (seen.has(key))
+            throw new Error(`invalid mutation grammar: duplicate public mutation '${key}'`);
+        seen.add(key);
+    }
+    validateMutationGrammarParity(operations, authority);
+    const contract = {
+        schema_version: schemaVersion,
+        operation_classes: operationClasses,
+        structured_input: raw.structured_input,
+        operations,
+    };
+    return {
+        schemaVersion,
+        authority: "references/artifacts/state-storage-authority.yaml",
+        operationClasses,
+        structuredInput: clonePlain(raw.structured_input),
+        operations,
+        contractDigest: digest(contract),
+    };
+}
+export function loadMutationGrammar(sourceRoot = resolveSourceRoot()) {
+    const authority = loadStateStorageAuthority(sourceRoot);
+    if (cache?.revision === authority.revision)
+        return cache.grammar;
+    const grammar = parseGrammar(authority.document, authority.authorityPath);
+    cache = { revision: authority.revision, grammar };
+    return grammar;
+}
+export function mutationOperationsForArtifact(artifact, sourceRoot = resolveSourceRoot()) {
+    return loadMutationGrammar(sourceRoot).operations.filter((operation) => operation.artifact === artifact);
+}
+export function mutationGrammarPayload(sourceRoot = resolveSourceRoot()) {
+    const grammar = loadMutationGrammar(sourceRoot);
+    return {
+        schemaVersion: grammar.schemaVersion,
+        authority: grammar.authority,
+        contract_digest: grammar.contractDigest,
+        operation_classes: grammar.operationClasses,
+        structured_input: grammar.structuredInput,
+        operations: grammar.operations,
+    };
+}

package/dist/state/write/helpers.js

@@ -0,0 +1,29 @@
+import { reject } from "./errors.js";
+export function schemaViolation(violations) {
+    reject({ class: "schema_violation", message: violations[0], violations });
+}
+export function findByNumber(entries, number) {
+    return entries.find((entry) => Number(entry.number) === number);
+}
+/** Coerce an unknown value into a plain mapping, returning `{}` for non-objects. */
+export function mapping(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Return the object-valued elements of `doc[key]`, dropping non-mapping entries. */
+export function array(doc, key) {
+    return Array.isArray(doc[key])
+        ? doc[key].filter((v) => Boolean(v && typeof v === "object" && !Array.isArray(v)))
+        : [];
+}
+/** Traverse a dotted field path into a nested mapping, returning `undefined` on miss. */
+export function mappingPath(entry, field) {
+    let value = entry;
+    for (const part of field.split(".")) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}

package/dist/state/write/index.js

@@ -0,0 +1,12 @@
+export * from "./operations.js";
+export * from "./fields.js";
+export * from "./input.js";
+export * from "./assign.js";
+export * from "./explain.js";
+export * from "./lock.js";
+export * from "./mutation.js";
+export * from "./transaction.js";
+export * from "./validate.js";
+export * from "./serialize.js";
+export * from "./errors.js";
+export * from "./glossaryPublication.js";