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

package/dist/analytics/glossaryInputAcquisition.js

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+import { personalGlossaryConsumerEntries, PersonalGlossaryBoundaryError, } from "./personalGlossaryProfile.js";
+import { glossaryAcquisitionContract, GlossaryEntryBoundError, } from "../registries/glossaryEntryContract.js";
+import { docsPathOverridesFromBytes, loadArtifactRecord, resolveArtifactPath, } from "../registries/artifactRegistry.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "../registries/artifactProtocolIds.js";
+import { assertValidatedProjectRoot, validateRealProjectRoot, } from "../state/projectRoot.js";
+import { parseProjectGlossaryDocument } from "../state/write/glossaryPublication.js";
+const PROJECT_RECOVERY = "Repair the canonical GLOSSARY.md artifact or docs mapping, then run agentera state query --list-artifacts before retrying glossary acquisition.";
+const PERSONAL_RECOVERY = "Run agentera profile to repair or regenerate the owned Glossary section, then retry glossary acquisition.";
+function valid(owner, availability, entries) {
+    return {
+        owner,
+        availability,
+        entries,
+        gap_proving: owner === "project" && availability !== "valid_present",
+        diagnostic: null,
+    };
+}
+function invalid(owner, availability) {
+    return {
+        owner,
+        availability,
+        entries: [],
+        gap_proving: false,
+        diagnostic: {
+            class: availability,
+            recovery: owner === "project" ? PROJECT_RECOVERY : PERSONAL_RECOVERY,
+        },
+    };
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function readBoundedRegularFile(pathname, maxBytes) {
+    let before;
+    try {
+        before = fs.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        return errorCode(error) === "ENOENT" ? { status: "absent" } : { status: "unreadable" };
+    }
+    if (before.isSymbolicLink() || !before.isFile())
+        return { status: "ambiguous" };
+    const noFollow = fs.constants.O_NOFOLLOW;
+    if (noFollow === undefined)
+        return { status: "ambiguous" };
+    let descriptor;
+    try {
+        descriptor = fs.openSync(pathname, fs.constants.O_RDONLY | noFollow);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "ENOENT" || code === "ELOOP")
+            return { status: "ambiguous" };
+        return { status: "unreadable" };
+    }
+    try {
+        const opened = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameIdentity(before, opened) || !opened.isFile())
+            return { status: "ambiguous" };
+        if (opened.size > BigInt(maxBytes))
+            return { status: "over_bound" };
+        const bytes = readDescriptorBounded(descriptor, maxBytes);
+        if (bytes === null)
+            return { status: "over_bound" };
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        const current = fs.lstatSync(pathname, { bigint: true });
+        if (!sameFileSnapshot(opened, after) || !sameIdentity(opened, current)) {
+            return { status: "ambiguous" };
+        }
+        return { status: "ok", bytes };
+    }
+    catch {
+        return { status: "unreadable" };
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameFileSnapshot(left, right) {
+    return (sameIdentity(left, right) &&
+        left.isFile() &&
+        right.isFile() &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function readDescriptorBounded(descriptor, maxBytes) {
+    const candidate = Buffer.alloc(maxBytes + 1);
+    let offset = 0;
+    while (offset < candidate.byteLength) {
+        const count = fs.readSync(descriptor, candidate, offset, candidate.byteLength - offset, null);
+        if (count === 0)
+            break;
+        offset += count;
+    }
+    return offset > maxBytes ? null : candidate.subarray(0, offset);
+}
+function identitiesStable(identities) {
+    return identities.every((identity) => {
+        try {
+            const current = fs.lstatSync(identity.pathname, { bigint: true });
+            return (current.dev === identity.dev &&
+                current.ino === identity.ino &&
+                (identity.type === "directory" ? current.isDirectory() : current.isFile()) &&
+                !current.isSymbolicLink());
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function readStableProjectFile(root, pathname, maxBytes, kind, hooks) {
+    assertValidatedProjectRoot(root);
+    const relative = path.relative(root.path, pathname);
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return { status: "ambiguous" };
+    }
+    const identities = [];
+    let current = root.path;
+    const segments = relative.split(path.sep).filter(Boolean);
+    for (const [index, segment] of segments.entries()) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = fs.lstatSync(current, { bigint: true });
+        }
+        catch (error) {
+            if (errorCode(error) !== "ENOENT")
+                return { status: "unreadable" };
+            try {
+                hooks.afterPathSnapshot?.(kind);
+            }
+            catch {
+                return { status: "ambiguous" };
+            }
+            if (!identitiesStable(identities))
+                return { status: "ambiguous" };
+            try {
+                fs.lstatSync(current);
+                return { status: "ambiguous" };
+            }
+            catch (missingError) {
+                if (errorCode(missingError) !== "ENOENT")
+                    return { status: "ambiguous" };
+                try {
+                    assertValidatedProjectRoot(root);
+                }
+                catch {
+                    return { status: "ambiguous" };
+                }
+                return { status: "absent" };
+            }
+        }
+        if (stat.isSymbolicLink())
+            return { status: "ambiguous" };
+        const type = index === segments.length - 1 ? "file" : "directory";
+        if ((type === "file" && !stat.isFile()) || (type === "directory" && !stat.isDirectory())) {
+            return { status: "ambiguous" };
+        }
+        identities.push({ pathname: current, dev: stat.dev, ino: stat.ino, type });
+    }
+    try {
+        hooks.afterPathSnapshot?.(kind);
+    }
+    catch {
+        return { status: "ambiguous" };
+    }
+    const noFollow = fs.constants.O_NOFOLLOW;
+    if (noFollow === undefined)
+        return { status: "ambiguous" };
+    let descriptor;
+    try {
+        descriptor = fs.openSync(pathname, fs.constants.O_RDONLY | noFollow);
+        const opened = fs.fstatSync(descriptor, { bigint: true });
+        const leaf = identities.at(-1);
+        if (!opened.isFile() ||
+            opened.dev !== leaf.dev ||
+            opened.ino !== leaf.ino ||
+            !identitiesStable(identities)) {
+            return { status: "ambiguous" };
+        }
+        if (opened.size > BigInt(maxBytes))
+            return { status: "over_bound" };
+        const bytes = readDescriptorBounded(descriptor, maxBytes);
+        if (bytes === null)
+            return { status: "over_bound" };
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (!sameFileSnapshot(opened, after) || !identitiesStable(identities)) {
+            return { status: "ambiguous" };
+        }
+        assertValidatedProjectRoot(root);
+        return { status: "ok", bytes };
+    }
+    catch (error) {
+        const code = errorCode(error);
+        return code === "EACCES" || code === "EPERM"
+            ? { status: "unreadable" }
+            : { status: "ambiguous" };
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch {
+                /* A failed close cannot make rejected bytes authoritative. */
+            }
+        }
+    }
+}
+function decodeUtf8(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+export function acquireProjectGlossaryInput(projectRoot, hooks = {}) {
+    const bounds = glossaryAcquisitionContract();
+    let root;
+    let pathname;
+    try {
+        root = validateRealProjectRoot(projectRoot);
+        const record = loadArtifactRecord("glossary");
+        if (!record)
+            return invalid("project", "ambiguous");
+        const docsPath = path.join(root.path, ARTIFACT_PROTOCOL_PATHS.docs);
+        const docsSource = readStableProjectFile(root, docsPath, bounds.maxSourceUtf8Bytes, "docs_override", hooks);
+        if (docsSource.status !== "ok" && docsSource.status !== "absent") {
+            return invalid("project", "ambiguous");
+        }
+        let docsPathOverrides = {};
+        if (docsSource.status === "ok") {
+            const decoded = decodeUtf8(docsSource.bytes);
+            if (decoded === null)
+                return invalid("project", "ambiguous");
+            try {
+                docsPathOverrides = docsPathOverridesFromBytes(decoded, true);
+            }
+            catch {
+                return invalid("project", "ambiguous");
+            }
+        }
+        pathname = resolveArtifactPath(record, root.path, { strictWrite: true, docsPathOverrides });
+        assertValidatedProjectRoot(root);
+    }
+    catch {
+        return invalid("project", "ambiguous");
+    }
+    const source = readStableProjectFile(root, pathname, bounds.maxSourceUtf8Bytes, "glossary_target", hooks);
+    if (source.status === "absent")
+        return valid("project", "absent", []);
+    if (source.status !== "ok")
+        return invalid("project", source.status);
+    try {
+        assertValidatedProjectRoot(root);
+        const decoded = decodeUtf8(source.bytes);
+        if (decoded === null)
+            return invalid("project", "malformed");
+        const document = parseProjectGlossaryDocument(decoded, bounds.maxEntries);
+        assertValidatedProjectRoot(root);
+        const entries = document.entries.map((entry) => ({
+            term: String(entry.term),
+            meaning: String(entry.meaning),
+            owner: "project",
+        }));
+        return valid("project", entries.length === 0 ? "valid_empty" : "valid_present", entries);
+    }
+    catch (error) {
+        return invalid("project", error instanceof GlossaryEntryBoundError ? "over_bound" : "malformed");
+    }
+}
+export function acquirePersonalGlossaryInput(profilePath) {
+    const bounds = glossaryAcquisitionContract();
+    const source = readBoundedRegularFile(profilePath, bounds.maxSourceUtf8Bytes);
+    if (source.status === "absent")
+        return valid("personal", "absent", []);
+    if (source.status !== "ok")
+        return invalid("personal", source.status);
+    try {
+        const decoded = decodeUtf8(source.bytes);
+        if (decoded === null)
+            return invalid("personal", "malformed");
+        const parsed = personalGlossaryConsumerEntries(decoded, bounds.maxEntries);
+        if (parsed === null)
+            return valid("personal", "absent", []);
+        const entries = parsed.map(({ term, meaning }) => ({
+            term,
+            meaning,
+            owner: "personal",
+        }));
+        return valid("personal", entries.length === 0 ? "valid_empty" : "valid_present", entries);
+    }
+    catch (error) {
+        if (error instanceof GlossaryEntryBoundError)
+            return invalid("personal", "over_bound");
+        if (error instanceof PersonalGlossaryBoundaryError)
+            return invalid("personal", error.availability);
+        return invalid("personal", "malformed");
+    }
+}
+export function acquireGlossaryInputs(projectRoot, personalProfilePath, projectHooks = {}) {
+    return {
+        project: acquireProjectGlossaryInput(projectRoot, projectHooks),
+        personal: acquirePersonalGlossaryInput(personalProfilePath),
+    };
+}

package/dist/analytics/personalGlossaryAdmission.js

@@ -0,0 +1,133 @@
+import { personalGlossaryAdmissionContract } from "../registries/glossaryEntryContract.js";
+import { readSignalTier, resolveEvidenceAnchor, } from "./extractCorpus/evidenceTiers.js";
+import { assessTiers, recoveryForState } from "./extractCorpus/tierReader.js";
+function trimMeaning(value) {
+    return value
+        .trim()
+        .replace(/[.!?]+$/, "")
+        .trim();
+}
+/** Classify only authority-supported explicit correction or clarification forms. */
+export function classifyExplicitGlossaryLanguage(text) {
+    const correction = /\b(?:actually|not quite|instead|correction)\b[^`"']*([`"'])([^`"']+)\1\s+means\s+(.+)$/i.exec(text);
+    const clarification = /\bto clarify\b.*?\bprefer\s+([`"'])([^`"']+)\1\s+to mean\s+(.+)$/i.exec(text);
+    const match = correction ?? clarification;
+    if (!match)
+        return null;
+    const term = match[2].trim();
+    const meaning = trimMeaning(match[3]);
+    return term && meaning ? { term, meaning } : null;
+}
+function recordText(record) {
+    const data = record.data;
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return "";
+    const object = data;
+    for (const field of ["text", "prompt", "content"]) {
+        if (typeof object[field] === "string")
+            return object[field];
+    }
+    return "";
+}
+function semanticValues(record) {
+    const data = record.data;
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const object = data;
+    if (record.source_kind === "instruction_document") {
+        return typeof object.content === "string" ? [object.content] : [];
+    }
+    if (record.source_kind === "project_config_signal") {
+        return Array.isArray(object.signals)
+            ? object.signals.filter((value) => typeof value === "string")
+            : [];
+    }
+    return [];
+}
+function containsCompleteTerm(text, term) {
+    // Personal admission intentionally classifies case-insensitive prose signals;
+    // it is not project terminology's exact-case source occurrence contract.
+    const escaped = term.trim().replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return escaped.length > 0 && new RegExp(`(^|[^a-z0-9])${escaped}(?=$|[^a-z0-9])`, "i").test(text);
+}
+function unavailable(state) {
+    return { state, status: "unavailable", candidates: [], recovery: recoveryForState(state) };
+}
+/**
+ * Admit personal glossary evidence from one bounded signal read and direct
+ * resolution of selected anchors only. Profile rendering and persistence are
+ * deliberately outside this partial producer boundary.
+ */
+export function admitPersonalGlossaryEvidence(input, resolveAnchor = resolveEvidenceAnchor) {
+    const authority = personalGlossaryAdmissionContract();
+    const assessment = assessTiers(input.tiersDir, input.corpusPath);
+    if (!assessment.analyzable)
+        return unavailable(assessment.state);
+    const tier = readSignalTier(input.tiersDir);
+    if (!tier)
+        return unavailable("corrupt");
+    const explicitTypes = new Set(authority.explicitSignalTypes);
+    const inferredTypes = new Set(authority.inferredSignalTypes);
+    const inferredKinds = new Set(authority.inferredSourceKinds);
+    const selected = tier.records.filter((signal) => explicitTypes.has(signal.signal_type) ||
+        (input.requestedTerms.length > 0 &&
+            inferredTypes.has(signal.signal_type) &&
+            inferredKinds.has(signal.source_kind)));
+    const resolved = new Map();
+    for (const signal of selected) {
+        if (resolved.has(signal.evidence_anchor))
+            continue;
+        const record = resolveAnchor(signal.evidence_anchor, input.tiersDir);
+        if (record &&
+            record.source_id === signal.source_id &&
+            record.source_kind === signal.source_kind) {
+            resolved.set(signal.evidence_anchor, { signal, record });
+        }
+    }
+    const candidates = [];
+    for (const { signal, record } of resolved.values()) {
+        if (!explicitTypes.has(signal.signal_type))
+            continue;
+        const classified = classifyExplicitGlossaryLanguage(recordText(record));
+        if (!classified)
+            continue;
+        candidates.push({
+            kind: "personal_explicit_definition",
+            ...classified,
+            evidence: [
+                {
+                    source_id: signal.source_id,
+                    evidence_anchor: signal.evidence_anchor,
+                    signal_type: signal.signal_type,
+                },
+            ],
+        });
+    }
+    for (const term of new Set(input.requestedTerms.map((value) => value.trim()).filter(Boolean))) {
+        const evidence = [...resolved.values()]
+            .filter(({ signal, record }) => inferredTypes.has(signal.signal_type) &&
+            inferredKinds.has(signal.source_kind) &&
+            semanticValues(record).some((value) => containsCompleteTerm(value, term)))
+            .map(({ signal }) => ({
+            source_id: signal.source_id,
+            evidence_anchor: signal.evidence_anchor,
+            source_kind: signal.source_kind,
+        }))
+            .filter((item, index, all) => all.findIndex((candidate) => candidate.source_id === item.source_id ||
+            candidate.evidence_anchor === item.evidence_anchor) === index)
+            .sort((left, right) => left.source_id.localeCompare(right.source_id));
+        if (evidence.length >= 2 &&
+            new Set(evidence.map((item) => item.source_id)).size >= 2 &&
+            new Set(evidence.map((item) => item.evidence_anchor)).size >= 2) {
+            candidates.push({ kind: "personal_inferred_usage", term, evidence: evidence.slice(0, 2) });
+        }
+    }
+    return candidates.length > 0
+        ? { state: assessment.state, status: "admitted", candidates, recovery: null }
+        : {
+            state: assessment.state,
+            status: "insufficient",
+            candidates: [],
+            recovery: authority.insufficientRecovery,
+        };
+}

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 };
+}