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

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,113 @@
+import { personalGlossaryAdmissionContract } from "../registries/glossaryEntryContract.js";
+import { readSignalTier, resolveEvidenceAnchor, } from "./extractCorpus/evidenceTiers.js";
+import { assessTiers, recoveryForState } from "./extractCorpus/tierReader.js";
+import { mineExplicitGlossaryCandidates } from "./personalGlossaryExplicitMining.js";
+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 hasInferredProvenance(signal) {
+    return (/^[a-f0-9]{64}$/.test(signal.origin_id ?? "") &&
+        /^[a-f0-9]{64}$/.test(signal.content_fingerprint ?? ""));
+}
+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 (explicitTypes.has(signal.signal_type))
+            continue;
+        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 = [];
+    const explicitMining = mineExplicitGlossaryCandidates({ tiersDir: input.tiersDir }, resolveAnchor);
+    for (const { capsule } of explicitMining.candidates) {
+        candidates.push({
+            kind: "personal_explicit_definition",
+            term: capsule.term,
+            meaning: capsule.meaning,
+            evidence: capsule.evidence.map((evidence) => ({
+                source_id: String(evidence.source_id),
+                evidence_anchor: String(evidence.evidence_anchor),
+                signal_type: String(evidence.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) &&
+            hasInferredProvenance(signal) &&
+            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 });
+        }
+    }
+    return candidates.length > 0
+        ? { state: assessment.state, status: "admitted", candidates, recovery: null }
+        : {
+            state: assessment.state,
+            status: "insufficient",
+            candidates: [],
+            recovery: authority.insufficientRecovery,
+        };
+}
+export { classifyExplicitGlossaryLanguage, discoverExplicitGlossaryCues, mineExplicitGlossaryCandidates, mineExplicitGlossaryEvidence, minePersonalExplicitGlossaryCandidates, EXPLICIT_GLOSSARY_REASONS, } from "./personalGlossaryExplicit.js";
+export { mineRecurringGlossaryCandidates, mineRecurringGlossaryEvidence, PERSONAL_GLOSSARY_MINING_POLICY_VERSION, RECURRING_MEANING_PENDING_REVIEW, RECURRING_REASONS, } from "./personalGlossaryRecurrence.js";
+export { maintainPersonalGlossaryCandidateProjection, personalGlossaryCandidateProjectionPath, personalGlossaryProjectionProjectIdentity, persistPersonalGlossaryCandidateProjection, persistPersonalGlossaryCandidateProjectionAfterRefresh, projectPersonalGlossaryCandidates, readPersonalGlossaryCandidateProjection, } from "./personalGlossaryCandidateProjection.js";
+export { decidePersonalGlossaryCandidate, } from "./personalGlossaryDecision.js";
+export { currentPersonalGlossaryReviewRecords, maintainPersonalGlossaryReviewRecords, personalGlossaryReviewRecordsPath, queuePersonalGlossaryReviewRecord, readPersonalGlossaryReviewRecords, } from "./personalGlossaryReviewRecords.js";