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

package/dist/analytics/personalGlossaryProfile.js

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import { loadProfileDecayParameters } from "../capabilities/profile/instructions.js";
+import { writeFileAtomic } from "../core/atomicWriter.js";
+import { GlossaryEntryBoundError, validateGlossaryEntry, } from "../registries/glossaryEntryContract.js";
+import { unicodeCaselessExact } from "../registries/glossaryTermIdentity.js";
+const START = "<!-- agentera:personal-glossary:start -->";
+const END = "<!-- agentera:personal-glossary:end -->";
+const HEADING = "## Glossary";
+const SCHEMA_VERSION = "agentera.personalGlossarySection.v1";
+const DECAY = loadProfileDecayParameters();
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function calendarDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        throw new Error(`expected ISO calendar date, received '${value}'`);
+    const date = new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== value) {
+        throw new Error(`expected ISO calendar date, received '${value}'`);
+    }
+    return date;
+}
+function daysBetween(from, to) {
+    const days = (calendarDate(to).getTime() - calendarDate(from).getTime()) / 86_400_000;
+    if (days < 0)
+        throw new Error(`as_of ${to} precedes last_confirmed_at ${from}`);
+    return days;
+}
+function count(text, token) {
+    return text.split(token).length - 1;
+}
+function persistedContext(entry) {
+    const retained = new Map();
+    for (const evidence of entry.provenance.evidence) {
+        retained.set(evidence.evidence_anchor, {
+            sourceId: evidence.source_id,
+            sourceKind: "source_kind" in evidence ? evidence.source_kind : "conversation_turn",
+            signalType: "signal_type" in evidence ? evidence.signal_type : "instruction",
+        });
+    }
+    return { retainedHistory: retained };
+}
+function validateEntry(entry, context) {
+    const errors = validateGlossaryEntry(entry, "personal", context);
+    if (errors.length > 0)
+        throw new Error(`invalid personal glossary entry '${String(entry.term)}': ${errors.join("; ")}`);
+}
+function validateUnique(entries, label) {
+    for (const [index, entry] of entries.entries()) {
+        if (entries.slice(0, index).some((candidate) => unicodeCaselessExact(candidate.term, entry.term))) {
+            throw new Error(`${label} contains duplicate Unicode caseless-exact term '${entry.term}'`);
+        }
+    }
+}
+function matchingIndex(entries, term) {
+    return entries.findIndex((entry) => unicodeCaselessExact(entry.term, term));
+}
+function confidenceBasisFor(document, term) {
+    const key = Object.keys(document.confidence_basis).find((candidate) => unicodeCaselessExact(candidate, term));
+    return key === undefined ? Number.NaN : document.confidence_basis[key];
+}
+function parseSection(profile, maxEntries = Number.POSITIVE_INFINITY) {
+    const starts = count(profile, START);
+    const ends = count(profile, END);
+    const headings = [...profile.matchAll(/^## Glossary\s*$/gm)].length;
+    if (starts === 0 && ends === 0 && headings === 0)
+        return { document: null, start: -1, end: -1 };
+    if (starts > 1 || ends > 1 || headings > 1 || (headings > 0 && starts === 0 && ends === 0))
+        throw new PersonalGlossaryBoundaryError("ambiguous");
+    if (starts !== 1 || ends !== 1 || headings !== 1)
+        throw new PersonalGlossaryBoundaryError("malformed");
+    const start = profile.indexOf(START);
+    const end = profile.indexOf(END, start) + END.length;
+    if (start < 0 || end < END.length || end <= start)
+        throw new Error("PROFILE.md Glossary section has malformed or ambiguous owned boundaries");
+    const owned = profile.slice(start, end);
+    const newline = "\\r?\\n";
+    const match = new RegExp(`^${START}${newline}${HEADING}${newline}${newline}\`\`\`json${newline}([\\s\\S]+)${newline}\`\`\`${newline}${END}$`).exec(owned);
+    if (!match)
+        throw new Error("PROFILE.md Glossary section is malformed");
+    let value;
+    try {
+        value = JSON.parse(match[1]);
+    }
+    catch {
+        throw new Error("PROFILE.md Glossary section contains invalid JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("PROFILE.md Glossary section document is malformed");
+    const document = value;
+    if (JSON.stringify(Object.keys(document)) !== JSON.stringify(["schema_version", "as_of", "confidence_basis", "entries"]) || document.schema_version !== SCHEMA_VERSION || !Array.isArray(document.entries) || !document.confidence_basis || typeof document.confidence_basis !== "object" || Array.isArray(document.confidence_basis)) {
+        throw new Error("PROFILE.md Glossary section document is malformed");
+    }
+    if (document.entries.length > maxEntries)
+        throw new GlossaryEntryBoundError("personal glossary exceeds the consumer entry bound");
+    calendarDate(document.as_of);
+    validateUnique(document.entries, "existing personal glossary");
+    const basisKeys = Object.keys(document.confidence_basis);
+    if (basisKeys.length !== document.entries.length || basisKeys.some((key, index) => basisKeys.slice(0, index).some((candidate) => unicodeCaselessExact(candidate, key)) || matchingIndex(document.entries, key) < 0)) {
+        throw new Error("PROFILE.md Glossary section confidence basis is malformed");
+    }
+    for (const entry of document.entries) {
+        validateEntry(entry, persistedContext(entry));
+        const basis = confidenceBasisFor(document, entry.term);
+        if (!Number.isInteger(basis) || basis < 0 || basis > 100)
+            throw new Error("PROFILE.md Glossary section confidence basis is malformed");
+        daysBetween(entry.temporal.last_confirmed_at, document.as_of);
+    }
+    return { document, start, end };
+}
+export class PersonalGlossaryBoundaryError extends Error {
+    availability;
+    constructor(availability) {
+        super("PROFILE.md Glossary section has malformed or ambiguous owned boundaries");
+        this.availability = availability;
+    }
+}
+/** Parse only the owned glossary range and project only consumer-safe fields. */
+export function personalGlossaryConsumerEntries(profile, maxEntries) {
+    const document = parseSection(profile, maxEntries).document;
+    return document?.entries.map(({ term, meaning }) => ({ term, meaning })) ?? null;
+}
+/** Return profile grounding with the validated owned glossary range excluded byte-for-byte. */
+export function personalProfileGrounding(profile) {
+    const section = parseSection(profile);
+    return section.document === null
+        ? profile
+        : `${profile.slice(0, section.start)}${profile.slice(section.end)}`;
+}
+function orderedEntry(entry) {
+    return {
+        term: entry.term,
+        meaning: entry.meaning,
+        confidence: entry.confidence,
+        permanence: entry.permanence,
+        temporal: {
+            observed_at: entry.temporal.observed_at,
+            last_confirmed_at: entry.temporal.last_confirmed_at,
+        },
+        provenance: {
+            kind: entry.provenance.kind,
+            evidence: entry.provenance.evidence.map((item) => ({ ...item })),
+        },
+    };
+}
+function render(document) {
+    return `${START}\n${HEADING}\n\n\`\`\`json\n${JSON.stringify(document, null, 2)}\n\`\`\`\n${END}`;
+}
+export function updatePersonalGlossaryProfile(input) {
+    calendarDate(input.asOf);
+    const original = fs.readFileSync(input.profilePath, "utf8");
+    const section = parseSection(original);
+    if (section.document && calendarDate(input.asOf).getTime() < calendarDate(section.document.as_of).getTime()) {
+        throw new Error("personal glossary as_of cannot move backward");
+    }
+    validateUnique(input.freshEntries, "fresh personal glossary evidence");
+    for (const entry of input.freshEntries)
+        validateEntry(entry, input.retainedHistory);
+    const fresh = input.freshEntries;
+    const established = section.document?.entries ?? [];
+    const merged = [];
+    const confidenceBasis = new Map();
+    const usedFresh = new Set();
+    for (const previous of established) {
+        const freshIndex = matchingIndex(fresh, previous.term);
+        const current = freshIndex >= 0 ? fresh[freshIndex] : undefined;
+        if (freshIndex >= 0)
+            usedFresh.add(freshIndex);
+        let entry;
+        let entryBasis;
+        if (current) {
+            if (previous.meaning !== current.meaning || previous.provenance.kind !== current.provenance.kind) {
+                throw new Error(`personal glossary conflict for established term '${previous.term}'`);
+            }
+            daysBetween(previous.temporal.last_confirmed_at, input.asOf);
+            entryBasis = current.confidence;
+            entry = orderedEntry({
+                ...current,
+                term: previous.term,
+                permanence: previous.permanence,
+                temporal: { observed_at: previous.temporal.observed_at, last_confirmed_at: input.asOf },
+            });
+        }
+        else {
+            entryBasis = confidenceBasisFor(section.document, previous.term);
+            const days = daysBetween(previous.temporal.last_confirmed_at, input.asOf);
+            entry = orderedEntry({
+                ...previous,
+                confidence: Math.max(DECAY.floor, Math.round(entryBasis * Math.exp(-DECAY.lambdas[previous.permanence] * days))),
+            });
+        }
+        merged.push(entry);
+        confidenceBasis.set(entry.term, entryBasis);
+    }
+    for (const [index, current] of fresh.entries()) {
+        if (usedFresh.has(index))
+            continue;
+        const entryBasis = current.confidence;
+        if (calendarDate(current.temporal.observed_at).getTime() > calendarDate(input.asOf).getTime())
+            throw new Error(`observed_at for '${current.term}' is after as_of`);
+        const entry = orderedEntry({
+            ...current,
+            temporal: { observed_at: current.temporal.observed_at, last_confirmed_at: input.asOf },
+        });
+        merged.push(entry);
+        confidenceBasis.set(entry.term, entryBasis);
+    }
+    merged.sort((left, right) => compareText(left.term, right.term));
+    const orderedBasis = Object.fromEntries(merged.map((entry) => [entry.term, confidenceBasis.get(entry.term)]));
+    const document = { schema_version: SCHEMA_VERSION, as_of: input.asOf, confidence_basis: orderedBasis, entries: merged };
+    const rendered = render(document);
+    const candidate = section.document
+        ? `${original.slice(0, section.start)}${rendered}${original.slice(section.end)}`
+        : `${original}${original.endsWith("\n") ? "\n" : "\n\n"}${rendered}\n`;
+    const changed = candidate !== original;
+    if (changed && !input.dryRun)
+        writeFileAtomic(input.profilePath, candidate);
+    return { changed, profilePath: input.profilePath, entries: merged };
+}

package/dist/analytics/profileSignals.js

@@ -0,0 +1,211 @@
+import path from "node:path";
+import { PROFILE_SIGNAL_TYPES, profileSufficiency, } from "../registries/evidenceTierContract.js";
+import { readCurrentPointer, readSignalTier, resolveEvidenceAnchor, } from "./extractCorpus/evidenceTiers.js";
+import { assessTiers, recoveryForState, resolveTiersDir, } from "./extractCorpus/tierReader.js";
+const PROFILE_TYPES_SET = new Set(PROFILE_SIGNAL_TYPES);
+/** Resolve the absolute signal tier file path from the current generation. */
+function signalTierPath(tiersDir) {
+    const pointer = readCurrentPointer(tiersDir);
+    if (!pointer)
+        return null;
+    return path.join(tiersDir, "generations", pointer.generation, "signal.json");
+}
+/** Resolve the co-located corpus path for legacy compatibility assessment. */
+function corpusPathFromTiersDir(tiersDir) {
+    const idx = tiersDir.lastIndexOf(path.sep + "tiers");
+    if (idx === -1)
+        return undefined;
+    return path.join(tiersDir.slice(0, idx), "corpus.json");
+}
+/**
+ * Assess whether the retained profile-relevant signal distribution is
+ * sufficient against the contract threshold. The prior intended distribution
+ * is reconstructed from the signal tier's selection report (total per
+ * family); the retained distribution from the published signal records.
+ * No separate full-corpus read is needed — the selection report carries both.
+ *
+ * When the tier is uncapped, retained == total, so the bounded and intended
+ * distributions are identical and sufficiency is trivially met. When capped,
+ * the selection report's per-family total/retained is the authoritative prior
+ * distribution; the profile-relevant intended count is scaled from the
+ * retained profile-relevant count by the family's overall retention ratio.
+ */
+export function assessProfileSufficiency(selection, signals, contractPath) {
+    const suff = profileSufficiency(contractPath);
+    const threshold = suff.minimumFamilyRetention;
+    const profileRetainedPerFamily = new Map();
+    for (const sig of signals) {
+        const family = sig.source_product || "unknown";
+        profileRetainedPerFamily.set(family, (profileRetainedPerFamily.get(family) ?? 0) + 1);
+    }
+    const profileIntendedPerFamily = new Map();
+    if (!selection.capped) {
+        // Uncapped: retained == intended, so the retained counts ARE the intended.
+        for (const [family, retained] of profileRetainedPerFamily) {
+            profileIntendedPerFamily.set(family, retained);
+        }
+    }
+    else {
+        // Capped: the selection report's per_family is the authoritative source
+        // of which families had records. For families with profile-relevant
+        // retained signals, scale the intended count by the family's overall
+        // retention ratio. For families where all records were capped
+        // (retained=0, total>0), flag them as insufficient — no data survived
+        // to contribute to the profile.
+        for (const sel of selection.per_family) {
+            if (sel.total === 0)
+                continue;
+            const profileRetained = profileRetainedPerFamily.get(sel.family) ?? 0;
+            if (sel.retained > 0 && profileRetained > 0) {
+                profileIntendedPerFamily.set(sel.family, Math.round(profileRetained * (sel.total / sel.retained)));
+            }
+            else if (sel.retained === 0 && sel.total > 0) {
+                // All records for this family were capped — insufficient by definition.
+                profileIntendedPerFamily.set(sel.family, sel.total);
+            }
+            // If sel.retained > 0 but profileRetained == 0, the family's retained
+            // records were simply non-profile-relevant; leave it as sufficient.
+        }
+        // Also include any family that appears in retained signals but not in the
+        // selection report (should not normally happen, but handle gracefully).
+        for (const [family, retained] of profileRetainedPerFamily) {
+            if (!profileIntendedPerFamily.has(family)) {
+                profileIntendedPerFamily.set(family, retained);
+            }
+        }
+    }
+    const perFamily = [];
+    const allFamilies = new Set([...profileIntendedPerFamily.keys(), ...profileRetainedPerFamily.keys()]);
+    for (const family of [...allFamilies].sort()) {
+        const intended = profileIntendedPerFamily.get(family) ?? 0;
+        const retained = profileRetainedPerFamily.get(family) ?? 0;
+        const retention = intended > 0 ? retained / intended : 1;
+        const sufficient = intended === 0 || retention >= threshold;
+        perFamily.push({ family, intended, retained, retention, sufficient });
+    }
+    const insufficientFamilies = perFamily.filter((f) => !f.sufficient);
+    const sufficient = !selection.capped || insufficientFamilies.length === 0;
+    const reason = sufficient
+        ? selection.capped
+            ? "signal tier capped but per-family retention meets threshold"
+            : "signal tier uncapped; bounded and intended distributions identical"
+        : `insufficient retention for families: ${insufficientFamilies.map((f) => `${f.family} (${f.retained}/${f.intended}, ${(f.retention * 100).toFixed(0)}%)`).join(", ")}`;
+    return { sufficient, reason, threshold, capped: selection.capped, per_family: perFamily };
+}
+/**
+ * Read the bounded signal tier and return profile-relevant signals with a
+ * sufficiency assessment. This is the bounded profile-synthesis input: it
+ * loads only the signal tier (bounded by construction), never the full-
+ * evidence shards. Each signal's `evidence_anchor` resolves to retained full
+ * evidence via resolveProfileEvidence.
+ */
+export function readProfileSignals(tiersDir, corpusPath, contractPath) {
+    const assessment = assessTiers(tiersDir, corpusPath);
+    const recovery = recoveryForState(assessment.state);
+    const threshold = profileSufficiency(contractPath).minimumFamilyRetention;
+    if (!assessment.analyzable) {
+        return {
+            state: assessment.state,
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signals: [],
+            profile_signal_count: 0,
+            sufficiency: {
+                sufficient: false,
+                reason: assessment.state === "missing"
+                    ? "no evidence tiers published"
+                    : assessment.state === "legacy"
+                        ? "legacy monolithic state; refresh required"
+                        : `tier state ${assessment.state}; ${recovery ?? "recovery unavailable"}`,
+                threshold,
+                capped: false,
+                per_family: [],
+            },
+            recovery,
+        };
+    }
+    const tier = readSignalTier(tiersDir);
+    if (!tier) {
+        return {
+            state: "corrupt",
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signals: [],
+            profile_signal_count: 0,
+            sufficiency: {
+                sufficient: false,
+                reason: "signal tier unreadable or not found",
+                threshold,
+                capped: false,
+                per_family: [],
+            },
+            recovery,
+        };
+    }
+    const profileSignals = tier.records.filter((s) => PROFILE_TYPES_SET.has(s.signal_type));
+    const sufficiency = assessProfileSufficiency(tier.manifest.signal.selection, profileSignals, contractPath);
+    return {
+        state: assessment.state,
+        tiers_dir: tiersDir,
+        signal_path: signalTierPath(tiersDir),
+        signals: profileSignals,
+        profile_signal_count: profileSignals.length,
+        sufficiency,
+        recovery,
+    };
+}
+/**
+ * Resolve a synthesized claim's evidence anchor to its retained full-evidence
+ * record. Loads only the owning shard, never the whole tier. Returns null
+ * when the anchor does not resolve (the claim cannot be checked).
+ */
+export function resolveProfileEvidence(anchor, tiersDir) {
+    return resolveEvidenceAnchor(anchor, tiersDir);
+}
+/**
+ * Lightweight status for profile_context — assesses the tiers, reads the
+ * signal tier, and computes sufficiency. The signal records are counted but
+ * not returned in the status payload (the synthesis step reads them via
+ * readProfileSignals or the signal_path). This status tells the agent
+ * whether synthesis can proceed and where to read.
+ */
+export function profileSignalsStatus(env = process.env, platform = process.platform, contractPath) {
+    const tiersDir = resolveTiersDir(env, platform);
+    const corpusPath = corpusPathFromTiersDir(tiersDir);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    const recovery = recoveryForState(assessment.state);
+    if (!assessment.analyzable) {
+        return {
+            state: assessment.state,
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signal_count: 0,
+            profile_signal_count: 0,
+            sufficiency: null,
+            recovery,
+        };
+    }
+    const tier = readSignalTier(tiersDir);
+    if (!tier) {
+        return {
+            state: "corrupt",
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signal_count: 0,
+            profile_signal_count: 0,
+            sufficiency: null,
+            recovery,
+        };
+    }
+    const profileSignals = tier.records.filter((s) => PROFILE_TYPES_SET.has(s.signal_type));
+    const sufficiency = assessProfileSufficiency(tier.manifest.signal.selection, profileSignals, contractPath);
+    return {
+        state: assessment.state,
+        tiers_dir: tiersDir,
+        signal_path: signalTierPath(tiersDir),
+        signal_count: tier.records.length,
+        profile_signal_count: profileSignals.length,
+        sufficiency,
+        recovery,
+    };
+}