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

package/dist/state/entityListProjection.js

@@ -0,0 +1,187 @@
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { StateRetrievalFailure } from "./directRetrieval.js";
+import { serializedProjectionBytes } from "./projectionPolicy.js";
+import { shellQuoteArgument } from "../core/shell.js";
+import { entityListFamily, entityListValidValues } from "./entityRetrievalHelp.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fail(options, message, recovery, exitCode, validValues) {
+    const family = entityListFamily(options.family);
+    throw new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: exitCode === 2 ? "invalid_request" : "unsupported_state",
+            message,
+            syntax: family.syntax,
+            example: family.example,
+            recovery: exitCode === 2 ? `Run \`${family.example}\`; no state was changed.` : recovery,
+            artifact: options.artifact,
+            ...(validValues ? { valid_values: validValues } : exitCode === 2 ? { valid_values: entityListValidValues(family) } : {}),
+        },
+    }, exitCode);
+}
+function fieldPaths(value, prefix = "") {
+    if (!mapping(value))
+        return [];
+    return Object.entries(value).flatMap(([name, child]) => {
+        const field = prefix ? `${prefix}.${name}` : name;
+        return mapping(child) ? [field, ...fieldPaths(child, field)] : [field];
+    });
+}
+function selectedValue(record, field) {
+    let value = record;
+    for (const part of field.split(".")) {
+        if (!mapping(value) || !(part in value))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+function assignSelected(target, field, value) {
+    const parts = field.split(".");
+    let current = target;
+    for (const part of parts.slice(0, -1)) {
+        if (!mapping(current[part]))
+            current[part] = {};
+        current = current[part];
+    }
+    current[parts.at(-1)] = structuredClone(value);
+}
+export function resolveEntityListSelector(input, entries, options) {
+    if (input?.idsOnly && input.fields !== undefined) {
+        fail(options, "--ids-only and --fields cannot be combined", "Choose one bounded selector and retry; no state was changed.", 2);
+    }
+    if (input?.idsOnly)
+        return { mode: "ids_only", fields: [] };
+    if (input?.fields === undefined)
+        return { mode: "default", fields: [] };
+    const requested = input.fields.split(",").map((field) => field.trim());
+    if (!requested.length || requested.some((field) => !/^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/.test(field))) {
+        fail(options, "--fields must be a comma-separated list of record field paths", "Use lowercase record paths such as status or header.title; no state was changed.", 2);
+    }
+    if (new Set(requested).size !== requested.length) {
+        fail(options, "--fields contains a duplicate field path", "Remove duplicate field paths and retry; no state was changed.", 2);
+    }
+    const fields = [...requested].sort();
+    const available = [...new Set(entries.flatMap((entry) => fieldPaths(entry.record)))].sort();
+    const unsupported = fields.find((field) => !available.includes(field));
+    if (unsupported) {
+        fail(options, `unsupported record field '${unsupported}' for this filtered ${options.artifact} snapshot; available fields: ${available.join(", ") || "none"}`, "Choose a listed field or change the filters, then restart without --cursor; no state was changed.", 2, available);
+    }
+    return { mode: "fields", fields };
+}
+export function entityListSelectorKey(selector) {
+    return canonicalRecordJson({ mode: selector.mode, fields: selector.fields });
+}
+export function entityListSelectorFlags(selector) {
+    if (selector.mode === "ids_only")
+        return " --ids-only";
+    if (selector.mode === "fields")
+        return ` --fields ${shellQuoteArgument(selector.fields.join(","))}`;
+    return "";
+}
+function identityEntry(entry, family, fields) {
+    const id = String(entry.id);
+    const result = { id, artifact: String(entry.artifact) };
+    for (const field of fields) {
+        if (field === "id" || field === "artifact")
+            continue;
+        if (field === "retrieval.get") {
+            result.retrieval = { get: family.get.replace("ID", id) };
+            continue;
+        }
+        const value = selectedValue(entry, field);
+        if (value !== undefined)
+            assignSelected(result, field, value);
+    }
+    return result;
+}
+function projectEntry(entry, selector, family) {
+    const fields = selector.mode === "default" ? family.summaryFields : family.minimumFields;
+    const identity = identityEntry(entry, family, fields);
+    if (selector.mode === "ids_only" || selector.mode === "default")
+        return identity;
+    const record = {};
+    for (const field of selector.fields) {
+        const value = mapping(entry.record) ? selectedValue(entry.record, field) : undefined;
+        if (value !== undefined)
+            assignSelected(record, field, value);
+    }
+    return { ...identity, record };
+}
+function omittedTopLevelFields(fullEntries, retainedEntries) {
+    const omitted = new Set();
+    fullEntries.forEach((entry, index) => {
+        const retained = retainedEntries[index] ?? {};
+        for (const field of Object.keys(entry))
+            if (!(field in retained))
+                omitted.add(field);
+    });
+    return [...omitted].sort();
+}
+function degradedProjection(response, entries, selector, options, family, fullEntries, detail) {
+    return normalize({
+        ...response,
+        status: "degraded",
+        degradation: {
+            reason: "optional_detail_byte_budget",
+            detail_omitted_count: entries.length,
+            omitted_fields: omittedTopLevelFields(fullEntries, entries),
+            recovery: family.get,
+        },
+    }, entries, selector, options, detail);
+}
+function normalize(response, entries, selector, options, detail) {
+    const family = entityListFamily(options.family);
+    const counts = mapping(response.counts) ? response.counts : {};
+    const snapshot = mapping(response.snapshot) ? response.snapshot : {};
+    const candidate = Number(snapshot.candidate_count ?? counts.total ?? entries.length);
+    const remaining = Number(counts.remaining ?? 0);
+    const retrieval = mapping(response.retrieval) ? response.retrieval : {};
+    return {
+        ...response,
+        entries,
+        counts: {
+            ...counts,
+            total: candidate,
+            candidate,
+            returned: entries.length,
+            remaining,
+            omitted: remaining,
+            continuation: remaining,
+        },
+        snapshot: { ...snapshot, candidate_count: candidate, has_more: remaining > 0 },
+        retrieval: { ...retrieval, get: family.get },
+        projection: {
+            selector: selector.mode,
+            detail,
+            cardinality: "requested_rows",
+            ...(selector.mode === "fields" ? { fields: selector.fields } : {}),
+        },
+    };
+}
+export function projectEntityList(response, selector, options) {
+    const family = entityListFamily(options.family);
+    const fullEntries = Array.isArray(response.entries) ? response.entries.filter(mapping) : [];
+    const selectedEntries = selector.mode === "default"
+        ? fullEntries.map((entry) => ({ ...entry, retrieval: identityEntry(entry, family, family.minimumFields).retrieval }))
+        : fullEntries.map((entry) => projectEntry(entry, selector, family));
+    const selectedDetail = selector.mode === "default" ? "full" : selector.mode === "fields" ? "selected_fields" : "identity";
+    const selected = normalize(response, selectedEntries, selector, options, selectedDetail);
+    if (serializedProjectionBytes(selected, options.format === "text" ? "yaml" : options.format) <= options.maxUtf8Bytes)
+        return selected;
+    if (selector.mode !== "default") {
+        fail(options, `${selector.mode === "fields" ? "selected fields" : "IDs-only rows"} cannot fit the ${options.maxUtf8Bytes}-byte ${options.format} list budget`, "Request fewer rows or fewer fields and retry; no fields or rows were returned partially.", 1);
+    }
+    const summaries = fullEntries.map((entry) => projectEntry(entry, selector, family));
+    const degraded = degradedProjection(response, summaries, selector, options, family, fullEntries, "summary");
+    if (serializedProjectionBytes(degraded, options.format === "text" ? "yaml" : options.format) <= options.maxUtf8Bytes)
+        return degraded;
+    const minimumEntries = fullEntries.map((entry) => identityEntry(entry, family, family.minimumFields));
+    const minimum = degradedProjection(response, minimumEntries, selector, options, family, fullEntries, "minimum");
+    if (serializedProjectionBytes(minimum, options.format === "text" ? "yaml" : options.format) <= options.maxUtf8Bytes)
+        return minimum;
+    fail(options, `the requested summary rows cannot fit the ${options.maxUtf8Bytes}-byte ${options.format} list budget`, "Request fewer rows and retry; no rows were returned partially.", 1);
+}

package/dist/state/entityListRuntimeRegistry.js

@@ -0,0 +1,85 @@
+import { CANONICAL_DEVELOPMENT_CLI } from "../core/developmentChannel.js";
+const COMMON_SUMMARY_FIELDS = ["id", "artifact", "retrieval.get"];
+export const ENTITY_LIST_RUNTIME_FORMATS = ["text", "json", "yaml"];
+export const ENTITY_LIST_RUNTIME_BOUNDS = {
+    minimum: 1,
+    default: 20,
+    maximum: 100,
+    maxUtf8Bytes: 32768,
+};
+export const ENTITY_LIST_RUNTIME_SELECTORS = {
+    idsOnly: "--ids-only",
+    fields: "--fields FIELDS",
+};
+function family(options) {
+    const identifier = options.familyIdentifier
+        ? ` ${options.familyIdentifier.required ? options.familyIdentifier.syntax : `[${options.familyIdentifier.syntax}]`}`
+        : "";
+    const filters = options.filters.map(({ flag }) => ` [${flag}]`).join("");
+    const root = `${CANONICAL_DEVELOPMENT_CLI} state ${options.commandTokens.join(" ")}`;
+    const projection = {
+        list: `${root} list${identifier}${filters} [--limit N] [--cursor TOKEN] [--ids-only | --fields FIELDS] --format json`,
+        get: `${root} get --id ID --format json`,
+        example: `${CANONICAL_DEVELOPMENT_CLI} ${options.exampleArguments}`,
+        ...(options.bareRecoveryArguments ? { bareRecovery: `${CANONICAL_DEVELOPMENT_CLI} ${options.bareRecoveryArguments}` } : {}),
+    };
+    const { exampleArguments: _example, bareRecoveryArguments: _bareRecovery, ...runtime } = options;
+    return { ...runtime, projection };
+}
+export const ENTITY_LIST_RUNTIME_REGISTRY = {
+    progress: family({ key: "progress", commandTokens: ["progress"], parser: "generic", artifact: "progress", boundary: "progress_cycle", bareRead: "alias", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state progress list --limit 20 --format json" }),
+    decisions: family({ key: "decisions", commandTokens: ["decisions"], parser: "generic", artifact: "decisions", boundary: "decision", bareRead: "alias", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state decisions list --limit 20 --format json" }),
+    health: family({ key: "health", commandTokens: ["health"], parser: "generic", artifact: "health", boundary: "health_audit", bareRead: "correction", filters: [{ name: "dimension", flag: "--dimension DIMENSION", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state health list --limit 20 --format json", bareRecoveryArguments: "state health list --limit 20 --format json" }),
+    plans: family({ key: "plans", commandTokens: ["plan"], parser: "plans", artifact: "plan", boundary: "plan", bareRead: "correction", filters: [{ name: "status", flag: "--status open|complete|archived", values: ["open", "complete", "archived"] }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state plan list --status open --limit 20 --format json", bareRecoveryArguments: "state plan list --status open --limit 20 --format json" }),
+    plan_tasks: family({ key: "plan_tasks", commandTokens: ["plan", "tasks"], parser: "plan_tasks", artifact: "plan", boundary: "plan_task", boundsBoundary: "plan", bareRead: "correction", filters: [], familyIdentifier: { syntax: "PLAN_ID", required: false }, summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state plan tasks list --limit 20 --format json", bareRecoveryArguments: "state plan tasks list --limit 20 --format json" }),
+    objective: family({ key: "objective", commandTokens: ["objective"], parser: "generic", artifact: "objective", boundary: "objective", bareRead: "correction", filters: [], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state objective list --limit 20 --format json", bareRecoveryArguments: "state objective list --limit 20 --format json" }),
+    experiments: family({ key: "experiments", commandTokens: ["experiments"], bareRecoveryCommandTokens: ["objective"], parser: "experiments", artifact: "experiments", boundary: "experiment", bareRead: "correction", filters: [], familyIdentifier: { syntax: "--objective ID", required: true }, summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state experiments list --objective qjtrmnpvka --limit 20 --format json", bareRecoveryArguments: "state objective list --limit 20 --format json" }),
+    todo: family({ key: "todo", commandTokens: ["todo"], parser: "generic", artifact: "todo", boundary: "todo_item", bareRead: "alias", filters: [{ name: "severity", flag: "--severity SEVERITY", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: ["id", "artifact", "public_order", "readiness", "actionability", "queue_rank", "reconciliation", "retrieval.get"], exampleArguments: "state todo list --severity critical --ids-only --limit 20 --format json" }),
+    docs: family({ key: "docs", commandTokens: ["docs"], parser: "generic", artifact: "docs", boundary: "documentation_inventory_entry", bareRead: "correction", filters: [{ name: "topic", flag: "--topic TEXT", values: "free_text" }, { name: "status", flag: "--status STATUS", values: "free_text" }], summaryFields: COMMON_SUMMARY_FIELDS, exampleArguments: "state docs list --limit 20 --format json", bareRecoveryArguments: "state docs list --limit 20 --format json" }),
+};
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+deepFreeze(ENTITY_LIST_RUNTIME_REGISTRY);
+export const ENTITY_LIST_RUNTIME_FAMILIES = Object.freeze(Object.values(ENTITY_LIST_RUNTIME_REGISTRY));
+export function runtimeEntityFamiliesForCommand(command) {
+    return ENTITY_LIST_RUNTIME_FAMILIES.filter(({ commandTokens }) => commandTokens[0] === command);
+}
+export function runtimeEntityListFamilyForStateArgs(command, argv) {
+    return ENTITY_LIST_RUNTIME_FAMILIES
+        .filter(({ commandTokens }) => commandTokens[0] === command)
+        .sort((left, right) => right.commandTokens.length - left.commandTokens.length)
+        .find(({ commandTokens }) => {
+        const remainder = commandTokens.slice(1);
+        return remainder.every((token, index) => argv[index] === token) && argv[remainder.length] === "list";
+    });
+}
+export function runtimeEntityFamilyForStateCommand(command, argv) {
+    return runtimeEntityFamiliesForCommand(command)
+        .slice()
+        .sort((left, right) => right.commandTokens.length - left.commandTokens.length)
+        .find(({ commandTokens }) => commandTokens.slice(1).every((token, index) => argv[index] === token));
+}
+export function runtimeEntityListFamilyForHelpArgs(args) {
+    return ENTITY_LIST_RUNTIME_FAMILIES
+        .slice()
+        .sort((left, right) => right.commandTokens.length - left.commandTokens.length)
+        .find(({ commandTokens }) => args.length === commandTokens.length + 1 && args.at(-1) === "list" && commandTokens.every((token, index) => args[index] === token));
+}
+export function runtimeEntityFamilyForHelpArgs(args) {
+    for (const family of ENTITY_LIST_RUNTIME_FAMILIES.slice().sort((left, right) => right.commandTokens.length - left.commandTokens.length)) {
+        for (const verb of ["list", "get"]) {
+            if (args.length === family.commandTokens.length + 1 && args.at(-1) === verb && family.commandTokens.every((token, index) => args[index] === token))
+                return { family, verb };
+        }
+    }
+    return undefined;
+}
+export function runtimeGenericEntityListFamily(artifact) {
+    return ENTITY_LIST_RUNTIME_FAMILIES.find((family) => family.parser === "generic" && family.artifact === artifact);
+}

package/dist/state/entityMigrationCausality.js

@@ -0,0 +1,97 @@
+/**
+ * Source validation identifies root corruption. Relationship validation then
+ * reports its downstream effects without relabelling valid source records as
+ * corrupt. A deterministic member roots an otherwise-valid cycle because the
+ * cycle itself is malformed source state and has no recovery interpretation.
+ */
+export function applyCausalBlockers(entries, recoveryFor, rootReasons = new Map()) {
+    const byIdentity = new Map(entries.map((entry) => [entry.source_identity, entry]));
+    for (const entry of entries) {
+        const unresolved = entry.relationships.find((relationship) => relationship.status === "unresolved");
+        if (unresolved) {
+            const target = unresolved.target_source_identity ?? "missing structured reference";
+            rootReasons.set(entry.source_identity, `source relationship '${unresolved.field}' references unresolved target '${target}'`);
+            entry.classification = "corrupt";
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = `Repair relationship '${unresolved.field}' on '${entry.source_identity}' to reference an inventoried source identity instead of '${target}', then run ${recoveryFor(entry.source_paths[0] ?? "migration source")}`;
+        }
+        if (["duplicate", "conflict", "corrupt", "unsupported"].includes(entry.classification) && !rootReasons.has(entry.source_identity))
+            rootReasons.set(entry.source_identity, `${entry.classification} source requires explicit recovery`);
+    }
+    const adjacency = new Map(entries.map((entry) => [entry.source_identity, entry.relationships
+            .filter((relationship) => relationship.status === "resolved" && relationship.target_source_identity && byIdentity.has(relationship.target_source_identity))
+            .map((relationship) => relationship.target_source_identity)
+            .sort()]));
+    const index = new Map();
+    const lowlink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let nextIndex = 0;
+    const visit = (sourceIdentity) => {
+        index.set(sourceIdentity, nextIndex);
+        lowlink.set(sourceIdentity, nextIndex++);
+        stack.push(sourceIdentity);
+        onStack.add(sourceIdentity);
+        for (const target of adjacency.get(sourceIdentity) ?? []) {
+            if (!index.has(target)) {
+                visit(target);
+                lowlink.set(sourceIdentity, Math.min(lowlink.get(sourceIdentity), lowlink.get(target)));
+            }
+            else if (onStack.has(target))
+                lowlink.set(sourceIdentity, Math.min(lowlink.get(sourceIdentity), index.get(target)));
+        }
+        if (lowlink.get(sourceIdentity) !== index.get(sourceIdentity))
+            return;
+        const component = [];
+        while (true) {
+            const member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+            if (member === sourceIdentity)
+                break;
+        }
+        const cyclic = component.length > 1 || (adjacency.get(sourceIdentity) ?? []).includes(sourceIdentity);
+        if (cyclic && !component.some((member) => rootReasons.has(member))) {
+            const root = component.sort()[0];
+            const entry = byIdentity.get(root);
+            rootReasons.set(root, `source relationship graph contains a cycle rooted at '${root}'`);
+            entry.classification = "corrupt";
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = `Break the relationship cycle containing '${root}', then run ${recoveryFor(entry.source_paths[0] ?? "migration source")}`;
+        }
+    };
+    for (const sourceIdentity of [...byIdentity.keys()].sort())
+        if (!index.has(sourceIdentity))
+            visit(sourceIdentity);
+    const roots = new Set(rootReasons.keys());
+    const memo = new Map();
+    const resolving = new Set();
+    const resolveRoots = (sourceIdentity) => {
+        if (roots.has(sourceIdentity))
+            return [sourceIdentity];
+        const existing = memo.get(sourceIdentity);
+        if (existing)
+            return existing;
+        // Every cycle has a root after the SCC pass. This guard keeps malformed
+        // graph handling fail-closed if that invariant is ever changed.
+        if (resolving.has(sourceIdentity))
+            return [];
+        resolving.add(sourceIdentity);
+        const resolved = [...new Set((adjacency.get(sourceIdentity) ?? []).flatMap(resolveRoots))].sort();
+        resolving.delete(sourceIdentity);
+        memo.set(sourceIdentity, resolved);
+        return resolved;
+    };
+    for (const entry of entries) {
+        if (roots.has(entry.source_identity))
+            continue;
+        if (resolveRoots(entry.source_identity).length > 0) {
+            entry.proposed_target = null;
+            entry.target_sha256 = null;
+            entry.recovery = recoveryFor(entry.source_paths[0]);
+        }
+    }
+    return { rootReasons, rootsFor: resolveRoots };
+}

package/dist/state/entityMigrationIdentity.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+export function entityMigrationId(sourceFingerprint, sourceIdentity) {
+    const bytes = createHash("sha256").update(`agentera.entity-preview.v1\0${sourceFingerprint}\0${sourceIdentity}`, "utf8").digest();
+    return Array.from(bytes.subarray(0, 10), (byte) => String.fromCharCode(97 + byte % 26)).join("");
+}