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

package/dist/state/write/grammar.js

@@ -0,0 +1,280 @@
+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`) }),
+        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 (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 } : {}),
+            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 } : {}),
+            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";