agentera 3.0.0-dev.72 → 3.0.0-dev.75

package/dist/cli/help.js

@@ -1,6 +1,9 @@
 import { CAPABILITY_ROUTING_NAMES } from "./commands/capability.js";
 import { verbsForArtifact, WRITABLE_ARTIFACTS } from "../state/write/operations.js";
 import { personalGlossaryOutputContract } from "../registries/glossaryEntryContract.js";
+import { personalGlossaryCandidateProjectionContract } from "../registries/glossaryCandidateProjectionContract.js";
+import { personalGlossaryCandidateDecisionContract } from "../registries/glossaryCandidateDecisionContract.js";
+import { personalGlossaryReviewRecordsContract } from "../registries/glossaryReviewRecordsContract.js";
 import { describeRouteReceipt } from "../registries/hybridRoute.js";
 import { advertisedValidateFamilyNames } from "./commands/validate.js";
 import { entityListFamilies, entityRetrievalFamilyForHelpArgs } from "../state/entityRetrievalHelp.js";
@@ -346,7 +349,7 @@ export function stateCommandNames() {
 export function printCheckHelp(sub) {
     if (sub === "verify") {
         return [
-            "usage: agentera check verify [-h] eval {skills,semantic,routing} [--format text|json] [options]",
+            "usage: agentera check verify [-h] eval {skills,semantic,routing,glossary} [--format text|json] [options]",
             "",
             "Evaluation verify gates. Smoke verify is retired on the npm self-contained CLI;",
             "use the stable Python line for smoke maintainer harnesses.",
@@ -397,6 +400,9 @@ export function printCheckHelp(sub) {
 }
 export function printReportHelp() {
     const profileGlossary = personalGlossaryOutputContract();
+    const candidateReads = personalGlossaryCandidateProjectionContract();
+    const candidateDecision = personalGlossaryCandidateDecisionContract();
+    const reviewRecords = personalGlossaryReviewRecordsContract();
     return [
         "usage: agentera report [-h] [--format {text,json}] [--project VALUE] [--sources {active,all}]",
         "                       | agentera report refresh [--dry-run|--consent local-history]",
@@ -405,13 +411,53 @@ export function printReportHelp() {
         `                       | ${profileGlossary.command} --input <file|-> [--dry-run] --format json`,
         "                       | agentera report glossary-advice --input <file|-> --format json",
         "                       | agentera report profile-grounding --format json",
+        `                       | ${candidateReads.candidateReadCommand} list [--source-family explicit|recurring]`,
+        "                         [--provenance-kind KIND] [--scope personal|ambiguous] [--limit N] [--cursor TOKEN] --format json",
+        `                       | ${candidateReads.candidateReadCommand} get --candidate-id ID --candidate-revision REVISION`,
+        "                         --generation GENERATION --policy-version POLICY --format json",
+        `                       | ${candidateDecision.command} --input <file|-> --format json`,
+        `                       | ${reviewRecords.command} queue --input <file|-> --format json`,
+        `                       | ${reviewRecords.command} disposition --input <file|-> --format json`,
+        `                       | ${reviewRecords.command} list [--status pending|terminal] [--limit N] [--cursor TOKEN] --format json`,
+        `                       | ${reviewRecords.command} get --review-id ID --candidate-id ID --candidate-revision REVISION`,
+        "                         --generation GENERATION --policy-version POLICY --format json",
         "",
         "Privacy-gated usage analytics over an existing corpus.",
         "Default analytics use --sources active and exclude historical imports.",
         "Use --sources all to include historical records with visible provenance.",
-        `Profile Full sends ${profileGlossary.requestSchemaVersion} to the exact profile path returned by prime; this subcommand requires no project checkout.`,
+        `Personal glossary publication accepts one ${profileGlossary.requestSchemaVersion} mapping with a prior CLI decision and its host receipt; this subcommand requires no project checkout.`,
         "Profile grounding reports one bounded validity object (valid, absent, or repair_needed); only valid responses include non-glossary content.",
         "Build requests bounded glossary advice through structured input; the command is read-only and does not publish or refresh state.",
+        "Personal glossary candidate reads are private, user-local, non-interactive, and read-only. They require a readable current bounded",
+        "evidence-tier generation and a projection bound to it. They never read a project glossary, refresh evidence, acquire consent,",
+        "record review state, or alter the candidate projection. List emits only summaries and bounded",
+        "projection-local abstention and coverage counts. Safe context becomes unavailable at its 30-day expiry without changing projection bytes.",
+        "Exact read returns only opaque validated occurrences and a currently available safe context.",
+        "Both forms emit JSON on stdout. Exit 0 reports a current page or exact candidate, exit 1 reports unavailable/stale state, and exit 2",
+        "reports malformed arguments. Copy a returned next_cursor exactly; it binds the collection, generation, policy, filters, limit, order,",
+        "and expiry-aware safe-context availability snapshot.",
+        `Personal glossary decisions accept either a ${candidateDecision.requestSchemaVersion} host receipt or a ${candidateDecision.receiptConstructionRequestSchemaVersion}`,
+        "classification with exact candidate bindings. The CLI binds it to the current private projection, current evidence, and quality",
+        "gate, then emits automatic_admission, review_required, or abstain. The classification form constructs and returns its receipt.",
+        "It never writes a review, profile, project glossary, candidate projection, or project state. Host confidence cannot enable",
+        "inferred automatic admission.",
+        "Personal glossary publication consumes a current explicit automatic admission, or one current accepted/corrected review authorization.",
+        "Immediately before changing the owned PROFILE.md Glossary section, it revalidates the current candidate, projection, receipt,",
+        "decision, explicit user-authored evidence, policy, quality gate, scope, meaning, and revision. It never accepts a profile path,",
+        "reads a project glossary, or echoes candidate content. Accepted/corrected review publication revalidates the same current",
+        "projection, receipt, decision, evidence, policy, scope, meaning, and revision before the profile effect.",
+        "Personal glossary reviews queue only a current review_required decision. Disposition accepts only a fresh signed current-user",
+        "agentera-local-host IPC approval verified by the configured user-local Ed25519 public key. It records accept, correct, reject,",
+        "or defer without changing a profile entry, project state, candidate projection, or publication. Accept/correct returns only an",
+        "opaque authorization for the separate publish command. Exact approval replay is idempotent and conflicting nonce reuse fails.",
+        "Canonical v1 pending stores remain readable without mutation; only disposition revalidates and migrates one valid v1 record",
+        "to v2, deriving its missing scope from the current validated host receipt. Invalid or ambiguous v1 input has no effects.",
+        "Rejected and deferred records suppress a recurrence with the same stable identity, semantic fingerprint, scope, and policy.",
+        "Meaning, scope, or policy changes requeue with a visible reopening reason. List and exact reads emit only opaque bindings,",
+        "a stable reason, lifecycle dates, status, disposition, and reopening reason. They require the configured",
+        "current-user owner and current candidate-projection binding, use opaque snapshot cursors, and never return terms, meanings,",
+        "evidence, source, session, project, path, tool, or approval material. Terminal review metadata expires after 90 days through",
+        "separate authenticated owner maintenance; reads never perform maintenance.",
         "",
         "Corpus extraction flags (report refresh with --consent local-history):",
         "  These flags deselect runtimes that would otherwise be included when their",

package/dist/cli/migrationRequired.js

@@ -20,7 +20,10 @@ export function requiresCompletedEntityCutover(argv) {
     const [command, subcommand, verb] = argv;
     if (["--version", "version", "app-home", "doctor", "schema", "route", "upgrade"].includes(command))
         return false;
-    if (command === "report" && ["profile-glossary", "profile-grounding"].includes(subcommand))
+    if (command === "report" &&
+        ["personal-glossary-publish", "profile-grounding", "personal-glossary-candidates", "personal-glossary-decision", "personal-glossary-reviews"].includes(subcommand))
+        return false;
+    if (command === "check" && subcommand === "verify" && verb === "eval" && argv[3] === "glossary")
         return false;
     if (command === "prime" && (argv.includes("--guidance") || !argv.includes("--context") || value(argv, "--context") === "status"))
         return false;

package/dist/core/atomicWriter.js

@@ -1,11 +1,14 @@
 import fs from "node:fs";
-export function writeFileAtomic(target, data, encoding = "utf8") {
+export function writeFileAtomic(target, data, encoding = "utf8", options = {}) {
+    const targetMode = options.preserveTargetMode ? fs.statSync(target).mode & 0o777 : undefined;
     const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
     try {
         if (Buffer.isBuffer(data))
             fs.writeFileSync(tmp, data);
         else
             fs.writeFileSync(tmp, data, encoding);
+        if (targetMode !== undefined)
+            fs.chmodSync(tmp, targetMode);
         fs.renameSync(tmp, target);
     }
     catch (err) {

package/dist/core/developmentInvocation.js

@@ -46,11 +46,14 @@ function developmentCommand(argumentsText) {
 }
 const profileGroundingCommand = developmentCommand("report profile-grounding --format json");
 const GLOSSARY_PROJECTIONS = {
-    "profile_output.command": developmentCommand("report profile-glossary"),
+    "profile_output.command": developmentCommand("report personal-glossary-publish"),
     "profile_grounding.command": profileGroundingCommand,
     "profile_grounding.repair": `Use the Profile capability to repair or regenerate PROFILE.md, then retry \`${profileGroundingCommand}\`; no profile bytes were changed.`,
     "profile_grounding.absent": `Use the Profile capability to generate PROFILE.md, then retry ${profileGroundingCommand}.`,
     "advice.command": developmentCommand("report glossary-advice --input REQUEST --format json"),
+    "candidate_retrieval.command": developmentCommand("report personal-glossary-candidates"),
+    "candidate_decision.command": developmentCommand("report personal-glossary-decision"),
+    "review_records.command": developmentCommand("report personal-glossary-reviews"),
 };
 function invalid(reason) {
     throw new Error(`invalid development command projection: ${reason}`);

package/dist/core/yaml.js

@@ -1,5 +1,34 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import YAML from "yaml";
+const MAX_MAPPING_CACHE_ENTRIES = 64;
+let activeMappingCache = null;
+/** Run synchronous work with a bounded, content-invalidated YAML mapping cache. */
+export function withYamlMappingCache(run) {
+    return withActiveYamlMappingCache(run, false);
+}
+/** Share frozen YAML mappings only inside one trusted read-only operation. */
+export function withReadOnlyYamlMappingCache(run) {
+    return withActiveYamlMappingCache(run, true);
+}
+function withActiveYamlMappingCache(run, readOnly) {
+    const previous = activeMappingCache;
+    activeMappingCache = { entries: new Map(), readOnly };
+    try {
+        return run();
+    }
+    finally {
+        activeMappingCache = previous;
+    }
+}
+function freezeYamlValue(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object" || seen.has(value))
+        return;
+    seen.add(value);
+    for (const child of Object.values(value))
+        freezeYamlValue(child, seen);
+    Object.freeze(value);
+}
 /**
  * Parse YAML text as a mapping. Empty/whitespace-only documents return `{}`.
  * Non-mapping roots throw. Faithful port of `scripts/yaml_mapping.py`.
@@ -16,7 +45,30 @@ export function loadYamlMapping(text) {
 }
 /** Read `path` and parse it with {@link loadYamlMapping}. */
 export function loadYamlMappingFile(path) {
-    return loadYamlMapping(fs.readFileSync(path, "utf8"));
+    const cache = activeMappingCache;
+    if (cache === null)
+        return loadYamlMapping(fs.readFileSync(path, "utf8"));
+    // One synchronous operation sees a stable frozen authority snapshot.
+    // A fresh scope still fingerprints its current bytes before reuse.
+    if (cache.readOnly) {
+        const cached = cache.entries.get(path);
+        if (cached)
+            return cached.value;
+    }
+    const text = fs.readFileSync(path, "utf8");
+    const digest = crypto.createHash("sha256").update(text).digest("hex");
+    // A digest check preserves fresh authority reads while avoiding repeated parses.
+    const cached = cache.entries.get(path);
+    if (cached?.digest === digest)
+        return cache.readOnly ? cached.value : structuredClone(cached.value);
+    const value = loadYamlMapping(text);
+    if (cache.readOnly)
+        freezeYamlValue(value);
+    cache.entries.set(path, { digest, value });
+    if (cache.entries.size > MAX_MAPPING_CACHE_ENTRIES) {
+        cache.entries.delete(cache.entries.keys().next().value);
+    }
+    return cache.readOnly ? value : structuredClone(value);
 }
 /** Parse arbitrary YAML (any root type). */
 export function parseYaml(text) {