agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/analytics/extractCorpus/jsonlSessions.js

@@ -111,7 +111,18 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
             const cwd = event.cwd || event.workingDirectory || event.working_directory;
             if (typeof cwd === "string" && cwd)
                 projectPath = cwd;
-            const toolRecord = toolCallRecord({ event, fallbackTimestamp, projectPath, runtime: "claude-code", sourcePath: p, index, sessionId });
+            const toolRecord = toolCallRecord({
+                event,
+                fallbackTimestamp,
+                projectPath,
+                runtime: null,
+                sourceClass: "historical_import",
+                sourceProduct: "claude-code",
+                activeRuntime: false,
+                sourcePath: p,
+                index,
+                sessionId,
+            });
             if (toolRecord !== null) {
                 records.push(toolRecord);
                 continue;
@@ -124,7 +135,10 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
                     event,
                     fallbackTimestamp,
                     projectPath,
-                    runtime: "claude-code",
+                    runtime: null,
+                    sourceClass: "historical_import",
+                    sourceProduct: "claude-code",
+                    activeRuntime: false,
                     sourcePath: p,
                     index: index * 1000 + contentIndex,
                     sessionId,
@@ -159,7 +173,10 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
                 sourceKind: "conversation_turn",
                 timestamp,
                 projectPath,
-                runtime: "claude-code",
+                runtime: null,
+                sourceClass: "historical_import",
+                sourceProduct: "claude-code",
+                activeRuntime: false,
                 sourceParts: [resolvePath(p), index, role, content.slice(0, 80)],
                 sessionId,
                 data,
@@ -171,7 +188,10 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
                         sourceKind: "history_prompt",
                         timestamp,
                         projectPath,
-                        runtime: "claude-code",
+                        runtime: null,
+                        sourceClass: "historical_import",
+                        sourceProduct: "claude-code",
+                        activeRuntime: false,
                         sourceParts: [resolvePath(p), index, "history", content.slice(0, 120)],
                         sessionId,
                         data: { prompt: content, signal_type: sig },
@@ -182,4 +202,3 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
     }
     return records;
 }
-//# sourceMappingURL=jsonlSessions.js.map

package/dist/analytics/extractCorpus/sqliteCaps.js

@@ -41,4 +41,3 @@ export function applyTruncationToStatus(status, truncation) {
         truncation_limit: truncation.limit,
     };
 }
-//# sourceMappingURL=sqliteCaps.js.map

package/dist/analytics/extractCorpus/sqliteSessions.js

@@ -365,4 +365,3 @@ export function extractOpencodeSessions(storePath, errors, ctx) {
     }
     return records;
 }
-//# sourceMappingURL=sqliteSessions.js.map

package/dist/analytics/extractCorpus/tierReader.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { compatibilityStates, evidenceTierBounds, } from "../../registries/evidenceTierContract.js";
+import { defaultTiersDir, evidenceTierCompatibility, iterTierRecords, readSignalTier, readTierCorpusMetadata, } from "./evidenceTiers.js";
+/**
+ * Bounded tier reader for analytics consumers (plan Task 3).
+ *
+ * Task 2 publishes bounded full-evidence shards and a bounded signal tier with
+ * an atomic generation pointer. This module is the consumer-side surface that
+ * projects the contract's compatibility states and recovery guidance, resolves
+ * the tiers directory from a corpus path, and exposes bounded reads (full-evidence
+ * records one shard at a time; metadata/signal reads without full records). It does
+ * not duplicate the tier map, source families, bounds, or compatibility outcomes —
+ * those are projected from `evidenceTierContract` and `evidenceTiers`.
+ *
+ * Consumers preserve their JSON output shape and exit codes. A non-current tier
+ * degrades with actionable, contract-projected recovery rather than indefinitely
+ * loading an oversized monolithic corpus envelope. `incomplete` is a degrade
+ * outcome: consumers analyze available sources and surface the coverage gap, so a
+ * host missing some runtimes still gets useful analysis instead of a hard failure.
+ */
+/** A corpus path's co-located tiers directory (`<intermediate>/tiers`). */
+export function tiersDirForCorpusPath(corpusPath) {
+    return path.join(path.dirname(corpusPath), "tiers");
+}
+/** Canonical tiers directory for the stats profile. */
+export function resolveTiersDir(env = process.env, platform = process.platform) {
+    return defaultTiersDir(env, platform);
+}
+/** Whether a compatibility state still permits analysis of available sources. */
+export function isAnalyzable(state) {
+    return state === "current" || state === "incomplete";
+}
+/**
+ * Actionable recovery guidance projected from the authority contract for a
+ * compatibility state. The contract owns the recovery text; this never
+ * duplicates it. Returns `null` for states that proceed (current/incomplete).
+ */
+export function recoveryForState(state) {
+    if (state === "current" || state === "incomplete")
+        return null;
+    const states = compatibilityStates();
+    const def = states.find((s) => s.state_id === state);
+    return def?.recovery ?? null;
+}
+/**
+ * Assess the tiers directory against the contract's compatibility states. When a
+ * legacy corpus envelope is supplied, a missing tier with an existing envelope
+ * surfaces as `legacy` (refresh guidance) rather than a bare missing state.
+ */
+export function assessTiers(tiersDir, corpusPath) {
+    const compat = evidenceTierCompatibility(tiersDir, corpusPath);
+    const assessment = {
+        state: compat.state,
+        analyzable: isAnalyzable(compat.state),
+        tiersDir,
+        corpusPath,
+        recovery: recoveryForState(compat.state) ?? undefined,
+    };
+    if (compat.state === "incomplete")
+        assessment.coverageGaps = compat.detail;
+    if (compat.state === "oversized")
+        assessment.artifact = compat.artifact;
+    if (compat.state === "current")
+        assessment.generation = compat.generation;
+    return assessment;
+}
+/**
+ * Read bounded metadata for signal-tier consumers (report status, prime
+ * coverage). Reads the manifest and the bounded signal tier only — never the
+ * full-evidence shards — so metadata consumers stay bounded at real scale. The
+ * signal tier is bounded by construction; a defensively oversized signal tier is
+ * reported as null so the caller degrades with the assessment's recovery.
+ */
+export function readBoundedMetadata(tiersDir) {
+    const signal = readSignalTier(tiersDir);
+    const corpusMetadata = readTierCorpusMetadata(tiersDir);
+    const bounds = evidenceTierBounds();
+    if (signal && (signal.bytes > bounds.signalByteCap || signal.manifest.signal.bytes > bounds.signalByteCap)) {
+        return { corpusMetadata: null, signal: null, manifest: signal.manifest };
+    }
+    return { corpusMetadata, signal, manifest: signal?.manifest ?? null };
+}
+/**
+ * Iterate full-evidence records for the current generation, one bounded shard at
+ * a time. Full-record consumers (usage analytics, startup analysis) use this so
+ * they never materialize the monolithic corpus envelope. Returns `null` when no
+ * current generation exists; callers report the assessment instead.
+ */
+export function iterBoundedRecords(tiersDir) {
+    return iterTierRecords(tiersDir);
+}
+/**
+ * Legacy fallback: a small monolithic corpus envelope may still be read for
+ * backward compatibility when no tiers were published. Oversized legacy state
+ * is never loaded whole — it returns `false` so the caller emits refresh guidance.
+ */
+export function legacyCorpusReadable(corpusPath) {
+    if (!corpusPath || !fs.existsSync(corpusPath))
+        return false;
+    const bounds = evidenceTierBounds();
+    try {
+        return fs.statSync(corpusPath).size <= bounds.readerByteCap;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/analytics/extractCorpus.js

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

package/dist/analytics/glossaryAdviceResolution.js

@@ -0,0 +1,166 @@
+import { glossaryAdviceContract, } from "../registries/glossaryAdviceContract.js";
+import { unicodeCaselessExact } from "../registries/glossaryTermIdentity.js";
+const RECOVERY = {
+    invalid_request: "Provide one non-empty bounded requested term and retry advice resolution.",
+    invalid_acquisition: "Reacquire bounded glossary inputs and retry advice resolution.",
+    invalid_host_review: "Provide one contract-declared relation to a valid acquired personal candidate and retry advice resolution.",
+};
+export class GlossaryAdviceInputError extends Error {
+    code;
+    constructor(code) {
+        super(RECOVERY[code]);
+        this.code = code;
+        this.name = "GlossaryAdviceInputError";
+    }
+}
+function hasOnlyKeys(value, expected) {
+    const keys = Object.keys(value).sort();
+    return (keys.length === expected.length &&
+        keys.every((key, index) => key === [...expected].sort()[index]));
+}
+function boundedNonEmpty(value, maxBytes) {
+    return (typeof value === "string" &&
+        value.trim().length > 0 &&
+        Buffer.byteLength(value, "utf8") <= maxBytes);
+}
+function validateEntries(source, owner, maxEntries, maxBytes) {
+    if (!Array.isArray(source.entries) || source.entries.length > maxEntries) {
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    }
+    const terms = [];
+    for (const candidate of source.entries) {
+        if (candidate === null ||
+            typeof candidate !== "object" ||
+            !hasOnlyKeys(candidate, ["term", "meaning", "owner"]) ||
+            candidate.owner !== owner ||
+            !boundedNonEmpty(candidate.term, maxBytes) ||
+            !boundedNonEmpty(candidate.meaning, maxBytes)) {
+            throw new GlossaryAdviceInputError("invalid_acquisition");
+        }
+        if (terms.some((term) => unicodeCaselessExact(term, candidate.term))) {
+            throw new GlossaryAdviceInputError("invalid_acquisition");
+        }
+        terms.push(candidate.term);
+    }
+}
+function validateSource(source, owner, maxEntries, maxBytes, availabilityStates) {
+    if (source === null ||
+        typeof source !== "object" ||
+        !hasOnlyKeys(source, ["owner", "availability", "entries", "gap_proving", "diagnostic"])) {
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    }
+    const candidate = source;
+    if (candidate.owner !== owner ||
+        !availabilityStates.includes(candidate.availability) ||
+        typeof candidate.gap_proving !== "boolean") {
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    }
+    validateEntries(candidate, owner, maxEntries, maxBytes);
+    const valid = ["absent", "valid_empty", "valid_present"].includes(candidate.availability);
+    const expectedGap = owner === "project" && ["absent", "valid_empty"].includes(candidate.availability);
+    if (valid) {
+        const expectedEntryPresence = candidate.availability === "valid_present";
+        if (candidate.diagnostic !== null ||
+            candidate.gap_proving !== expectedGap ||
+            expectedEntryPresence !== candidate.entries.length > 0) {
+            throw new GlossaryAdviceInputError("invalid_acquisition");
+        }
+        return;
+    }
+    const diagnostic = candidate.diagnostic;
+    if (candidate.entries.length !== 0 ||
+        candidate.gap_proving ||
+        diagnostic === null ||
+        typeof diagnostic !== "object" ||
+        !hasOnlyKeys(diagnostic, ["class", "recovery"]) ||
+        diagnostic.class !== candidate.availability ||
+        typeof diagnostic.recovery !== "string" ||
+        diagnostic.recovery.trim().length === 0) {
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    }
+}
+function validateAcquired(acquired, contract) {
+    if (acquired === null ||
+        typeof acquired !== "object" ||
+        !hasOnlyKeys(acquired, ["project", "personal"])) {
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    }
+    const candidate = acquired;
+    validateSource(candidate.project, "project", contract.maxEntries, contract.maxRequestedTermUtf8Bytes, contract.availabilityStates);
+    validateSource(candidate.personal, "personal", contract.maxEntries, contract.maxRequestedTermUtf8Bytes, contract.availabilityStates);
+}
+function exactEntry(entries, requestedTerm) {
+    return entries.find((candidate) => unicodeCaselessExact(candidate.term, requestedTerm));
+}
+function validatedHostReview(requestedTerm, personal, hostReview, contract) {
+    if (hostReview === undefined)
+        return undefined;
+    if (hostReview === null ||
+        typeof hostReview !== "object" ||
+        !hasOnlyKeys(hostReview, ["relation", "candidate_owner", "candidate_term"])) {
+        throw new GlossaryAdviceInputError("invalid_host_review");
+    }
+    const candidate = hostReview;
+    if (!contract.hostReviewRelations.includes(candidate.relation) ||
+        !contract.hostReviewCandidateOwners.includes(candidate.candidate_owner) ||
+        !boundedNonEmpty(candidate.candidate_term, contract.maxRequestedTermUtf8Bytes) ||
+        unicodeCaselessExact(candidate.candidate_term, requestedTerm) ||
+        !personal.entries.some((entry) => unicodeCaselessExact(entry.term, candidate.candidate_term))) {
+        throw new GlossaryAdviceInputError("invalid_host_review");
+    }
+    return candidate;
+}
+export function classifyGlossaryAdviceInputs(requestedTerm, acquired, hostReview) {
+    const projectExact = exactEntry(acquired.project.entries, requestedTerm);
+    const personalExact = exactEntry(acquired.personal.entries, requestedTerm);
+    const projectValid = ["absent", "valid_empty", "valid_present"].includes(acquired.project.availability);
+    const personalUsable = ["valid_empty", "valid_present"].includes(acquired.personal.availability);
+    return {
+        project_input: !projectValid ? "invalid" : projectExact ? "valid_exact" : "valid_gap",
+        personal_input: personalExact
+            ? "valid_exact"
+            : personalUsable
+                ? "valid_without_exact"
+                : "invalid",
+        exact_meaning: projectExact && personalExact
+            ? projectExact.meaning === personalExact.meaning
+                ? "equivalent"
+                : "divergent"
+            : "not_applicable",
+        inferred_candidate: hostReview ? "present" : "absent",
+    };
+}
+function matches(match, state) {
+    return Object.entries(state).every(([dimension, value]) => match[dimension]?.includes(value));
+}
+export function resolveGlossaryAdvice(requestedTerm, acquired, hostReview) {
+    const contract = glossaryAdviceContract();
+    if (!boundedNonEmpty(requestedTerm, contract.maxRequestedTermUtf8Bytes)) {
+        throw new GlossaryAdviceInputError("invalid_request");
+    }
+    validateAcquired(acquired, contract);
+    const review = validatedHostReview(requestedTerm, acquired.personal, hostReview, contract);
+    const state = classifyGlossaryAdviceInputs(requestedTerm, acquired, review);
+    const rows = contract.rows.filter((row) => matches(row.match, state));
+    if (rows.length !== 1)
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    const row = rows[0];
+    const selectedOwner = row.selectedOwner === "project" || row.selectedOwner === "personal" ? row.selectedOwner : null;
+    const selectedEntry = selectedOwner
+        ? exactEntry(acquired[selectedOwner].entries, requestedTerm)
+        : undefined;
+    const advisories = contract.advisories.filter((advisory) => advisory.primaryOutcome === row.name && matches(advisory.match, state));
+    if (advisories.length > 1)
+        throw new GlossaryAdviceInputError("invalid_acquisition");
+    const advisory = advisories[0];
+    return {
+        outcome: row.name,
+        applicable_meaning: selectedEntry?.meaning ?? null,
+        applicable_owner: selectedOwner,
+        review: advisory?.review ?? row.review,
+        tension: row.tension,
+        advisory: advisory
+            ? { reason: advisory.caveatReason, ownership_state: advisory.ownershipState }
+            : null,
+    };
+}

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