agentera 3.0.0-dev.7 → 3.0.0-dev.74

package/dist/analytics/extractCorpus/extractCorpusParity.js

@@ -41,22 +41,23 @@ function boundsFromRecords(records) {
     }
     return { earliest, latest };
 }
-/** Canonical opencode parity snapshot used by TS and the generated Python wrapper. */
+/** Production opencode parity snapshot compared with the generated independent Python oracle. */
 export function opencodeParitySnapshot(dbPath) {
     if (!fs.existsSync(dbPath)) {
         throw new Error(`extract-corpus parity: missing opencode db at ${dbPath}`);
     }
     const audit = runCoverageAudit({
         output: dbPath,
+        tierOutput: null,
         projectRoot: [path.dirname(dbPath)],
         codexSessionsDir: path.join(path.dirname(dbPath), "unused-codex"),
-        claudeProjectsDir: path.join(path.dirname(dbPath), "unused-claude"),
+        claudeProjectsDir: null,
         opencodeConversationsDir: dbPath,
         copilotConversationsDir: null,
         cursorProjectsDir: null,
         cursorChatsDir: null,
         noCodex: true,
-        noClaude: true,
+        importSources: [],
         noOpencode: false,
         noCopilot: true,
         noCursor: true,
@@ -102,4 +103,3 @@ export function opencodeParitySnapshot(dbPath) {
         },
     };
 }
-//# sourceMappingURL=extractCorpusParity.js.map

package/dist/analytics/extractCorpus/filesystemSources.js

@@ -4,10 +4,7 @@ import { resolvePath } from "../../core/paths.js";
 import { isPlainObject, isoFromMtime, record, splitLines, } from "./core.js";
 export function extractInstructionDocuments(projectRoots, errors) {
     const records = [];
-    const docNames = [
-        ["AGENTS.md", "agents_md"],
-        ["CLAUDE.md", "claude_md"],
-    ];
+    const docNames = [["AGENTS.md", "agents_md"]];
     for (const root of projectRoots) {
         for (const [filename, docType] of docNames) {
             const p = path.join(root, filename);
@@ -26,7 +23,9 @@ export function extractInstructionDocuments(projectRoots, errors) {
                 timestamp: isoFromMtime(p),
                 projectPath: root,
                 runtime: "filesystem",
+                origin: resolvePath(p),
                 sourceParts: [resolvePath(p)],
+                content,
                 data: { doc_type: docType, name: filename, content, scope: "project" },
             }));
         }
@@ -112,11 +111,12 @@ export function extractProjectConfigSignals(projectRoots, errors) {
                 timestamp: isoFromMtime(p),
                 projectPath: root,
                 runtime: "filesystem",
+                origin: resolvePath(p),
                 sourceParts: [resolvePath(p), configType],
+                content: signals.join("\n"),
                 data: { config_type: configType, file_path: path.relative(root, p), signals },
             }));
         }
     }
     return records;
 }
-//# sourceMappingURL=filesystemSources.js.map

package/dist/analytics/extractCorpus/index.js

@@ -1,4 +1,4 @@
-export { ADAPTER_VERSION, FAMILIES, RUNTIME_STORE_GLOBS, isoNow, isoFromMtime, stableId, projectIdFromPath, defaultAgenteraHome, defaultProfileDir, defaultOutputPath, runtimeStatus, discoverRuntimeStore, record, payloadItem, eventKind, eventTimestamp, textFromContent, claudeContentItems, iterJsonl, signalType, } from "./core.js";
+export { ADAPTER_VERSION, FAMILIES, RUNTIME_STORE_GLOBS, isoNow, isoFromMtime, stableId, originIdentity, contentFingerprint, transportProvenance, authorClassForRole, missingProvenanceFields, assessProvenance, countIndependentOrigins, projectIdFromPath, defaultAgenteraHome, defaultProfileDir, defaultOutputPath, runtimeStatus, discoverRuntimeStore, record, payloadItem, eventKind, eventTimestamp, textFromContent, claudeContentItems, iterJsonl, signalType, } from "./core.js";
 export { extractInstructionDocuments, extractProjectConfigSignals } from "./filesystemSources.js";
 export { extractCodexSessions, extractClaudeProjectSessions } from "./jsonlSessions.js";
 export { extractOpencodeSessions, PermissionDeniedError } from "./sqliteSessions.js";
@@ -8,5 +8,7 @@ export { ExtractionNotImplementedError, dedupeRecords, buildMetadata, buildCorpu
 export { formatTruncationWarnings, resolveSqliteCaps, } from "./sqliteCaps.js";
 export { COVERAGE_EXIT_FLAGGED, corpusEnvelopeCoverage, formatCoverageSummaryText, resolveRuntimeStoreConfigs, runCoverageAudit, } from "./coverageAudit.js";
 export { parseExtractArgs, extractCorpusMain } from "./cli.js";
+export { TIER_SCHEMA_VERSION, CURRENT_POINTER_VERSION, defaultTiersDir, familyOf, deriveSignalRecords, shardFullEvidence, selectSignalsForBound, generationId, publishEvidenceTiers, readCurrentPointer, readCurrentGeneration, readSignalTier, missingSignalProvenanceFields, getFullRecord, resolveEvidenceAnchor, evidenceTierCompatibility, iterTierRecords, readTierCorpusMetadata, } from "./evidenceTiers.js";
+export { tiersDirForCorpusPath, resolveTiersDir, isAnalyzable, recoveryForState, assessTiers, readBoundedMetadata, iterBoundedRecords, legacyCorpusReadable, } from "./tierReader.js";
 export { EXTRACT_CORPUS_PARITY_SCHEMA, buildExtractCorpusParityManifest, opencodeParitySnapshot, } from "./extractCorpusParity.js";
-//# sourceMappingURL=index.js.map
+export { readProfileSignals, resolveProfileEvidence, profileSignalsStatus, assessProfileSufficiency, } from "../profileSignals.js";

package/dist/analytics/extractCorpus/jsonlSessions.js

@@ -1,12 +1,43 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolvePath } from "../../core/paths.js";
-import { claudeContentItems, eventKind, eventTimestamp, isPlainObject, isoFromMtime, iterJsonl, payloadItem, record, rglob, signalType, textFromContent, toolCallRecord, toolCallRecordFromItem, } from "./core.js";
+import { claudeContentItems, authorClassForRole, eventKind, eventTimestamp, inspectTransportProvenance, isPlainObject, isoFromMtime, iterJsonl, payloadItem, record, rglob, signalType, textFromContent, transportProvenance, toolCallRecord, toolCallRecordFromItem, } from "./core.js";
 function pathStem(p) {
     const base = path.basename(p);
     const ext = path.extname(base);
     return ext ? base.slice(0, -ext.length) : base;
 }
+function updateSessionProvenance(current, update) {
+    if (update.originState === "invalid")
+        return current;
+    const originId = update.originState === "valid" ? update.originId : current.originId;
+    const originChanged = update.originState === "valid" && originId !== current.originId;
+    if (originChanged) {
+        return {
+            originId,
+            authorClass: update.authorState === "valid" ? update.authorClass : null,
+        };
+    }
+    if (originId !== null && update.authorState === "valid") {
+        return { originId, authorClass: update.authorClass };
+    }
+    return { originId, authorClass: current.authorClass };
+}
+function codexMessageProvenance(role, message, session) {
+    const originId = message.originState === "valid" ? message.originId : session.originId;
+    if (message.originState === "invalid" || message.authorState === "invalid") {
+        return { originId, authorClass: null };
+    }
+    const explicitAuthorClass = message.authorState === "valid"
+        ? message.authorClass
+        : originId !== null && originId === session.originId
+            ? session.authorClass
+            : null;
+    return {
+        originId,
+        authorClass: authorClassForRole(role, explicitAuthorClass, originId),
+    };
+}
 export function extractCodexSessions(sessionsDir, errors) {
     if (sessionsDir === null || !fs.existsSync(sessionsDir))
         return [];
@@ -14,6 +45,7 @@ export function extractCodexSessions(sessionsDir, errors) {
     for (const p of rglob(sessionsDir, "*.jsonl")) {
         const fallbackTimestamp = isoFromMtime(p);
         let sessionId = pathStem(p);
+        let sessionProvenance = { originId: null, authorClass: null };
         let projectPath = null;
         let previousAssistant = "";
         let index = 0;
@@ -25,6 +57,7 @@ export function extractCodexSessions(sessionsDir, errors) {
                 const sid = payload.id || event.id;
                 if (typeof sid === "string" && sid)
                     sessionId = sid;
+                sessionProvenance = updateSessionProvenance(sessionProvenance, inspectTransportProvenance(event, payload));
                 const cwd = payload.cwd || payload.working_directory;
                 if (typeof cwd === "string" && cwd)
                     projectPath = cwd;
@@ -46,7 +79,7 @@ export function extractCodexSessions(sessionsDir, errors) {
             let role = item.role || item.actor;
             if (kind === "user_msg")
                 role = "user";
-            if (role !== "user" && role !== "assistant")
+            if (typeof role !== "string" || role.length === 0)
                 continue;
             const skipType = itemType !== undefined && itemType !== null && itemType !== "message";
             if (skipType && !["response_item", "user_msg"].includes(kind))
@@ -55,6 +88,7 @@ export function extractCodexSessions(sessionsDir, errors) {
             if (!content)
                 continue;
             const timestamp = eventTimestamp(event, fallbackTimestamp);
+            const transport = codexMessageProvenance(role, inspectTransportProvenance(event, item), sessionProvenance);
             const data = { actor: role, content };
             if (role === "user") {
                 if (previousAssistant)
@@ -73,6 +107,9 @@ export function extractCodexSessions(sessionsDir, errors) {
                 runtime: "codex",
                 sourceParts: [resolvePath(p), index, role, content.slice(0, 80)],
                 sessionId,
+                originId: transport.originId,
+                authorClass: transport.authorClass,
+                content,
                 data,
             }));
             if (role === "user") {
@@ -85,6 +122,9 @@ export function extractCodexSessions(sessionsDir, errors) {
                         runtime: "codex",
                         sourceParts: [resolvePath(p), index, "history", content.slice(0, 120)],
                         sessionId,
+                        originId: transport.originId,
+                        authorClass: transport.authorClass,
+                        content,
                         data: { prompt: content, signal_type: sig },
                     }));
                 }
@@ -111,7 +151,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 +175,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,
@@ -138,12 +192,15 @@ export function extractClaudeProjectSessions(projectsDir, errors) {
                 if (isPlainObject(message))
                     role = message.role;
             }
-            if (role !== "user" && role !== "assistant")
+            if (typeof role !== "string" || role.length === 0)
                 continue;
             const content = textFromContent(event.content || event.text || (isPlainObject(event.message) ? event.message : null));
             if (!content)
                 continue;
             const timestamp = eventTimestamp(event, fallbackTimestamp);
+            const transport = transportProvenance(event, isPlainObject(event.message) ? event.message : null);
+            const originId = transport.originId;
+            const authorClass = authorClassForRole(role, transport.authorClass, transport.originId);
             const data = { actor: role, content };
             if (role === "user") {
                 if (previousAssistant)
@@ -159,9 +216,15 @@ 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,
+                originId,
+                authorClass,
+                content,
                 data,
             }));
             if (role === "user") {
@@ -171,9 +234,15 @@ 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,
+                        originId,
+                        authorClass,
+                        content,
                         data: { prompt: content, signal_type: sig },
                     }));
                 }
@@ -182,4 +251,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

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import { resolvePath } from "../../core/paths.js";
-import { isoFromMtime, record, signalType, textFromContent, } from "./core.js";
+import { authorClassForRole, isoFromMtime, record, signalType, textFromContent, transportProvenance, } from "./core.js";
 import { isPlainObject, isFilePath, rglob } from "./core.js";
 import { resolveSqliteCaps, } from "./sqliteCaps.js";
 const requireCjs = createRequire(import.meta.url);
@@ -271,8 +271,11 @@ export function extractOpencodeSessions(storePath, errors, ctx) {
             const messageTime = row.message_time || nestedTimeCreated(messageData);
             let item = messages.get(messageId);
             if (item === undefined) {
+                const transport = transportProvenance(messageData);
                 item = {
                     role,
+                    origin_id: transport.originId,
+                    author_class: authorClassForRole(role, transport.authorClass, transport.originId),
                     session_id: String(row.session_id),
                     project_path: row.project_path,
                     timestamp: sqliteTimestamp(messageTime, fallbackTimestamp),
@@ -305,9 +308,9 @@ export function extractOpencodeSessions(storePath, errors, ctx) {
         let index = 0;
         for (const item of messages.values()) {
             index += 1;
-            const role = String(item.role).toLowerCase();
-            if (role !== "user" && role !== "assistant")
+            if (typeof item.role !== "string" || item.role.length === 0)
                 continue;
+            const role = item.role.toLowerCase();
             const content = item.parts.filter((p) => p).join("\n");
             if (!content && item.tools.length === 0)
                 continue;
@@ -331,6 +334,9 @@ export function extractOpencodeSessions(storePath, errors, ctx) {
                     runtime: "opencode",
                     sourceParts: [resolvePath(dbPath), index, role, content.slice(0, 80)],
                     sessionId: item.session_id,
+                    originId: item.origin_id,
+                    authorClass: item.author_class,
+                    content,
                     data,
                 }));
             }
@@ -357,6 +363,9 @@ export function extractOpencodeSessions(storePath, errors, ctx) {
                         runtime: "opencode",
                         sourceParts: [resolvePath(dbPath), index, "history", content.slice(0, 120)],
                         sessionId: item.session_id,
+                        originId: item.origin_id,
+                        authorClass: item.author_class,
+                        content,
                         data: { prompt: content, signal_type: sig },
                     }));
                 }
@@ -365,4 +374,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,
+    };
+}