agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/dist/state/archivePublication.js

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { dumpYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { ArtifactSchemaValidator } from "../hooks/validateArtifact/index.js";
+import { assertRealpathBoundary } from "../registries/artifactRegistry.js";
+import { canonicalRecordJson, discoverNumberedArchives, numberedArchiveContract, } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+const nodeFileSystem = {
+    exists: (candidate) => fs.existsSync(candidate),
+    mkdir: (directory) => fs.mkdirSync(directory),
+    openExclusive: (stage) => fs.openSync(stage, "wx"),
+    write: (fd, bytes) => fs.writeFileSync(fd, bytes, "utf8"),
+    syncFile: (fd) => fs.fsyncSync(fd),
+    close: (fd) => fs.closeSync(fd),
+    link: (stage, target) => fs.linkSync(stage, target),
+    unlink: (stage) => fs.unlinkSync(stage),
+    syncDirectory: (directory) => {
+        const fd = fs.openSync(directory, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    },
+};
+function nearestExistingDirectory(directory, fileSystem) {
+    let cursor = path.resolve(directory);
+    while (!fileSystem.exists(cursor)) {
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return cursor;
+        cursor = parent;
+    }
+    return cursor;
+}
+function ensureDurableDirectory(directory, fileSystem, options) {
+    const root = path.resolve(options.directoryDurabilityRoot ?? nearestExistingDirectory(directory, fileSystem));
+    const relative = path.relative(root, path.resolve(directory));
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`directory durability root '${root}' does not contain '${directory}'`);
+    let parent = root;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        const child = path.join(parent, segment);
+        let created = false;
+        if (!fileSystem.exists(child)) {
+            try {
+                fileSystem.mkdir(child);
+                created = true;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        fileSystem.syncDirectory(parent);
+        if (created)
+            options.afterDirectoryEntrySync?.(child);
+        parent = child;
+    }
+}
+let stageSequence = 0;
+export function publishImmutableFile(target, bytes, options = {}) {
+    const fileSystem = options.fileSystem ?? nodeFileSystem;
+    const directory = path.dirname(target);
+    ensureDurableDirectory(directory, fileSystem, options);
+    const stage = stagePath(directory, path.basename(target));
+    let stageCreated = false;
+    let fd;
+    try {
+        fd = fileSystem.openExclusive(stage);
+        stageCreated = true;
+        fileSystem.write(fd, bytes);
+        fileSystem.syncFile(fd);
+        fileSystem.close(fd);
+        fd = undefined;
+        try {
+            fileSystem.link(stage, target);
+            fileSystem.syncDirectory(directory);
+            options.afterDirectorySync?.();
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            options.onExisting?.();
+            return false;
+        }
+    }
+    finally {
+        if (fd !== undefined)
+            fileSystem.close(fd);
+        if (stageCreated) {
+            try {
+                fileSystem.unlink(stage);
+                fileSystem.syncDirectory(directory);
+            }
+            catch {
+                // A linked file is authoritative; a private stage can be cleaned on retry.
+            }
+        }
+    }
+}
+function rejectConflict(stableId, message) {
+    reject({
+        class: "conflict",
+        message,
+        syntax: "agentera state <artifact-id> append ... --format json",
+        example: "retry the same append for an identical record; change the entry content for a new record",
+        violations: [`immutable archive identity: ${stableId}`],
+    });
+}
+function assertNoSymlinkPath(projectRoot, candidate) {
+    const relative = path.relative(path.resolve(projectRoot), candidate);
+    let cursor = path.resolve(projectRoot);
+    for (const segment of relative.split(path.sep)) {
+        if (!segment)
+            continue;
+        cursor = path.join(cursor, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(cursor);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            reject({
+                class: "unsupported_target",
+                message: `numbered archive path contains a symbolic link: '${cursor}'`,
+                syntax: "agentera state <artifact-id> append ... --format json",
+                example: "remove the symbolic link and retry the append",
+            });
+    }
+}
+function archivePath(projectRoot, artifactId, entryNumber, sourceRoot) {
+    if (!Number.isSafeInteger(entryNumber) || entryNumber <= 0)
+        reject({
+            class: "invalid_int",
+            message: `entry number must be a positive safe integer, got '${entryNumber}'`,
+            syntax: "entry number N",
+            example: "use the number assigned by the state writer",
+        });
+    const contract = numberedArchiveContract(artifactId, sourceRoot);
+    const target = path.join(path.resolve(projectRoot), contract.archiveRoot, contract.artifactId, `${entryNumber}${contract.archiveExtension}`);
+    try {
+        assertRealpathBoundary(projectRoot, target, "numbered archive");
+    }
+    catch (error) {
+        reject({
+            class: "unsupported_target",
+            message: error.message,
+            syntax: "agentera state <artifact-id> append ... --format json",
+            example: "select a project-local archive path and retry",
+        });
+    }
+    assertNoSymlinkPath(projectRoot, target);
+    return { target, stableId: `${artifactId}:${entryNumber}`, contract };
+}
+function validateRecord(sourceRoot, contract, entryNumber, record) {
+    if (typeof record[contract.entryNumberField] !== "number" ||
+        !Number.isSafeInteger(record[contract.entryNumberField]) ||
+        record[contract.entryNumberField] !== entryNumber) {
+        throw new Error(`archive record ${contract.entryNumberField} must equal its positive entry number ${entryNumber}`);
+    }
+    const validator = new ArtifactSchemaValidator(path.join(sourceRoot, "skills", "agentera", "schemas", "artifacts"));
+    const schema = validator.loadSchema(contract.artifactId);
+    if (!schema)
+        throw new Error(`archive artifact '${contract.artifactId}' schema is unavailable`);
+    const violations = validator.validateYaml(dumpYamlMapping({ [contract.entryCollection]: [record] }), schema, contract.artifactId);
+    if (violations.length > 0)
+        throw new Error(`archive record failed ${contract.artifactId} schema validation: ${violations.join("; ")}`);
+    return canonicalRecordJson(record);
+}
+function stagePath(directory, filename) {
+    stageSequence += 1;
+    return path.join(directory, `.${filename}.writer.${process.pid}.${stageSequence}.tmp`);
+}
+function existingArchiveMatches(projectRoot, target, stableId, record, sourceRoot) {
+    const discovered = discoverNumberedArchives(projectRoot, { sourceRoot });
+    const existing = discovered.entries.find((entry) => entry.path === target);
+    if (existing && canonicalRecordJson(existing.record) === canonicalRecordJson(record))
+        return true;
+    rejectConflict(stableId, `immutable archive '${target}' already exists with different or invalid canonical content; existing bytes were preserved`);
+}
+export function publishNumberedArchive(projectRoot, artifactId, entryNumber, record, options = {}) {
+    const sourceRoot = options.sourceRoot ?? resolveSourceRoot();
+    const fileSystem = options.fileSystem ?? nodeFileSystem;
+    const location = archivePath(projectRoot, artifactId, entryNumber, sourceRoot);
+    const serialized = serializeNumberedArchive(artifactId, entryNumber, record, sourceRoot, options);
+    const published = publishImmutableFile(location.target, serialized.bytes, {
+        fileSystem,
+        directoryDurabilityRoot: projectRoot,
+        afterDirectorySync: options.afterDirectorySync,
+        onExisting: () => {
+            existingArchiveMatches(projectRoot, location.target, location.stableId, record, sourceRoot);
+        },
+    });
+    return {
+        path: location.target,
+        stableId: location.stableId,
+        recordSha256: serialized.recordSha256,
+        replay: !published,
+    };
+}
+export function serializeNumberedArchive(artifactId, entryNumber, record, sourceRoot = resolveSourceRoot(), options = {}) {
+    const contract = numberedArchiveContract(artifactId, sourceRoot);
+    const canonical = validateRecord(sourceRoot, contract, entryNumber, record);
+    const recordSha256 = createHash("sha256").update(canonical, "utf8").digest("hex");
+    return {
+        bytes: dumpYamlMapping({
+            schemaVersion: contract.entrySchemaVersion,
+            artifact_id: artifactId,
+            entry_number: entryNumber,
+            record,
+            record_sha256: recordSha256,
+            ...(options.recoveryProvenance ? { recovery_provenance: options.recoveryProvenance } : {}),
+        }),
+        recordSha256,
+    };
+}

package/dist/state/archiveRecovery.js

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { canonicalRecordJson, discoverNumberedArchives, numberedArchiveContract, } from "./archiveDiscovery.js";
+const PROJECTION_COMMAND = "agentera check compact --mode fix --format json";
+function entryNumber(record, contract) {
+    const value = record[contract.entryNumberField];
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
+        const parsed = Number(value);
+        return Number.isSafeInteger(parsed) ? parsed : null;
+    }
+    return null;
+}
+function stableId(artifactId, number) {
+    return `${artifactId}:${number ?? "?"}`;
+}
+function archivePath(projectRoot, contract, artifactId, number) {
+    if (number === null)
+        return undefined;
+    return path.join(path.resolve(projectRoot), contract.archiveRoot, artifactId, `${number}${contract.archiveExtension}`);
+}
+function rejectionForEntry(rejectionList, target, contract, number) {
+    if (!target || number === null)
+        return undefined;
+    const artifactDirectory = path.dirname(target);
+    return rejectionList.find((candidate) => {
+        const candidatePath = path.resolve(candidate.path);
+        const resolvedTarget = path.resolve(target);
+        const targetFromCandidate = path.relative(candidatePath, resolvedTarget);
+        if (candidatePath === resolvedTarget ||
+            candidatePath === path.resolve(artifactDirectory) ||
+            (targetFromCandidate !== "" &&
+                !targetFromCandidate.startsWith(".." + path.sep) &&
+                !path.isAbsolute(targetFromCandidate))) {
+            return true;
+        }
+        const relative = path.relative(artifactDirectory, candidatePath);
+        if (!relative || relative.includes(path.sep))
+            return false;
+        const stem = relative.endsWith(contract.archiveExtension)
+            ? relative.slice(0, -contract.archiveExtension.length)
+            : "";
+        return /^\+?[0-9]+$/.test(stem) && Number(stem.replace(/^\+/, "")) === number;
+    });
+}
+function errorClassForRejection(rejection) {
+    return rejection.class === "unsupported_artifact" ||
+        rejection.reason === "unsupported_artifact" ||
+        (rejection.reason === "invalid_envelope" && rejection.message.startsWith("schemaVersion must be"))
+        ? "unsupported_state"
+        : "corrupt";
+}
+function failure(projectRoot, artifactId, number, contract, recoveryClass, message, details = {}) {
+    const archive = contract ? archivePath(projectRoot, contract, artifactId, number) : undefined;
+    const id = stableId(artifactId, number);
+    const recovery = recoveryClass === "not_found"
+        ? "Keep the current full entry and publish or restore its validated numbered archive before retrying."
+        : recoveryClass === "corrupt"
+            ? "Keep the current full entry, preserve the archive bytes for diagnostics, repair the archive, then retry."
+            : recoveryClass === "immutable_conflict"
+                ? "Keep the current full entry, preserve the immutable archive bytes, reconcile the conflicting record, then retry."
+                : "Keep the current full entry and use a state format supported by the storage authority before retrying.";
+    const status = recoveryClass === "not_found"
+        ? "degraded"
+        : recoveryClass === "unsupported_state"
+            ? "unsupported"
+            : "blocked";
+    return {
+        stable_id: id,
+        artifact_id: artifactId,
+        ...(number === null ? {} : { entry_number: number }),
+        ...(archive ? { archive_path: archive } : {}),
+        status,
+        reason: recoveryClass,
+        detail_availability: "full",
+        source: "current_projection",
+        error: {
+            schemaVersion: "agentera.stateFailure.v1",
+            class: recoveryClass,
+            message,
+            syntax: PROJECTION_COMMAND,
+            example: PROJECTION_COMMAND,
+            recovery,
+            details: {
+                artifact_id: artifactId,
+                entry_number: number,
+                stable_id: id,
+                ...(archive ? { archive_path: archive } : {}),
+                ...details,
+            },
+        },
+    };
+}
+function verifyWithDiscovery(projectRoot, artifactId, record, contract, discovery) {
+    const number = entryNumber(record, contract);
+    const target = archivePath(projectRoot, contract, artifactId, number);
+    const id = stableId(artifactId, number);
+    if (number === null) {
+        return failure(projectRoot, artifactId, number, contract, "unsupported_state", `full entry ${id} has no supported positive archive entry number`);
+    }
+    const candidate = discovery.entries.find((entry) => entry.stableId === id);
+    if (candidate) {
+        let expectedHash;
+        try {
+            expectedHash = createHash("sha256").update(canonicalRecordJson(record), "utf8").digest("hex");
+        }
+        catch (error) {
+            return failure(projectRoot, artifactId, number, contract, "unsupported_state", `full entry ${id} cannot be represented as canonical archive content: ${error.message}`);
+        }
+        if (candidate.recordSha256 === expectedHash && canonicalRecordJson(candidate.record) === canonicalRecordJson(record)) {
+            return {
+                stable_id: id,
+                artifact_id: artifactId,
+                entry_number: number,
+                archive_path: candidate.path,
+                status: "complete",
+                reason: "verified",
+                detail_availability: "full",
+                source: "archive",
+            };
+        }
+        return failure(projectRoot, artifactId, number, contract, "immutable_conflict", `archive record ${id} is valid but conflicts with the full current entry; summary publication is refused`, {
+            archive_record_sha256: candidate.recordSha256,
+            expected_record_sha256: expectedHash,
+        });
+    }
+    const rejection = rejectionForEntry(discovery.rejected, target, contract, number);
+    if (rejection) {
+        const recoveryClass = errorClassForRejection(rejection);
+        return failure(projectRoot, artifactId, number, contract, recoveryClass, `archive record ${id} cannot be verified: ${rejection.message}; summary publication is refused`, { archive_rejection: rejection.reason, archive_rejection_class: rejection.class });
+    }
+    return failure(projectRoot, artifactId, number, contract, "not_found", `validated archive record ${id} is absent; summary publication is refused`);
+}
+function aggregateStatus(refusals) {
+    if (refusals.some((entry) => entry.status === "blocked"))
+        return "blocked";
+    if (refusals.some((entry) => entry.status === "unsupported"))
+        return "unsupported";
+    if (refusals.some((entry) => entry.status === "degraded"))
+        return "degraded";
+    return "complete";
+}
+function unsupportedVerification(projectRoot, artifactId, record, message) {
+    const number = typeof record.number === "number" && Number.isSafeInteger(record.number) ? record.number : null;
+    return failure(projectRoot, artifactId, number, undefined, "unsupported_state", message);
+}
+export function verifyArchiveForProjection(projectRoot, artifactId, record, options = {}) {
+    let contract;
+    try {
+        contract = numberedArchiveContract(artifactId, options.sourceRoot);
+    }
+    catch (error) {
+        return unsupportedVerification(projectRoot, artifactId, record, `artifact '${artifactId}' is outside the numbered archive authority: ${error.message}`);
+    }
+    try {
+        return verifyWithDiscovery(projectRoot, artifactId, record, contract, discoverNumberedArchives(projectRoot, { sourceRoot: options.sourceRoot }));
+    }
+    catch (error) {
+        return failure(projectRoot, artifactId, entryNumber(record, contract), contract, "unsupported_state", `archive authority could not verify ${stableId(artifactId, entryNumber(record, contract))}: ${error.message}`);
+    }
+}
+export function gateProjectionEntries(projectRoot, artifactId, records, options = {}) {
+    if (records.length === 0) {
+        return {
+            verified: [],
+            refused: [],
+            recovery: { status: "complete", attempted: 0, verified: 0, retained_full: 0, refused_count: 0, refusals: [] },
+        };
+    }
+    let contract;
+    try {
+        contract = numberedArchiveContract(artifactId, options.sourceRoot);
+    }
+    catch (error) {
+        const refused = records.map((entry) => ({
+            entry,
+            recovery: unsupportedVerification(projectRoot, artifactId, entry, `artifact '${artifactId}' is outside the numbered archive authority: ${error.message}`),
+        }));
+        return {
+            verified: [],
+            refused,
+            recovery: {
+                status: "unsupported",
+                attempted: records.length,
+                verified: 0,
+                retained_full: records.length,
+                refused_count: refused.length,
+                refusals: refused.map(({ recovery }) => recovery),
+            },
+        };
+    }
+    let discovery;
+    try {
+        discovery = discoverNumberedArchives(projectRoot, { sourceRoot: options.sourceRoot });
+    }
+    catch (error) {
+        const refused = records.map((entry) => ({
+            entry,
+            recovery: failure(projectRoot, artifactId, entryNumber(entry, contract), contract, "unsupported_state", `archive authority could not verify ${stableId(artifactId, entryNumber(entry, contract))}: ${error.message}`),
+        }));
+        return {
+            verified: [],
+            refused,
+            recovery: {
+                status: "unsupported",
+                attempted: records.length,
+                verified: 0,
+                retained_full: records.length,
+                refused_count: refused.length,
+                refusals: refused.map(({ recovery }) => recovery),
+            },
+        };
+    }
+    const verified = [];
+    const refused = [];
+    for (const entry of records) {
+        const recovery = verifyWithDiscovery(projectRoot, artifactId, entry, contract, discovery);
+        if (recovery.reason === "verified")
+            verified.push(entry);
+        else
+            refused.push({ entry, recovery });
+    }
+    const refusals = refused.map(({ recovery }) => recovery);
+    return {
+        verified,
+        refused,
+        recovery: {
+            status: aggregateStatus(refusals),
+            attempted: records.length,
+            verified: verified.length,
+            retained_full: refused.length,
+            refused_count: refused.length,
+            refusals,
+        },
+    };
+}

package/dist/state/archiveReplay.js

@@ -0,0 +1,53 @@
+import { isDeepStrictEqual } from "node:util";
+import { discoverNumberedArchives } from "./archiveDiscovery.js";
+import { reject } from "./write/errors.js";
+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;
+}
+export function isExactArchiveReplay(entry, payload) {
+    if (!entry)
+        return false;
+    const projected = {};
+    for (const [key, expected] of Object.entries(payload)) {
+        if (expected === undefined)
+            continue;
+        const parts = key.split(".");
+        let cursor = projected;
+        for (const part of parts.slice(0, -1)) {
+            if (!cursor[part] || typeof cursor[part] !== "object")
+                cursor[part] = {};
+            cursor = cursor[part];
+        }
+        cursor[parts.at(-1)] = mappingPath(entry, key);
+    }
+    return isDeepStrictEqual(projected, payload);
+}
+export function findArchivedReplay(projectRoot, artifact, payload) {
+    if (Object.keys(payload).length === 0)
+        return undefined;
+    return discoverNumberedArchives(projectRoot).entries
+        .filter((entry) => entry.artifactId === artifact)
+        .find((entry) => isExactArchiveReplay(entry.record, payload))?.record;
+}
+export function recoverArchivedEntry(candidate, collection, entries, recovered, descending) {
+    const number = Number(recovered.number);
+    const sameNumber = entries.find((entry) => Number(entry.number) === number);
+    if (sameNumber && !isDeepStrictEqual(sameNumber, recovered)) {
+        reject({
+            class: "conflict",
+            message: `archived entry ${number} conflicts with the current ${collection} projection`,
+        });
+    }
+    if (sameNumber)
+        return;
+    candidate[collection] = [...entries, recovered].sort((a, b) => {
+        const difference = Number(a.number) - Number(b.number);
+        return descending ? -difference : difference;
+    });
+}

package/dist/state/canonicalMigrationRecord.js

@@ -0,0 +1,36 @@
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Apply the authority-owned legacy-to-canonical field removal and relationship mapping. */
+export function canonicalMigrationRecord(boundary, source, forbiddenAliases, relationships = []) {
+    const record = structuredClone(source);
+    for (const field of ["id", "artifact", "number", ...forbiddenAliases])
+        delete record[field];
+    if (boundary === "decision")
+        delete record.satisfaction;
+    if (boundary === "plan" || boundary === "objective") {
+        const header = record.header;
+        if (mapping(header))
+            delete header.id;
+    }
+    if (boundary === "plan") {
+        delete record.tasks;
+        delete record.previous_plan_archived;
+        const header = record.header;
+        if (mapping(header)) {
+            if (header.status === "active")
+                header.status = "open";
+            if (header.status === "completed")
+                header.status = "complete";
+        }
+    }
+    for (const relationship of relationships) {
+        if (relationship.field === "depends_on") {
+            record.depends_on = relationships.filter(({ field }) => field === "depends_on").map(({ target_id }) => target_id);
+        }
+        else {
+            record[relationship.field] = relationship.target_id;
+        }
+    }
+    return record;
+}