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

package/dist/state/stateMode.js

@@ -0,0 +1,222 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { dumpYamlMapping, loadYamlMapping } from "../core/yaml.js";
+import { EntityPublicationContext } from "./entityPublicationContext.js";
+import { validateRealProjectRoot } from "./projectRoot.js";
+import { readProjectFileSnapshot } from "./safeProjectFile.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function contract(sourceRoot = resolveSourceRoot()) {
+    const authorityPath = path.join(sourceRoot, "references", "artifacts", "state-storage-authority.yaml");
+    const authority = loadYamlMapping(fs.readFileSync(authorityPath, "utf8"));
+    const migration = authority.entity_migration;
+    const marker = mapping(migration) ? migration.cutover_marker : null;
+    const entityMode = mapping(marker) ? marker.entity_mode : null;
+    if (!mapping(marker) ||
+        typeof marker.path !== "string" ||
+        typeof marker.schema_version !== "string" ||
+        !mapping(entityMode) ||
+        typeof entityMode.mode !== "string") {
+        throw new Error(`state storage authority '${authorityPath}' has no executable cutover marker contract`);
+    }
+    if (path.isAbsolute(marker.path) || marker.path.split(/[\\/]/).includes("..")) {
+        throw new Error(`state storage authority declares unsafe cutover marker path '${marker.path}'`);
+    }
+    return { markerPath: marker.path, schemaVersion: marker.schema_version, mode: entityMode.mode };
+}
+function readStableMarker(root, markerPath) {
+    const snapshot = readProjectFileSnapshot(root, markerPath);
+    if (snapshot.kind === "missing") {
+        if (path.resolve(snapshot.absolute) === root.path) {
+            throw new Error(`project root '${root.path}' changed while the state mode marker was inspected; restore the real directory and retry`);
+        }
+        return null;
+    }
+    if (snapshot.kind === "unsafe") {
+        const detail = snapshot.reason === "type"
+            ? "is not a regular file"
+            : snapshot.reason === "symlink"
+                ? "has an unsafe path"
+                : "changed or became unsafe while being read";
+        throw new Error(`state mode marker '${markerPath}' ${detail}; restore a stable project-local marker and retry`);
+    }
+    return snapshot.bytes;
+}
+function pathKind(root, relativePath) {
+    const absolute = path.join(root.path, ...relativePath.split("/"));
+    try {
+        const stat = fs.lstatSync(absolute);
+        if (stat.isSymbolicLink())
+            return "unsafe";
+        if (stat.isFile())
+            return "file";
+        if (stat.isDirectory())
+            return "directory";
+        return "unsafe";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        return "unsafe";
+    }
+}
+function isGitWorktreeRoot(root) {
+    const env = { ...process.env };
+    for (const name of ["GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR"])
+        delete env[name];
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: root.path,
+        env,
+        encoding: "utf8",
+    });
+    if (result.error || result.status !== 0)
+        return false;
+    try {
+        return fs.realpathSync(String(result.stdout).trim()) === root.path;
+    }
+    catch {
+        return false;
+    }
+}
+function classifyMarkerAbsentProject(root, markerPath) {
+    const stateRoot = pathKind(root, ".agentera");
+    if (stateRoot === "missing") {
+        return {
+            state: isGitWorktreeRoot(root) ? "fresh_uninitialized" : "unknown",
+            root,
+            markerPath,
+        };
+    }
+    if (stateRoot !== "directory") {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "Agentera state root '.agentera' is not a safe directory",
+        };
+    }
+    const entities = pathKind(root, ".agentera/entities");
+    if (entities !== "missing" && entities !== "directory") {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "Agentera entity root '.agentera/entities' is not a safe directory",
+        };
+    }
+    if (entities === "directory")
+        return { state: "partial", root, markerPath };
+    const aggregates = ["plan.yaml", "progress.yaml", "decisions.yaml", "health.yaml"]
+        .map((name) => pathKind(root, `.agentera/${name}`));
+    if (aggregates.includes("unsafe")) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath,
+            reason: "a recognized Agentera aggregate is not a safe regular file",
+        };
+    }
+    const aggregateCount = aggregates.filter((kind) => kind === "file").length;
+    if (aggregateCount >= 2)
+        return { state: "legacy", root, markerPath };
+    if (aggregateCount === 1)
+        return { state: "partial", root, markerPath };
+    return { state: "unknown", root, markerPath };
+}
+/** Classify local state without creating, repairing, or adopting project files. */
+export function classifyProjectState(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const root = validateRealProjectRoot(projectRoot);
+    const declared = contract(sourceRoot);
+    let bytes;
+    try {
+        bytes = readStableMarker(root, declared.markerPath);
+    }
+    catch (error) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath: declared.markerPath,
+            reason: error.message,
+        };
+    }
+    if (bytes === null)
+        return classifyMarkerAbsentProject(root, declared.markerPath);
+    try {
+        const document = loadYamlMapping(bytes.toString("utf8"));
+        if (document.schemaVersion !== declared.schemaVersion || document.mode !== declared.mode) {
+            return {
+                state: "corrupt",
+                root,
+                markerPath: declared.markerPath,
+                reason: `state mode marker '${declared.markerPath}' must declare schemaVersion '${declared.schemaVersion}' and mode '${declared.mode}'; restore the durable migration marker before retrying`,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            state: "corrupt",
+            root,
+            markerPath: declared.markerPath,
+            reason: `state mode marker '${declared.markerPath}' is corrupt: ${error.message}; restore the durable migration marker before retrying`,
+        };
+    }
+    return { state: "entities", root, markerPath: declared.markerPath, markerBytes: bytes };
+}
+export function freshEntityStateMarker(sourceRoot = resolveSourceRoot()) {
+    const declared = contract(sourceRoot);
+    return { schemaVersion: declared.schemaVersion, mode: declared.mode };
+}
+export function freshPlanInitialization(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const classified = classifyProjectState(projectRoot, sourceRoot);
+    if (classified.state !== "fresh_uninitialized")
+        return null;
+    const marker = freshEntityStateMarker(sourceRoot);
+    return {
+        root: classified.root,
+        markerPath: classified.markerPath,
+        marker,
+        markerBytes: dumpYamlMapping(marker),
+    };
+}
+function detectValidatedStateMode(projectRoot, sourceRoot) {
+    const root = validateRealProjectRoot(projectRoot);
+    const declared = contract(sourceRoot);
+    const bytes = readStableMarker(root, declared.markerPath);
+    if (bytes === null)
+        return { mode: "legacy", root };
+    let document;
+    try {
+        document = loadYamlMapping(bytes.toString("utf8"));
+    }
+    catch (error) {
+        throw new Error(`state mode marker '${declared.markerPath}' is corrupt: ${error.message}; restore the durable migration marker before retrying`);
+    }
+    if (document.schemaVersion !== declared.schemaVersion || document.mode !== declared.mode) {
+        throw new Error(`state mode marker '${declared.markerPath}' must declare schemaVersion '${declared.schemaVersion}' and mode '${declared.mode}'; restore the durable migration marker before retrying`);
+    }
+    return { mode: "entities", root, markerPath: declared.markerPath, markerBytes: bytes };
+}
+/** Read the authority-owned cutover marker without creating or repairing state. */
+export function detectStateModeBinding(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const detected = detectValidatedStateMode(projectRoot, sourceRoot);
+    if (detected.mode === "legacy")
+        return detected;
+    return {
+        mode: "entities",
+        root: detected.root,
+        publicationContext: EntityPublicationContext.open(detected.root, detected.markerPath, detected.markerBytes),
+    };
+}
+export function detectStateMode(projectRoot, sourceRoot = resolveSourceRoot()) {
+    return detectValidatedStateMode(projectRoot, sourceRoot).mode;
+}
+export function requireEntityStateBinding(projectRoot, sourceRoot = resolveSourceRoot()) {
+    const binding = detectStateModeBinding(projectRoot, sourceRoot);
+    if (binding.mode === "legacy") {
+        throw new Error("state writes require the durable entity-state marker; legacy aggregates are read-only migration input");
+    }
+    return binding;
+}

package/dist/state/stateStorageAuthority.js

@@ -0,0 +1,47 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+const AUTHORITY_RELATIVE_PATH = path.join("references", "artifacts", "state-storage-authority.yaml");
+let cache;
+function immutableGraph(root) {
+    const proxies = new WeakMap();
+    const immutable = (value) => {
+        if (value === null || typeof value !== "object")
+            return value;
+        const existing = proxies.get(value);
+        if (existing)
+            return existing;
+        const proxy = new Proxy(value, {
+            get: (target, property, receiver) => immutable(Reflect.get(target, property, receiver)),
+            getOwnPropertyDescriptor: (target, property) => {
+                const descriptor = Reflect.getOwnPropertyDescriptor(target, property);
+                return descriptor && "value" in descriptor
+                    ? { ...descriptor, value: immutable(descriptor.value) }
+                    : descriptor;
+            },
+            set: () => { throw new TypeError("state storage authority is immutable"); },
+            defineProperty: () => { throw new TypeError("state storage authority is immutable"); },
+            deleteProperty: () => { throw new TypeError("state storage authority is immutable"); },
+            preventExtensions: () => { throw new TypeError("state storage authority is immutable"); },
+            setPrototypeOf: () => { throw new TypeError("state storage authority is immutable"); },
+        });
+        proxies.set(value, proxy);
+        return proxy;
+    };
+    return immutable(root);
+}
+/**
+ * Read the state-storage authority on every call and reuse its immutable parsed
+ * graph only while the canonical path and exact file bytes remain unchanged.
+ */
+export function loadStateStorageAuthority(sourceRoot) {
+    const authorityPath = path.resolve(sourceRoot, AUTHORITY_RELATIVE_PATH);
+    const bytes = fs.readFileSync(authorityPath);
+    if (cache?.authorityPath === authorityPath && cache.bytes.equals(bytes)) {
+        return { authorityPath, document: cache.document, revision: cache.revision };
+    }
+    const document = immutableGraph(loadYamlMapping(bytes.toString("utf8")));
+    const revision = Symbol(authorityPath);
+    cache = { authorityPath, bytes, document, revision };
+    return { authorityPath, document, revision };
+}

package/dist/state/summaryEntityRead.js

@@ -0,0 +1,25 @@
+export function isSummaryEntity(entity) {
+    return entity.boundary === "progress_summary" || entity.boundary === "decision_summary" || entity.boundary === "health_summary";
+}
+export function summaryCaveat(artifact) {
+    return `${artifact} summary is immutable migrated history: incomplete historical evidence is read-only and full record detail is unavailable.`;
+}
+export function detailMetadata(entity) {
+    const summary = isSummaryEntity(entity);
+    return {
+        boundary: entity.boundary,
+        detail_availability: summary ? "summary" : "full",
+        compatibility: summary ? "degraded" : "current",
+        ...(summary ? { caveats: [summaryCaveat(entity.artifact)] } : {}),
+    };
+}
+export function detailProvenance(projectRelativePath, entity) {
+    const summary = isSummaryEntity(entity);
+    return {
+        storage: "canonical_entity_file",
+        path: projectRelativePath,
+        boundary: entity.boundary,
+        detail: summary ? "summary" : "full",
+        ...(summary ? { migration_provenance: entity.record.migration_provenance } : {}),
+    };
+}

package/dist/state/summaryMigrationProvenance.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { loadYamlMapping } from "../core/yaml.js";
+import { canonicalRecordJson } from "./archiveDiscovery.js";
+import { canonicalMigrationRecord } from "./canonicalMigrationRecord.js";
+import { legacySummaryRecord } from "./legacySummaryRecord.js";
+import { readBoundMigrationSource } from "./migrationSourceBinding.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function summaryMigrationProvenanceDeclaration(value, authorityPath) {
+    if (!Array.isArray(value.sources))
+        throw new Error(`invalid summary migration provenance sources declaration in '${authorityPath}'`);
+    return { sources: value.sources.map((source) => {
+            if (!mapping(source) || typeof source.path !== "string" || !Array.isArray(source.collections) || !source.collections.every((collection) => typeof collection === "string")) {
+                throw new Error(`invalid summary migration provenance source declaration in '${authorityPath}'`);
+            }
+            return { path: source.path, collections: source.collections };
+        }) };
+}
+/** Bind a degraded summary to one declared legacy source record, without reopening arbitrary project paths. */
+export function summaryMigrationProvenanceViolations(boundary, record, declaration, forbiddenAliases, binding) {
+    const provenance = record.migration_provenance;
+    if (!mapping(provenance))
+        return ["migration_provenance must be a mapping"];
+    if (canonicalRecordJson(Object.keys(provenance).sort()) !== canonicalRecordJson(["source_path", "source_record_sha256"])) {
+        return ["migration_provenance must contain exactly source_path and source_record_sha256"];
+    }
+    if (typeof record.summary !== "string")
+        return ["summary must be a string"];
+    const sourcePath = provenance.source_path;
+    const sourceDigest = provenance.source_record_sha256;
+    const declaredSource = typeof sourcePath === "string" ? declaration.sources.find((source) => source.path === sourcePath) : undefined;
+    if (!declaredSource)
+        return ["migration_provenance.source_path must be an authority-declared preserved aggregate path"];
+    if (typeof sourceDigest !== "string" || !/^[a-f0-9]{64}$/.test(sourceDigest))
+        return ["migration_provenance.source_record_sha256 must be a lowercase SHA-256 digest"];
+    if (binding === undefined)
+        return ["migration_provenance requires a source binding context for a compacted summary"];
+    const source = readBoundMigrationSource(binding, declaredSource.path);
+    if (source.kind !== "file")
+        return [`migration_provenance source '${declaredSource.path}' is ${source.kind === "missing" ? "missing" : `unsafe (${source.reason})`}`];
+    let document;
+    try {
+        document = loadYamlMapping(source.bytes);
+    }
+    catch (error) {
+        return [`migration_provenance source '${declaredSource.path}' is invalid YAML: ${error.message}`];
+    }
+    const retained = structuredClone(record);
+    delete retained.migration_provenance;
+    const candidates = declaredSource.collections.flatMap((collection) => {
+        const rows = document[collection];
+        return Array.isArray(rows) ? rows.flatMap((physical) => {
+            const candidate = legacySummaryRecord(physical);
+            return candidate ? [{ physical, candidate }] : [];
+        }) : [];
+    }).filter(({ physical, candidate }) => (typeof candidate.summary === "string" || candidate.detail_availability === "summary_only")
+        && createHash("sha256").update(canonicalRecordJson(physical)).digest("hex") === sourceDigest
+        && canonicalRecordJson(canonicalMigrationRecord(boundary, candidate, forbiddenAliases)) === canonicalRecordJson(retained));
+    const canonicalCandidates = new Set(candidates.map(({ candidate }) => canonicalRecordJson(canonicalMigrationRecord(boundary, candidate, forbiddenAliases))));
+    if (canonicalCandidates.size !== 1)
+        return [canonicalCandidates.size === 0
+                ? "migration_provenance does not bind a retained canonical summary to a declared source record"
+                : "migration_provenance ambiguously binds divergent declared source summary records"];
+    return [];
+}

package/dist/state/summarySourceRowAuthority.js

@@ -0,0 +1,36 @@
+const REFERENCE = "entity_target.declared_compacted_summary_contract.source_row_provenance";
+const BOUNDARIES = new Set(["progress_summary", "decision_summary", "health_summary"]);
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string") ? [...value] : [];
+}
+/** Validate the one source-row digest semantic contract used by every summary boundary. */
+export function validateCompactedSummarySourceRowAuthority(target, authorityPath) {
+    const compacted = mapping(target.declared_compacted_summary_contract) ? target.declared_compacted_summary_contract : null;
+    const semantic = mapping(compacted?.source_row_provenance) ? compacted.source_row_provenance : null;
+    const digest = mapping(semantic?.source_record_sha256) ? semantic.source_record_sha256 : null;
+    const accepted = strings(semantic?.accepted_parsed_row_values).sort();
+    if (semantic?.status !== "implemented"
+        || semantic.semantic_id !== "v2_compacted_summary_physical_row.v1"
+        || accepted.length !== 2 || accepted[0] !== "mapping" || accepted[1] !== "scalar_string"
+        || typeof semantic.normalization !== "string"
+        || digest?.format !== "lowercase_sha256_hex"
+        || typeof digest.input !== "string"
+        || typeof digest.canonicalization !== "string")
+        throw new Error(`invalid compacted-summary source-row provenance declaration in '${authorityPath}'`);
+    const declared = Array.isArray(compacted?.boundaries) ? compacted.boundaries : [];
+    const primary = Array.isArray(target.entities) ? target.entities : [];
+    for (const [scope, entries, provenance] of [
+        ["primary", primary, (entry) => mapping(entry.canonical_metadata) && mapping(entry.canonical_metadata.summary_migration_provenance) ? entry.canonical_metadata.summary_migration_provenance : null],
+        ["declared", declared, (entry) => mapping(entry.record) && mapping(entry.record.migration_provenance) ? entry.record.migration_provenance : null],
+    ]) {
+        for (const entry of entries) {
+            if (!mapping(entry) || !BOUNDARIES.has(String(entry.boundary)))
+                continue;
+            if (provenance(entry)?.source_row_provenance !== REFERENCE)
+                throw new Error(`${scope} summary boundary '${entry.boundary}' must reference the compacted-summary source-row provenance declaration in '${authorityPath}'`);
+        }
+    }
+}

package/dist/state/todoActivationSafety.js

@@ -0,0 +1,58 @@
+import { renderTodoPublicRecord } from "../cli/todoMarkdown.js";
+import { todoActivationRisks, TODO_UNSAFE_INACTIVE_RECOVERY } from "./todoReconciliationActivation.js";
+import { reject } from "./write/errors.js";
+function publicSnapshot(record) {
+    return { present: true, description: renderTodoPublicRecord(record), severity: String(record.severity), status: String(record.status) };
+}
+function rowSnapshot(row, record) {
+    return { ...row.snapshot, severity: row.section === "resolved" ? String(record.severity) : row.snapshot.severity };
+}
+function samePublic(left, right) {
+    return ["present", "description", "severity", "status"].every((field) => left[field] === right[field]);
+}
+export function unsafeInactiveDuplicateDiagnosis(conflicting = 0) {
+    return {
+        counts: { matched: 0, converted: 0, retained: 0, duplicate: 1, stale: 0, conflicting },
+        risks: todoActivationRisks([]),
+    };
+}
+/** The one read-only decision that gates both activation preview and apply. */
+export function inactiveTodoActivationSafety(scan, entities) {
+    const todoEntities = entities.filter(({ boundary, id, record }) => boundary === "todo_item" && id && record);
+    const entityIds = new Set(todoEntities.map(({ id }) => id));
+    const unmatched = todoEntities.filter(({ id }) => !scan.rows.has(id));
+    const stale = todoEntities.filter(({ id, record }) => {
+        const row = scan.rows.get(id);
+        return row !== undefined && !samePublic(publicSnapshot(record), rowSnapshot(row, record));
+    });
+    const orphaned = [...scan.rows.keys()].filter((id) => !entityIds.has(id));
+    const resurrectedIds = todoEntities
+        .filter(({ id, record }) => {
+        const row = scan.rows.get(id);
+        return row === undefined ? record.status === "open" : record.status === "resolved" && !row.item.id;
+    })
+        .map(({ id }) => id)
+        .sort();
+    const counts = {
+        matched: scan.matchedRows,
+        converted: scan.convertedRows,
+        retained: scan.retainedLegacyRows.length,
+        duplicate: 0,
+        stale: stale.length,
+        conflicting: unmatched.length + orphaned.length,
+    };
+    return {
+        safe: unmatched.length === 0 && stale.length === 0 && orphaned.length === 0 && resurrectedIds.length === 0,
+        counts,
+        risks: todoActivationRisks(resurrectedIds),
+        resurrectedIds,
+    };
+}
+export function rejectUnsafeInactiveTodoActivation(safety) {
+    reject({
+        class: "conflict",
+        message: "TODO activation requires complete one-to-one inactive public projections",
+        diagnosis: { counts: safety.counts, risks: safety.risks },
+        recovery: TODO_UNSAFE_INACTIVE_RECOVERY,
+    });
+}