agentera 3.0.0-dev.7 → 3.0.0-dev.74

package/dist/state/safeProjectFile.js

@@ -0,0 +1,155 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertValidatedProjectRoot } from "./projectRoot.js";
+function projectPathType(stat) {
+    if (stat.isFile())
+        return "file";
+    if (stat.isDirectory())
+        return "directory";
+    if (stat.isSymbolicLink())
+        return "symlink";
+    return "other";
+}
+function samePathIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && projectPathType(left) === projectPathType(right);
+}
+function sameFileSnapshot(left, right) {
+    return left.isFile()
+        && right.isFile()
+        && samePathIdentity(left, right)
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+export function snapshotProjectPath(root, relativePath, leafType) {
+    const targets = [root];
+    let absolute = root;
+    for (const segment of relativePath.split("/").filter(Boolean)) {
+        absolute = path.join(absolute, segment);
+        targets.push(absolute);
+    }
+    const identities = [];
+    let leaf;
+    for (const [index, target] of targets.entries()) {
+        let stat;
+        try {
+            stat = fs.lstatSync(target, { bigint: true });
+        }
+        catch (error) {
+            return error.code === "ENOENT"
+                ? { kind: "missing", absolute: target, reason: "missing" }
+                : { kind: "unsafe", absolute: target, reason: "unreadable" };
+        }
+        const type = projectPathType(stat);
+        if (type === "symlink")
+            return { kind: "unsafe", absolute: target, reason: "symlink" };
+        const expected = index === targets.length - 1 ? leafType : "directory";
+        if (type !== expected)
+            return { kind: "unsafe", absolute: target, reason: "type" };
+        identities.push({ absolute: target, dev: stat.dev, ino: stat.ino, type });
+        leaf = stat;
+    }
+    return { kind: "stable", absolute, identities, leaf: leaf };
+}
+export function projectPathIsStable(snapshot) {
+    return snapshot.identities.every((identity) => {
+        try {
+            const current = fs.lstatSync(identity.absolute, { bigint: true });
+            return current.dev === identity.dev
+                && current.ino === identity.ino
+                && projectPathType(current) === identity.type;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function containedBy(root, candidate) {
+    const relativePath = path.relative(root, candidate);
+    return relativePath !== ""
+        && !relativePath.startsWith(`..${path.sep}`)
+        && relativePath !== ".."
+        && !path.isAbsolute(relativePath);
+}
+export function resolveProjectDescriptorPath(descriptor) {
+    try {
+        return fs.realpathSync(`/proc/self/fd/${descriptor}`);
+    }
+    catch {
+        return null;
+    }
+}
+function descriptorMatchesPath(root, absolute, descriptorPath) {
+    try {
+        return containedBy(root, descriptorPath) && fs.realpathSync(absolute) === descriptorPath;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pin one project file to a verified descriptor and return only stable in-project bytes. */
+export function readProjectFileSnapshot(projectRoot, relativePath, descriptorPathResolver = resolveProjectDescriptorPath, maxBytes = null) {
+    const root = typeof projectRoot === "string" ? projectRoot : projectRoot.path;
+    const verifyRoot = () => {
+        if (typeof projectRoot !== "string")
+            assertValidatedProjectRoot(projectRoot);
+    };
+    verifyRoot();
+    const pathSnapshot = snapshotProjectPath(root, relativePath, "file");
+    if (pathSnapshot.kind === "missing") {
+        verifyRoot();
+        return { bytes: null, kind: "missing", reason: "missing", absolute: pathSnapshot.absolute };
+    }
+    if (pathSnapshot.kind === "unsafe") {
+        verifyRoot();
+        return { bytes: null, kind: "unsafe", reason: pathSnapshot.reason };
+    }
+    let descriptor;
+    try {
+        const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+        descriptor = fs.openSync(pathSnapshot.absolute, fs.constants.O_RDONLY | noFollow);
+        const opened = fs.fstatSync(descriptor, { bigint: true });
+        if (!opened.isFile() || !samePathIdentity(pathSnapshot.leaf, opened) || !projectPathIsStable(pathSnapshot)) {
+            return { bytes: null, kind: "unsafe", reason: "changed" };
+        }
+        if (maxBytes !== null && opened.size > BigInt(maxBytes)) {
+            return { bytes: null, kind: "unsafe", reason: "over_limit" };
+        }
+        let descriptorRealPath = null;
+        try {
+            descriptorRealPath = descriptorPathResolver(descriptor);
+        }
+        catch { /* Descriptor paths are optional strengthening. */ }
+        if (descriptorRealPath !== null && !descriptorMatchesPath(root, pathSnapshot.absolute, descriptorRealPath)) {
+            return { bytes: null, kind: "unsafe", reason: "changed" };
+        }
+        const bytes = fs.readFileSync(descriptor);
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameFileSnapshot(opened, after)
+            || BigInt(bytes.byteLength) !== opened.size
+            || !projectPathIsStable(pathSnapshot)
+            || (descriptorRealPath !== null && !descriptorMatchesPath(root, pathSnapshot.absolute, descriptorRealPath))) {
+            return { bytes: null, kind: "unsafe", reason: "changed" };
+        }
+        verifyRoot();
+        return {
+            bytes,
+            kind: "file",
+            dev: after.dev,
+            ino: after.ino,
+            type: "file",
+            mode: Number(after.mode & 4095n),
+        };
+    }
+    catch {
+        return { bytes: null, kind: "unsafe", reason: "changed" };
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch { /* Failed close cannot make unverified bytes safe. */ }
+        }
+    }
+}

package/dist/state/startupAnalysis/benchmark.js

@@ -9,6 +9,7 @@ import { inc, counterDict, safeInt, pyJsonDumps } from "./helpers.js";
 import { boundedRuntimeStatus } from "./threshold.js";
 import { classifyStartupRecords } from "./records.js";
 import { renderStartupReport } from "./report.js";
+import { tiersDirForCorpusPath, assessTiers, readBoundedMetadata, iterBoundedRecords, legacyCorpusReadable, recoveryForState, } from "../../analytics/extractCorpus/index.js";
 export const STARTUP_INTERMEDIATE_ENVELOPE = "startup_state_analysis_v1";
 export const BENCHMARK_HISTORY_JSONL = "runs.jsonl";
 export const BENCHMARK_LATEST_REPORT_JSON = "latest-report.json";
@@ -346,21 +347,82 @@ export function buildNoRuntimeStartupIntermediate(opts = {}) {
         compatibility_note: "No runtime stores were approved, so no local runtime history was read.",
     };
 }
+/**
+ * Build a degraded corpus envelope for a tier-compatibility state. The
+ * local-corpus pseudo-runtime carries the contract-projected reason and
+ * recovery so a caller can self-service. `reason` must be a value from the
+ * evidence-tier authority's compatibility states (oversized,
+ * no_evidence, unreadable_or_schema_divergent, legacy_monolithic_state).
+ */
+function degradeEnvelope(reason, recovery) {
+    const status = {
+        runtime: "local-corpus",
+        status: "degraded",
+        reason,
+        error_count: 1,
+    };
+    if (recovery)
+        status.recovery = recovery;
+    return {
+        metadata: { runtime_statuses: [status] },
+        records: [],
+    };
+}
 export function extractStartupIntermediateFromCorpusFile(corpusPath, opts) {
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
     let corpus;
-    try {
-        corpus = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
-    }
-    catch {
+    if (assessment.analyzable) {
+        // Bounded tier read: assemble the corpus envelope from bounded evidence
+        // shards (read one at a time, each under the reader cap) plus the retained
+        // manifest metadata, then run the multi-pass startup classification. The
+        // monolithic corpus envelope is never read whole at real scale.
+        const meta = readBoundedMetadata(tiersDir);
+        const records = Array.from(iterBoundedRecords(tiersDir) ?? []);
         corpus = {
             metadata: {
-                runtime_statuses: [
-                    { runtime: "local-corpus", status: "degraded", reason: "schema_divergent", error_count: 1 },
-                ],
+                runtime_statuses: meta.corpusMetadata?.runtime_statuses ?? [],
+                adapter_version: meta.manifest?.adapter_version ?? null,
+                extracted_at: meta.corpusMetadata?.extracted_at ??
+                    meta.manifest?.published_at ??
+                    null,
             },
-            records: [],
+            records,
         };
     }
+    else if (assessment.state === "corrupt" || assessment.state === "oversized") {
+        // Tier-level failure: degrade truthfully with the contract-projected
+        // reason and recovery guidance. The boundedRuntimeStatus normalizer
+        // preserves compatibility-state reasons (no_evidence, oversized,
+        // unreadable_or_schema_divergent, legacy_monolithic_state) and passes
+        // through the recovery field for self-service correction.
+        corpus = degradeEnvelope(assessment.state === "corrupt"
+            ? "unreadable_or_schema_divergent"
+            : "oversized", assessment.recovery);
+    }
+    else if (assessment.state === "missing") {
+        // No evidence artifact or tier exists at the resolved path. Degrade with
+        // the contract's missing reason and recovery; never auto-build or scan.
+        corpus = degradeEnvelope("no_evidence", assessment.recovery);
+    }
+    else {
+        // Legacy monolithic corpus.json exists but no bounded tiers published.
+        // Size-check before reading — an oversized legacy corpus is never loaded
+        // whole, matching the contract's oversized compatibility state.
+        if (!legacyCorpusReadable(corpusPath)) {
+            corpus = degradeEnvelope("oversized", recoveryForState("oversized") ?? undefined);
+        }
+        else {
+            // Small legacy corpus: backward-compat bounded read.
+            try {
+                corpus = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
+            }
+            catch {
+                // Corrupt legacy corpus: report the contract's corrupt reason.
+                corpus = degradeEnvelope("unreadable_or_schema_divergent", recoveryForState("corrupt") ?? undefined);
+            }
+        }
+    }
     const intermediate = buildStartupIntermediate(corpus, { salt: opts.salt, contract: opts.contract ?? null });
     if (opts.outputPath) {
         fs.mkdirSync(path.dirname(opts.outputPath), { recursive: true });
@@ -368,4 +430,3 @@ export function extractStartupIntermediateFromCorpusFile(corpusPath, opts) {
     }
     return intermediate;
 }
-//# sourceMappingURL=benchmark.js.map

package/dist/state/startupAnalysis/contract.js

@@ -1,8 +1,4 @@
 import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { loadYamlMapping } from "../../core/yaml.js";
-import { resolveSourceRoot } from "../../core/sourceRoot.js";
 export const TRANSCRIPT_KEYS = new Set([
     "content",
     "text",
@@ -15,12 +11,51 @@ export const TRANSCRIPT_KEYS = new Set([
 ]);
 export const SESSION_KEYS = new Set(["session_id", "sessionID", "sessionId", "conversation_id"]);
 export const PATH_KEYS = new Set(["path", "project_path", "store_path", "file_path", "cwd", "report_path"]);
-export function contractPath(root = resolveSourceRoot()) {
-    return path.join(root, "references", "analysis", "startup-measurement-contract.yaml");
+const DEFAULT_CONTRACT = {
+    version: "startup-state-analysis-v1",
+    boundary: {
+        source: "git tag evidence",
+        commit: "b18e3dc7d768d4ad2726880916e7cfe6bd8617d3",
+        committed_at: "2026-05-12T17:50:13+02:00",
+    },
+    degradation_reasons: [
+        "pre_boundary_record",
+        "missing_timestamp",
+        "malformed_record",
+        "missing_conversation_key",
+        "no_agentera_state_sequence",
+        "privacy_redaction_required",
+    ],
+    privacy_boundary: {
+        canonical_artifact_labels: {
+            ".agentera/plan.yaml": "plan",
+            ".agentera/progress.yaml": "progress",
+            ".agentera/docs.yaml": "docs",
+            ".agentera/decisions.yaml": "decisions",
+            ".agentera/health.yaml": "health",
+            ".agentera/vision.yaml": "vision",
+            ".agentera/objective.yaml": "objective",
+            ".agentera/experiments.yaml": "experiments",
+            plan: "plan",
+            progress: "progress",
+            docs: "docs",
+            decisions: "decisions",
+            health: "health",
+            vision: "vision",
+            objective: "objective",
+            experiments: "experiments",
+            "AGENTS.md": "AGENTS.md",
+            "SKILL.md": "SKILL.md",
+        },
+    },
+};
+/** Legacy diagnostic label; startup analysis no longer loads a reference file. */
+export function contractPath() {
+    return "built-in:startup-state-analysis-v1";
 }
-export function loadContract(p = contractPath()) {
-    // cast: YAML parse returns Record<string,unknown>; privacy-boundary contract is JSON-native
-    return loadYamlMapping(fs.readFileSync(p, "utf8"));
+/** Startup analysis is source-only compatibility code with fixed redaction defaults. */
+export function loadContract() {
+    return DEFAULT_CONTRACT;
 }
 export function hashLabel(kind, value, salt) {
     if (!salt) {
@@ -123,4 +158,3 @@ export function formatTimestamp(value) {
     // ISO 8601 UTC, seconds precision (mirrors Python isoformat(timespec="seconds")).
     return value.toISOString().replace(/\.\d{3}Z$/, "+00:00");
 }
-//# sourceMappingURL=contract.js.map

package/dist/state/startupAnalysis/helpers.js

@@ -51,7 +51,7 @@ export const THRESHOLD_WARNING_PATTERNS = [
     ],
     ["self_audit", "abstraction", "self_audit.abstraction", /abstraction creep/i],
     ["self_audit", "filler", "self_audit.filler", /\bfiller\s*:/i],
-    ["compaction", "over_limit", "compaction.uniform_10_40_50", /over(?:\s+|_)limit|uniform_10_40_50/i],
+    ["compaction", "over_limit", "compaction.uniform_10_40_50", /over(?:\s+|_)limit|uniform_(?:10_40_50|20_50_100)/i],
     ["compaction", "protected_overflow", "compaction.protected_overflow", /protected[-_ ]overflow/i],
 ];
 export const POST_AUDIT_FLAG_RE = /\[post-audit-flagged(?::[^\]]*)?\]/gi;
@@ -284,4 +284,3 @@ export function safeInt(value) {
 export function nowIsoSeconds() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00");
 }
-//# sourceMappingURL=helpers.js.map

package/dist/state/startupAnalysis/index.js

@@ -4,4 +4,3 @@ export { classifyStartupRecords } from "./records.js";
 export { STARTUP_METRICS_ENVELOPE, TOKEN_ESTIMATOR_VERSION, aggregateStartupMetrics, } from "./metrics.js";
 export { STARTUP_REPORT_MARKDOWN, STARTUP_REPORT_JSON, renderStartupReport, writeStartupReports, } from "./report.js";
 export { STARTUP_INTERMEDIATE_ENVELOPE, BENCHMARK_HISTORY_JSONL, BENCHMARK_LATEST_REPORT_JSON, BENCHMARK_LATEST_REPORT_MARKDOWN, previousBenchmarkWatermark, buildBenchmarkHistoryRow, persistStartupBenchmark, buildStartupIntermediate, buildNoRuntimeStartupIntermediate, extractStartupIntermediateFromCorpusFile, } from "./benchmark.js";
-//# sourceMappingURL=index.js.map

package/dist/state/startupAnalysis/metrics.js

@@ -338,4 +338,3 @@ export function aggregateStartupMetrics(intermediateInput) {
     }
     return result;
 }
-//# sourceMappingURL=metrics.js.map

package/dist/state/startupAnalysis/records.js

@@ -196,4 +196,3 @@ export function classifyStartupRecords(corpus, opts) {
         degradations,
     };
 }
-//# sourceMappingURL=records.js.map

package/dist/state/startupAnalysis/report.js

@@ -109,4 +109,3 @@ export function writeStartupReports(metrics, outputDir) {
 // Slice 6: benchmark persistence + intermediate building + corpus-file extraction
 // (extract_*_from_runtime_stores depends on extract_corpus and lands in Phase 10)
 // ===========================================================================
-//# sourceMappingURL=report.js.map

package/dist/state/startupAnalysis/threshold.js

@@ -38,6 +38,14 @@ export const BOUNDED_RUNTIME_REASONS = new Set([
     "store_locked",
     "store_not_directory",
     "store_unreadable",
+    // Compatibility-state reasons projected from the evidence-tier authority
+    // contract. The local-corpus pseudo-runtime reports these when a tier
+    // compatibility state prevents analysis; they must survive normalization
+    // rather than collapsing to schema_divergent.
+    "no_evidence",
+    "legacy_monolithic_state",
+    "unreadable_or_schema_divergent",
+    "oversized",
 ]);
 export function boundedRuntimeStatus(status) {
     const runtime = String(status.runtime ?? "unknown");
@@ -56,6 +64,11 @@ export function boundedRuntimeStatus(status) {
     if (Array.isArray(status.remediation_labels)) {
         item.remediation_labels = status.remediation_labels.map((l) => String(l));
     }
+    // Contract-projected recovery guidance for tier compatibility states. Passes
+    // through only when present; extraction-time runtime statuses omit it.
+    if (typeof status.recovery === "string" && status.recovery.length > 0) {
+        item.recovery = status.recovery;
+    }
     return item;
 }
 export const STATE_CLI_COMMANDS = new Set([
@@ -497,4 +510,3 @@ export function classifyThresholdEvidence(scan) {
 // ===========================================================================
 // Slice 3: startup record classification into state-gathering sequences
 // ===========================================================================
-//# sourceMappingURL=threshold.js.map

package/dist/state/startupAnalysis.js

@@ -1,3 +1,2 @@
 /** Barrel: stable import path for startup analysis (split across ./startupAnalysis/). */
 export * from "./startupAnalysis/index.js";
-//# sourceMappingURL=startupAnalysis.js.map