agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/state/write/input.js

@@ -0,0 +1,367 @@
+import fs from "node:fs";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { glossaryCaveatContract } from "../../registries/glossaryCaveatContract.js";
+const caveat = glossaryCaveatContract();
+const field = (path, type, description, options = { required: false, update: "replace" }) => ({ path, type, description, ...options });
+const PROGRESS_INPUT_SCHEMA = {
+    root: "one progress cycle record",
+    fields: [
+        field("timestamp", "datetime", "Writer-defaulted cycle timestamp.", { required: false, update: "defaulted" }),
+        field("type", "string", "Conventional change type.", { required: true, enum: ["feat", "fix", "docs", "refactor", "chore", "test"], update: "replace" }),
+        field("phase", "string", "Lifecycle phase.", { required: true, enum: ["envision", "deliberate", "plan", "build", "audit"], update: "replace" }),
+        field("what", "string", "Non-empty summary of the cycle.", { required: true, update: "replace" }),
+        field("inspiration", "string", "Optional inspiration evidence.", { required: false, update: "replace" }),
+        field("discovered", "string", "Optional discovery evidence.", { required: false, update: "replace" }),
+        field("verified", "string", "Optional verification evidence.", { required: false, update: "replace" }),
+        field("next", "string", "Optional next-step evidence.", { required: false, update: "replace" }),
+        field("context", "mapping", "Required context mapping.", { required: true, shape: "intent:string, constraints?:string, unknowns?:string, scope?:string", update: "replace" }),
+        field("context.intent", "string", "Required cycle intent.", { required: true, update: "replace" }),
+        field("context.constraints", "string", "Optional constraints.", { required: false, update: "replace" }),
+        field("context.unknowns", "string", "Optional unknowns.", { required: false, update: "replace" }),
+        field("context.scope", "string", "Optional scope.", { required: false, update: "replace" }),
+        field("glossary_caveat", "mapping", "Optional bounded glossary-caveat lifecycle envelope.", { required: false, shape: "event, reason, ownership_state, caveat_id?, transition_id?", update: "replace" }),
+        field("glossary_caveat.event", "string", "Caveat lifecycle event.", { required: false, enum: caveat.events, update: "replace" }),
+        field("glossary_caveat.reason", "string", "Authority-declared caveat reason.", { required: false, enum: caveat.reasons, update: "replace" }),
+        field("glossary_caveat.ownership_state", "string", "Authority-declared ownership state.", { required: false, enum: caveat.ownershipStates, update: "replace" }),
+        field("glossary_caveat.caveat_id", "string", "Existing opaque caveat selector for terminal events.", { required: false, update: "replace" }),
+        field("glossary_caveat.transition_id", "string", "Existing opaque successor selector for supersession.", { required: false, update: "replace" }),
+    ],
+    semantics: {
+        mode: "append_record",
+        omitted_fields: "not present in the canonical record except writer-defaulted timestamp",
+        writer_metadata: "id, artifact, and publication_order are assigned by the writer and excluded from logical replay comparison",
+        glossary_caveat: "current events deduplicate by the existing caveat lifecycle contract; resolved and superseded events remain distinct",
+    },
+    ownedFields: ["id", "artifact", "publication_order"],
+    immutableFields: [],
+    bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 },
+    examples: ["agentera state progress append --input progress.yaml --format json"],
+};
+const DECISION_APPEND_INPUT_SCHEMA = {
+    root: "one decision record",
+    fields: [
+        field("date", "date", "Writer-defaulted decision date.", { required: false, update: "defaulted" }),
+        field("question", "string", "Question under deliberation.", { required: true, update: "replace" }),
+        field("context", "string", "Decision context.", { required: true, update: "replace" }),
+        field("alternatives", "mapping", "Alternatives mapping or ordered canonical alternative list.", { required: true, acceptedForms: ["mapping", "ordered_alternative_list"], shape: "chosen:string, rejected?:string[]", update: "replace" }),
+        field("alternatives.chosen", "string", "Exactly one chosen alternative.", { required: true, update: "replace" }),
+        field("alternatives.rejected", "list", "Optional rejected alternatives in caller order.", { required: false, itemType: "string", update: "replace" }),
+        field("choice", "string", "Selected choice.", { required: true, update: "replace" }),
+        field("reasoning", "string", "Decision reasoning.", { required: true, update: "replace" }),
+        field("confidence", "string", "Current confidence vocabulary.", { required: true, enum: ["firm", "provisional", "exploratory"], update: "replace" }),
+        field("feeds_into", "string", "Optional downstream relationship.", { required: false, update: "replace" }),
+    ],
+    semantics: {
+        mode: "append_record",
+        alternatives: "ordered list ordering is significant; mapping input is normalized to the canonical ordered list",
+        writer_metadata: "id and artifact are assigned by the writer and excluded from logical replay comparison",
+    },
+    ownedFields: ["id", "artifact"],
+    immutableFields: ["number", "satisfaction"],
+    bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 },
+    examples: ["agentera state decisions append --input decision.yaml --format json"],
+};
+const DECISION_AMEND_INPUT_SCHEMA = {
+    root: "amendable decision content",
+    fields: DECISION_APPEND_INPUT_SCHEMA.fields
+        .filter((entry) => entry.path !== "date")
+        .map((entry) => ({ ...entry, required: entry.path === "alternatives.chosen" ? false : false, update: entry.path === "alternatives.rejected" ? "append_unique" : "patch" })),
+    semantics: {
+        mode: "patch",
+        omitted_fields: "preserve the effective record",
+        alternatives: "alternatives.chosen replaces the chosen value; alternatives.rejected appends unique rejected values in input order",
+        immutable_fields: "date, number, satisfaction, id, artifact, and base_sha256 are not amendment content",
+    },
+    ownedFields: ["id", "artifact", "base_sha256"],
+    immutableFields: ["date", "number", "satisfaction"],
+    bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 },
+    examples: ["agentera state decisions amend --id qjtrmnpvka --base-sha256 HASH --input amendment.yaml --format json"],
+};
+const PLAN_TASK_APPEND_INPUT_SCHEMA = {
+    root: "one plan task record",
+    fields: [
+        field("name", "string", "Short task name.", { required: true, update: "replace" }),
+        field("depends_on", "list", "Bare ten-letter task IDs in the same plan; use an empty list for a root task.", { required: true, itemType: "string", update: "replace" }),
+        field("acceptance", "list", "Task acceptance criteria.", { required: true, itemType: "string", update: "replace" }),
+        field("evidence", "string", "Optional task evidence as a string or list of strings.", { required: false, acceptedForms: ["string", "list"], update: "replace" }),
+        field("blocked_reason", "string", "Optional task blocker explanation.", { required: false, update: "replace" }),
+    ],
+    semantics: {
+        mode: "append_record",
+        omitted_fields: "only writer-defaulted status is omitted; plan, id, and artifact are assigned by the writer",
+        identities: "depends_on contains bare ten-letter task IDs and every target must belong to the selected plan",
+        lifecycle: "status, supersession, evaluation, and plan lifecycle are separate flag-only transitions",
+    },
+    ownedFields: ["id", "artifact", "plan", "status", "superseded_by", "superseded_reason", "evaluation", "header.status", "header.id", "previous_plan_archived", "task_ids"],
+    immutableFields: [],
+    bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 },
+    examples: ["agentera state plan append --plan qjtrmnpvka --input task.yaml --format json"],
+};
+const PLAN_TASK_UPDATE_INPUT_SCHEMA = {
+    root: "plan task patch",
+    fields: [
+        field("name", "string", "Replacement task name.", { required: false, update: "patch" }),
+        field("depends_on", "list", "Replacement list of bare ten-letter task IDs in the same plan; null clears to an empty list.", { required: false, itemType: "string", update: "patch" }),
+        field("acceptance", "list", "Replacement task acceptance criteria; null clears to an empty list.", { required: false, itemType: "string", update: "patch" }),
+        field("evidence", "string", "Replacement task evidence as a string or list of strings; null clears it.", { required: false, acceptedForms: ["string", "list"], update: "patch" }),
+        field("blocked_reason", "string", "Replacement blocker explanation; null clears it.", { required: false, update: "patch" }),
+        field("surprise", "string", "Plan-level surprise; it is not written to the task entity.", { required: false, update: "patch" }),
+    ],
+    semantics: {
+        mode: "patch",
+        omitted_fields: "preserve the effective task record",
+        clearable_fields: ["depends_on", "acceptance", "evidence", "blocked_reason"],
+        surprise: "surprise remains plan-level content and cannot be combined with task-field changes",
+        identities: "depends_on contains bare ten-letter task IDs and every target must belong to the selected plan",
+        lifecycle: "status, supersession, evaluation, and plan lifecycle are separate flag-only transitions",
+    },
+    ownedFields: ["id", "artifact", "plan", "status", "superseded_by", "superseded_reason", "evaluation", "header.status", "header.id", "previous_plan_archived", "task_ids"],
+    immutableFields: ["status", "superseded_by", "superseded_reason", "evaluation", "plan"],
+    bounds: { max_input_utf8_bytes: 32768, max_collection_items: 1 },
+    examples: ["agentera state plan update --id qjtrmnpvka --plan abcdefghij --input task-patch.yaml --format json"],
+};
+const STRUCTURED_INPUT_SCHEMAS = {
+    "progress.append": PROGRESS_INPUT_SCHEMA,
+    "decisions.append": DECISION_APPEND_INPUT_SCHEMA,
+    "decisions.amend": DECISION_AMEND_INPUT_SCHEMA,
+    "plan.append": PLAN_TASK_APPEND_INPUT_SCHEMA,
+    "plan.update": PLAN_TASK_UPDATE_INPUT_SCHEMA,
+};
+export function structuredInputDescriptor(artifact, verb) {
+    return STRUCTURED_INPUT_SCHEMAS[`${artifact}.${verb}`] ?? null;
+}
+export function structuredInputSchemaProjection(schema) {
+    return {
+        root: schema.root,
+        fields: schema.fields.map((entry) => ({
+            path: entry.path,
+            type: entry.type,
+            required: entry.required,
+            ...(entry.enum ? { enum: [...entry.enum] } : {}),
+            ...(entry.itemType ? { item_type: entry.itemType } : {}),
+            ...(entry.acceptedForms ? { accepted_forms: [...entry.acceptedForms] } : {}),
+            ...(entry.shape ? { shape: entry.shape } : {}),
+            update: entry.update,
+            description: entry.description,
+        })),
+        semantics: structuredClone(schema.semantics),
+        owned_fields: [...schema.ownedFields],
+        immutable_fields: [...schema.immutableFields],
+        bounds: structuredClone(schema.bounds),
+        examples: [...schema.examples],
+    };
+}
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requiredString(value, field, violations) {
+    if (typeof value !== "string" || value.length === 0)
+        violations.push(`${field} must be a non-empty string`);
+}
+function optionalString(value, field, violations) {
+    if (value !== undefined && (typeof value !== "string" || value.length === 0))
+        violations.push(`${field} must be a non-empty string when present`);
+}
+function unknownFields(input, allowed, violations) {
+    for (const field of Object.keys(input))
+        if (!allowed.has(field))
+            violations.push(`input field '${field}' is not accepted for this mutation`);
+}
+function descriptorsFor(schema, prefix) {
+    return schema.fields.filter((entry) => entry.path === prefix || entry.path.startsWith(`${prefix}.`));
+}
+function descriptor(schema, path) {
+    const found = schema.fields.find((entry) => entry.path === path);
+    if (!found)
+        throw new Error(`structured input schema is missing '${path}'`);
+    return found;
+}
+function topLevelFields(schema) {
+    return new Set(schema.fields.map((entry) => entry.path.split(".")[0]));
+}
+function enumValues(schema, path) {
+    return descriptor(schema, path).enum ?? [];
+}
+function alternativesViolations(value, violations, requireChosen, schema) {
+    if (Array.isArray(value)) {
+        const chosen = value.filter((entry) => mapping(entry) && entry.status === "chosen");
+        if (chosen.length !== 1 || value.some((entry) => !mapping(entry) || typeof entry.name !== "string" || entry.name.length === 0 || !["chosen", "rejected"].includes(String(entry.status)))) {
+            violations.push("alternatives must be a mapping or a list with exactly one named chosen alternative");
+        }
+        if (!requireChosen && value.length === 0)
+            violations.push("alternatives must not be empty");
+        return;
+    }
+    if (!mapping(value)) {
+        violations.push("alternatives must be a mapping with chosen and rejected fields");
+        return;
+    }
+    unknownFields(value, new Set(descriptorsFor(schema, "alternatives").map((entry) => entry.path.split(".").at(-1))), violations);
+    if (requireChosen)
+        requiredString(value.chosen, "alternatives.chosen", violations);
+    else if (value.chosen !== undefined)
+        optionalString(value.chosen, "alternatives.chosen", violations);
+    if (value.rejected !== undefined && (!Array.isArray(value.rejected) || value.rejected.some((entry) => typeof entry !== "string" || entry.length === 0)))
+        violations.push("alternatives.rejected must be a list of non-empty strings when present");
+}
+function progressInputViolations(input) {
+    const violations = [];
+    const schema = structuredInputDescriptor("progress", "append");
+    unknownFields(input, topLevelFields(schema), violations);
+    requiredString(input.type, "type", violations);
+    requiredString(input.phase, "phase", violations);
+    requiredString(input.what, "what", violations);
+    if (typeof input.type === "string" && !enumValues(schema, "type").includes(input.type))
+        violations.push(`type must be one of ${enumValues(schema, "type").join(", ")}`);
+    if (typeof input.phase === "string" && !enumValues(schema, "phase").includes(input.phase))
+        violations.push(`phase must be one of ${enumValues(schema, "phase").join(", ")}`);
+    if (input.timestamp !== undefined && (typeof input.timestamp !== "string" || !/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(input.timestamp)))
+        violations.push("timestamp must use YYYY-MM-DD HH:MM when present");
+    for (const field of ["inspiration", "discovered", "verified", "next"])
+        optionalString(input[field], field, violations);
+    if (!mapping(input.context))
+        violations.push("context must be a mapping with intent");
+    else {
+        unknownFields(input.context, new Set(descriptorsFor(schema, "context").map((entry) => entry.path.split(".").at(-1))), violations);
+        requiredString(input.context.intent, "context.intent", violations);
+        for (const field of ["constraints", "unknowns", "scope"])
+            optionalString(input.context[field], `context.${field}`, violations);
+    }
+    if (input.glossary_caveat !== undefined) {
+        if (!mapping(input.glossary_caveat))
+            violations.push("glossary_caveat must be a mapping");
+        else {
+            unknownFields(input.glossary_caveat, new Set(descriptorsFor(schema, "glossary_caveat").map((entry) => entry.path.split(".").at(-1))), violations);
+            for (const field of descriptorsFor(schema, "glossary_caveat").map((entry) => entry.path.split(".").at(-1)).filter((entry) => entry !== "glossary_caveat"))
+                if (input.glossary_caveat[field] !== undefined && input.glossary_caveat[field] !== null)
+                    optionalString(input.glossary_caveat[field], `glossary_caveat.${field}`, violations);
+        }
+    }
+    return violations;
+}
+function decisionInputViolations(input, verb) {
+    const violations = [];
+    const schema = structuredInputDescriptor("decisions", verb);
+    unknownFields(input, topLevelFields(schema), violations);
+    if (verb === "append") {
+        requiredString(input.question, "question", violations);
+        requiredString(input.context, "context", violations);
+        requiredString(input.choice, "choice", violations);
+        requiredString(input.reasoning, "reasoning", violations);
+        requiredString(input.confidence, "confidence", violations);
+        if (input.date !== undefined && (typeof input.date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(input.date)))
+            violations.push("date must use YYYY-MM-DD when present");
+    }
+    else {
+        if (Object.keys(input).length === 0)
+            violations.push("decision amendment requires at least one content field");
+        for (const field of ["question", "context", "choice", "reasoning", "confidence", "feeds_into"])
+            optionalString(input[field], field, violations);
+    }
+    if (input.confidence !== undefined && (typeof input.confidence !== "string" || !enumValues(schema, "confidence").includes(input.confidence)))
+        violations.push(`confidence must be one of ${enumValues(schema, "confidence").join(", ")}`);
+    if (input.alternatives !== undefined)
+        alternativesViolations(input.alternatives, violations, verb === "append", schema);
+    else if (verb === "append")
+        violations.push("alternatives is required");
+    return violations;
+}
+const BARE_ID = /^[a-z]{10}$/;
+function stringList(value, field, violations, options) {
+    if (value === undefined) {
+        if (options.required)
+            violations.push(`${field} is required`);
+        return;
+    }
+    if (value === null && !options.required)
+        return;
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        violations.push(`${field} must be a list of strings${options.ids ? " containing bare ten-letter IDs" : ""}`);
+        return;
+    }
+    if (options.ids && value.some((entry) => !BARE_ID.test(entry)))
+        violations.push(`${field} must contain only bare ten-letter task IDs`);
+}
+function planTaskInputViolations(input, verb) {
+    const schema = structuredInputDescriptor("plan", verb);
+    const violations = [];
+    unknownFields(input, topLevelFields(schema), violations);
+    if (verb === "append") {
+        requiredString(input.name, "name", violations);
+        stringList(input.depends_on, "depends_on", violations, { required: true, ids: true });
+        stringList(input.acceptance, "acceptance", violations, { required: true });
+    }
+    else if (Object.keys(input).length === 0) {
+        violations.push("plan task patch requires at least one content field");
+    }
+    if (input.name !== undefined && (typeof input.name !== "string" || input.name.length === 0))
+        violations.push("name must be a non-empty string when present");
+    stringList(input.depends_on, "depends_on", violations, { required: false, ids: true });
+    stringList(input.acceptance, "acceptance", violations, { required: false });
+    if (input.evidence !== undefined && input.evidence !== null && typeof input.evidence !== "string" && (!Array.isArray(input.evidence) || input.evidence.some((entry) => typeof entry !== "string")))
+        violations.push("evidence must be a string, list of strings, or null when present");
+    if (input.blocked_reason !== undefined && input.blocked_reason !== null && typeof input.blocked_reason !== "string")
+        violations.push("blocked_reason must be a string or null when present");
+    if (verb === "append" && (input.evidence === null || input.blocked_reason === null))
+        violations.push("null clears are available only for plan task updates");
+    if (verb === "update" && input.surprise !== undefined && (typeof input.surprise !== "string" || input.surprise.length === 0))
+        violations.push("surprise must be a non-empty string when present");
+    if (verb === "append" && input.surprise !== undefined)
+        violations.push("surprise is plan-level content and is not accepted when appending a task");
+    return violations;
+}
+export function structuredRecordInputViolations(artifact, verb, input) {
+    if (!input || (artifact !== "progress" && artifact !== "decisions" && artifact !== "plan"))
+        return [];
+    if (artifact === "progress" && verb === "append")
+        return progressInputViolations(input);
+    if (artifact === "decisions" && (verb === "append" || verb === "amend"))
+        return decisionInputViolations(input, verb);
+    if (artifact === "plan" && (verb === "append" || verb === "update"))
+        return planTaskInputViolations(input, verb);
+    return [];
+}
+export function normalizeDecisionRecordInput(input) {
+    const result = structuredClone(input);
+    if (!Array.isArray(result.alternatives))
+        return result;
+    const alternatives = result.alternatives;
+    const chosen = alternatives.find((entry) => mapping(entry) && entry.status === "chosen");
+    result.alternatives = {
+        chosen: chosen?.name,
+        rejected: alternatives
+            .filter((entry) => mapping(entry) && entry.status === "rejected")
+            .map((entry) => entry.name),
+    };
+    return result;
+}
+export function loadStructuredInput(source, readStdin, maxBytes) {
+    let bytes;
+    if (source === "-") {
+        const input = readStdin();
+        bytes = Buffer.isBuffer(input) ? input : Buffer.from(input, "utf8");
+    }
+    else {
+        try {
+            bytes = fs.readFileSync(source);
+        }
+        catch {
+            throw new Error(`input file '${source}' is not readable`);
+        }
+    }
+    if (maxBytes !== undefined && maxBytes > 0 && bytes.byteLength > maxBytes)
+        throw new Error(`input exceeds the ${maxBytes}-byte UTF-8 limit`);
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new Error("input is not valid UTF-8");
+    }
+    try {
+        return loadYamlMapping(text);
+    }
+    catch (error) {
+        throw new Error(`input is not valid YAML or JSON: ${error.message}`);
+    }
+}