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

package/dist/analytics/personalGlossaryReviewRecords.js

@@ -0,0 +1,332 @@
+import fs from "node:fs";
+import { readCurrentPersonalGlossaryCandidateProjection } from "./personalGlossaryCurrentGeneration.js";
+import { decidePersonalGlossaryCandidate } from "./personalGlossaryDecision.js";
+import { createGlossaryReviewRecord, validateGlossaryAdmissionDecision, validateGlossaryHostClassificationReceipt, validateGlossaryReviewRecord, } from "../registries/glossaryCandidateContracts.js";
+import { personalReviewApprovalReceiptDigest, personalReviewApprovalReplayStatus, personalReviewDispositionLifecycle, validatePersonalReviewApprovalReceipt, } from "../registries/glossaryMiningAuthority.js";
+import { canonicalGlossaryJson, compareGlossaryUnicodeStrings } from "../registries/glossaryTermIdentity.js";
+import { activeReplayDigestMap, currentReplayIndex, ensurePersonalGlossaryReviewRecordsPrivate, isCurrentReviewRecord, isCurrentReviewStore, isLegacyReviewStore, makePersonalGlossaryReviewStore, migrateLegacyPendingReviewRecord, personalGlossaryReviewRecordsPath, personalGlossaryReviewRecordsStorageContract, personalGlossaryTrustedLocalHostPath, privateWritePersonalGlossaryReviewRecords, readPersonalGlossaryReviewRecords, readPersonalGlossaryTrustedLocalHost, readablePersonalGlossaryReviewRecord, recordMatchesProjection, replayDigestMap, replayNonceDigest, reviewExpiry, reviewIdentity, reviewScope, sealPersonalGlossaryReviewRecord, terminalReviewRecordExpired, validPersonalGlossaryReviewGenerationBinding, validPersonalGlossaryReviewMetadataBinding, } from "./personalGlossaryReviewRecordStorage.js";
+export { personalGlossaryReviewRecordsPath, personalGlossaryTrustedLocalHostPath, readPersonalGlossaryReviewRecords, validPersonalGlossaryReviewGenerationBinding, validPersonalGlossaryReviewMetadataBinding, };
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function timestamp(value) {
+    return typeof value === "string" && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value));
+}
+function digest(value) {
+    return typeof value === "string" && SHA256.test(value);
+}
+function exactCandidate(candidates, decision) {
+    return candidates.find((candidate) => candidate.capsule.candidate_id === decision.candidate_id &&
+        candidate.capsule.candidate_revision === decision.candidate_revision &&
+        candidate.capsule.capsule_sha256 === decision.candidate_capsule_sha256 &&
+        candidate.capsule.generation === decision.generation &&
+        candidate.capsule.policy_version === decision.policy_version) ?? null;
+}
+function pendingRecord(decision, scope, queuedAt, reopenReason) {
+    const body = {
+        schema_version: "agentera.personalGlossaryReviewRecord.v2",
+        owner: "current_user",
+        candidate_id: decision.candidate_id,
+        candidate_revision: decision.candidate_revision,
+        candidate_capsule_sha256: decision.candidate_capsule_sha256,
+        candidate_projection_sha256: decision.candidate_projection_sha256,
+        host_receipt_sha256: decision.host_receipt_sha256,
+        cli_decision_sha256: decision.decision_sha256,
+        semantic_fingerprint: decision.semantic_fingerprint,
+        generation: decision.generation,
+        policy_version: decision.policy_version,
+        scope,
+        reason: decision.reason,
+        status: "pending",
+        disposition: null,
+        review_record: null,
+        reopen_reason: reopenReason,
+        queued_at: queuedAt,
+        terminal_at: null,
+        expires_at: null,
+    };
+    return sealPersonalGlossaryReviewRecord({ ...body, review_id: reviewIdentity(body) });
+}
+function suppresses(record) {
+    return record.disposition === "reject" || record.disposition === "defer";
+}
+function sameSuppressionBinding(previous, current) {
+    return previous.candidate_id === current.candidate_id &&
+        previous.semantic_fingerprint === current.semantic_fingerprint &&
+        previous.scope === current.scope && previous.policy_version === current.policy_version;
+}
+function reopeningReason(previous, current) {
+    if (previous.candidate_id !== current.candidate_id)
+        return null;
+    if (previous.policy_version !== current.policy_version)
+        return "policy_changed";
+    if (previous.scope !== current.scope)
+        return "scope_changed";
+    if (previous.semantic_fingerprint !== current.semantic_fingerprint)
+        return "meaning_changed";
+    return null;
+}
+function latestComparableRecord(records, candidateId, now) {
+    return records.filter(isCurrentReviewRecord).filter((record) => record.candidate_id === candidateId && record.disposition !== null && !terminalReviewRecordExpired(record, now)).sort((left, right) => Date.parse(right.queued_at) - Date.parse(left.queued_at) || compareGlossaryUnicodeStrings(left.review_id, right.review_id))[0] ?? null;
+}
+function publicationAuthorization(record) {
+    return record.review_record && ["accept", "correct"].includes(String(record.disposition))
+        ? { review_id: record.review_id, review_record_sha256: record.review_record.record_sha256 }
+        : null;
+}
+export function currentPersonalGlossaryReviewRecords(options = {}, now = new Date().toISOString()) {
+    if (!timestamp(now))
+        throw new TypeError("review read time must be an ISO timestamp");
+    const current = readPersonalGlossaryReviewRecords(options);
+    if (current.status === "missing")
+        return { status: "current", records: [], expired_records: 0, stale_records: 0 };
+    if (current.status !== "current" || current.store === null)
+        return { status: current.status, records: [], expired_records: 0, stale_records: 0 };
+    const projection = readCurrentPersonalGlossaryCandidateProjection(options);
+    // Keep stale metadata observable only through the existing degraded count.
+    if (projection.status === "projection_stale") {
+        return {
+            status: "current",
+            records: [],
+            expired_records: 0,
+            stale_records: current.store.records.length,
+        };
+    }
+    if (projection.status !== "current" || projection.projection === null)
+        return { status: "projection_unavailable", records: [], expired_records: 0, stale_records: 0 };
+    let expiredRecords = 0;
+    let staleRecords = 0;
+    const records = current.store.records.filter((record) => {
+        if (terminalReviewRecordExpired(record, now)) {
+            expiredRecords += 1;
+            return false;
+        }
+        if (!recordMatchesProjection(record, projection.projection)) {
+            staleRecords += 1;
+            return false;
+        }
+        return true;
+    }).map(readablePersonalGlossaryReviewRecord);
+    return { status: "current", records, expired_records: expiredRecords, stale_records: staleRecords };
+}
+/** Queue one current review-required decision without accepting a user disposition. */
+export function queuePersonalGlossaryReviewRecord(input) {
+    const queuedAt = input.now ?? new Date().toISOString();
+    if (!timestamp(queuedAt))
+        throw new TypeError("review queue time must be an ISO timestamp");
+    if (!mapping(input.receipt))
+        return { status: "decision_not_review_required", reason: "receipt_invalid", record: null, reopen_reason: null };
+    const options = { env: input.env, platform: input.platform };
+    const decisionResult = decidePersonalGlossaryCandidate(input.receipt, options);
+    if (decisionResult.status !== "review_required" || decisionResult.decision === null)
+        return { status: "decision_not_review_required", reason: decisionResult.reason, record: null, reopen_reason: null };
+    const decision = decisionResult.decision;
+    const projection = readCurrentPersonalGlossaryCandidateProjection(options);
+    if (projection.status !== "current" || projection.projection === null || projection.projection.projection_sha256 !== decision.candidate_projection_sha256)
+        return { status: "current_binding_mismatch", reason: "projection_unavailable", record: null, reopen_reason: null };
+    const candidate = exactCandidate(projection.projection.candidates, decision);
+    const scope = reviewScope(input.receipt);
+    if (!validPersonalGlossaryReviewGenerationBinding(decision.generation) || !validPersonalGlossaryReviewMetadataBinding(decision.policy_version))
+        return { status: "current_binding_mismatch", reason: "record_binding_mismatch", record: null, reopen_reason: null };
+    if (candidate === null || scope === null || validateGlossaryHostClassificationReceipt(input.receipt, candidate.capsule, { candidateProjectionSha256: projection.projection.projection_sha256 }).length > 0 || validateGlossaryAdmissionDecision(decision, candidate.capsule, input.receipt).length > 0)
+        return { status: "current_binding_mismatch", reason: "candidate_binding_mismatch", record: null, reopen_reason: null };
+    const current = readPersonalGlossaryReviewRecords(options);
+    if (current.status === "corrupt" || (current.store !== null && isLegacyReviewStore(current.store)))
+        return { status: "records_unavailable", reason: "review_records_unavailable", record: null, reopen_reason: null };
+    const records = current.store?.records ?? [];
+    const candidateRecord = pendingRecord(decision, scope, queuedAt, null);
+    const existing = records.find((record) => record.review_id === candidateRecord.review_id);
+    if (existing) {
+        if (!isCurrentReviewRecord(existing))
+            return { status: "records_unavailable", reason: "review_records_unavailable", record: null, reopen_reason: null };
+        if (suppresses(existing))
+            return { status: "suppressed", reason: existing.reason, record: existing, reopen_reason: null };
+        if (existing.status === "pending") {
+            ensurePersonalGlossaryReviewRecordsPrivate(personalGlossaryReviewRecordsPath(options));
+            return { status: "unchanged_replay", reason: existing.reason, record: existing, reopen_reason: existing.reopen_reason };
+        }
+        return { status: "already_terminal", reason: "review_already_terminal", record: null, reopen_reason: null };
+    }
+    const suppressed = records.filter(isCurrentReviewRecord).find((record) => !terminalReviewRecordExpired(record, queuedAt) && suppresses(record) && sameSuppressionBinding(record, candidateRecord));
+    if (suppressed)
+        return { status: "suppressed", reason: suppressed.reason, record: suppressed, reopen_reason: null };
+    const previous = latestComparableRecord(records, decision.candidate_id, queuedAt);
+    const reopenReason = previous ? reopeningReason(previous, candidateRecord) : null;
+    const record = reopenReason === null ? candidateRecord : pendingRecord(decision, scope, queuedAt, reopenReason);
+    if (records.length >= personalGlossaryReviewRecordsStorageContract().recordsMax)
+        return { status: "record_capacity_exceeded", reason: "review_record_capacity_exceeded", record: null, reopen_reason: null };
+    privateWritePersonalGlossaryReviewRecords(personalGlossaryReviewRecordsPath(options), `${canonicalGlossaryJson(makePersonalGlossaryReviewStore([...records, record], current.store?.replay_index ?? []))}\n`);
+    return { status: reopenReason === null ? "queued" : "reopened", reason: record.reason, record, reopen_reason: reopenReason };
+}
+function currentRecordForDisposition(record, receipt) {
+    if (isCurrentReviewRecord(record))
+        return record;
+    const scope = reviewScope(receipt);
+    if (scope === null)
+        return null;
+    try {
+        return migrateLegacyPendingReviewRecord(record, scope);
+    }
+    catch {
+        return null;
+    }
+}
+/** Record one signed current-user disposition after current source and replay validation. */
+export function dispositionPersonalGlossaryReviewRecord(input) {
+    const now = input.now ?? new Date().toISOString();
+    if (!timestamp(now))
+        throw new TypeError("review disposition time must be an ISO timestamp");
+    if (!digest(input.review_id) || !mapping(input.receipt) || !mapping(input.approval))
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    const options = { env: input.env, platform: input.platform };
+    const current = readPersonalGlossaryReviewRecords(options);
+    if (current.status !== "current" || current.store === null)
+        return { status: current.status === "corrupt" ? "records_unavailable" : "review_not_found", record: null, publication_authorization: null };
+    const storedRecord = current.store.records.find((record) => record.review_id === input.review_id);
+    if (!storedRecord || terminalReviewRecordExpired(storedRecord, now))
+        return { status: "review_not_found", record: null, publication_authorization: null };
+    const decisionResult = decidePersonalGlossaryCandidate(input.receipt, options);
+    if (decisionResult.status !== "review_required" || decisionResult.decision === null)
+        return { status: "current_binding_mismatch", record: null, publication_authorization: null };
+    const decision = decisionResult.decision;
+    const projection = readCurrentPersonalGlossaryCandidateProjection(options);
+    if (projection.status !== "current" || projection.projection === null || !recordMatchesProjection(storedRecord, projection.projection))
+        return { status: "current_binding_mismatch", record: null, publication_authorization: null };
+    const candidate = exactCandidate(projection.projection.candidates, decision);
+    if (candidate === null || decision.candidate_id !== storedRecord.candidate_id || decision.candidate_revision !== storedRecord.candidate_revision || decision.candidate_capsule_sha256 !== storedRecord.candidate_capsule_sha256 || decision.candidate_projection_sha256 !== storedRecord.candidate_projection_sha256 || decision.host_receipt_sha256 !== storedRecord.host_receipt_sha256 || decision.decision_sha256 !== storedRecord.cli_decision_sha256 || decision.semantic_fingerprint !== storedRecord.semantic_fingerprint || decision.generation !== storedRecord.generation || decision.policy_version !== storedRecord.policy_version || validateGlossaryHostClassificationReceipt(input.receipt, candidate.capsule, { candidateProjectionSha256: projection.projection.projection_sha256 }).length > 0 || validateGlossaryAdmissionDecision(decision, candidate.capsule, input.receipt).length > 0)
+        return { status: "current_binding_mismatch", record: null, publication_authorization: null };
+    const record = currentRecordForDisposition(storedRecord, input.receipt);
+    if (!record)
+        return { status: "current_binding_mismatch", record: null, publication_authorization: null };
+    const trustedHost = readPersonalGlossaryTrustedLocalHost(options);
+    if (!trustedHost)
+        return { status: "approval_unavailable", record: null, publication_authorization: null };
+    const replayEntries = isCurrentReviewStore(current.store) ? currentReplayIndex(current.store.replay_index, now) : [];
+    const replayNonceKey = typeof input.approval.nonce === "string" ? replayNonceDigest(input.approval.nonce) : undefined;
+    const errors = validatePersonalReviewApprovalReceipt(input.approval, {
+        currentUserSubject: trustedHost.subject,
+        reviewId: record.review_id,
+        candidateId: record.candidate_id,
+        candidateRevision: record.candidate_revision,
+        candidateProjectionSha256: record.candidate_projection_sha256,
+        semanticFingerprint: record.semantic_fingerprint,
+        generation: record.generation,
+        policyVersion: record.policy_version,
+        now: new Date(now),
+        trustedHostPublicKey: trustedHost.publicKey,
+        consumedReceiptDigests: activeReplayDigestMap(replayEntries, now),
+        replayNonceKey,
+    });
+    let replay;
+    let receiptDigest;
+    let nonceDigest;
+    try {
+        replay = personalReviewApprovalReplayStatus(input.approval, replayDigestMap(replayEntries), replayNonceKey);
+        receiptDigest = personalReviewApprovalReceiptDigest(input.approval);
+        nonceDigest = replayNonceDigest(String(input.approval.nonce));
+    }
+    catch {
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    }
+    if (replay === "conflicting_replay")
+        return { status: "approval_conflicting_replay", record: null, publication_authorization: null };
+    if (errors.length > 0)
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    if (replay === "exact_replay")
+        return { status: "unchanged_replay", record, publication_authorization: publicationAuthorization(record) };
+    if (record.status === "terminal")
+        return { status: "review_not_pending", record: null, publication_authorization: null };
+    const disposition = input.approval.disposition;
+    if (disposition === "correct" && typeof input.approval.corrected_meaning !== "string")
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    if (replayEntries.length >= personalGlossaryReviewRecordsStorageContract().replayEntriesMax)
+        return { status: "replay_capacity_exceeded", record: null, publication_authorization: null };
+    let review;
+    try {
+        review = createGlossaryReviewRecord({
+            capsule: candidate.capsule,
+            receipt: input.receipt,
+            decision,
+            disposition,
+            corrected_meaning: input.approval.corrected_meaning,
+            corrected_scope: input.approval.corrected_scope,
+            disposed_at: input.approval.disposed_at,
+            expires_at: reviewExpiry(input.approval.disposed_at),
+        });
+    }
+    catch {
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    }
+    const terminal = personalReviewDispositionLifecycle(disposition) === "terminal";
+    let nextRecord;
+    try {
+        nextRecord = sealPersonalGlossaryReviewRecord({
+            ...record,
+            scope: disposition === "correct" ? "personal" : record.scope,
+            status: terminal ? "terminal" : "pending",
+            disposition,
+            review_record: review,
+            terminal_at: terminal ? review.disposed_at : null,
+            expires_at: terminal ? review.expires_at : null,
+        });
+    }
+    catch {
+        return { status: "approval_invalid", record: null, publication_authorization: null };
+    }
+    const replayEntry = { nonce_sha256: nonceDigest, receipt_sha256: receiptDigest, expires_at: input.approval.expires_at };
+    const next = makePersonalGlossaryReviewStore(current.store.records.map((item) => item.review_id === record.review_id ? nextRecord : item), [...replayEntries, replayEntry]);
+    try {
+        privateWritePersonalGlossaryReviewRecords(personalGlossaryReviewRecordsPath(options), `${canonicalGlossaryJson(next)}\n`);
+    }
+    catch {
+        return { status: "records_unavailable", record: null, publication_authorization: null };
+    }
+    return { status: "disposed", record: nextRecord, publication_authorization: publicationAuthorization(nextRecord) };
+}
+/** Resolve one stored accept/correct authorization without treating it as current evidence. */
+export function personalGlossaryReviewPublicationAuthorization(input) {
+    const now = input.now ?? new Date().toISOString();
+    if (!timestamp(now) || !digest(input.review_id) || !digest(input.review_record_sha256))
+        return { status: "binding_mismatch", review: null };
+    const current = readPersonalGlossaryReviewRecords({ env: input.env, platform: input.platform });
+    if (current.status !== "current" || current.store === null)
+        return { status: "unavailable", review: null };
+    const projection = readCurrentPersonalGlossaryCandidateProjection({ env: input.env, platform: input.platform });
+    if (projection.status !== "current" || projection.projection === null)
+        return { status: "unavailable", review: null };
+    const storedRecord = current.store.records.find((record) => record.review_id === input.review_id);
+    if (!storedRecord || !isCurrentReviewRecord(storedRecord) || terminalReviewRecordExpired(storedRecord, now) || !storedRecord.review_record || storedRecord.status !== "terminal")
+        return { status: "not_publishable", review: null };
+    if (storedRecord.review_record.record_sha256 !== input.review_record_sha256 || !["accept", "correct"].includes(String(storedRecord.disposition)) || !recordMatchesProjection(storedRecord, projection.projection) || storedRecord.candidate_projection_sha256 !== input.candidate_projection_sha256 || storedRecord.candidate_id !== input.capsule.candidate_id || storedRecord.candidate_revision !== input.capsule.candidate_revision || storedRecord.candidate_capsule_sha256 !== input.capsule.capsule_sha256 || storedRecord.host_receipt_sha256 !== input.receipt.receipt_sha256 || storedRecord.cli_decision_sha256 !== input.decision.decision_sha256 || storedRecord.semantic_fingerprint !== input.receipt.semantic_fingerprint || storedRecord.generation !== input.capsule.generation || storedRecord.policy_version !== input.capsule.policy_version || validateGlossaryReviewRecord(storedRecord.review_record, input.capsule, input.receipt, input.decision).length > 0)
+        return { status: "binding_mismatch", review: null };
+    return { status: "authorized", review: storedRecord.review_record };
+}
+/** Remove expired terminal metadata and receipt replay digests, or a purged local store only. */
+export function maintainPersonalGlossaryReviewRecords(input) {
+    if (!timestamp(input.now))
+        throw new TypeError("review maintenance time must be an ISO timestamp");
+    const options = { env: input.env, platform: input.platform };
+    const current = readPersonalGlossaryReviewRecords(options);
+    if (current.status === "missing" || current.status === "corrupt")
+        return { status: current.status, expired_records: 0, expired_receipts: 0 };
+    const pathname = personalGlossaryReviewRecordsPath(options);
+    if (input.current_user_purge_authorized === true) {
+        fs.rmSync(pathname, { force: true });
+        return { status: "purged", expired_records: 0, expired_receipts: 0 };
+    }
+    if (isLegacyReviewStore(current.store))
+        return { status: "unchanged", expired_records: 0, expired_receipts: 0 };
+    const records = current.store.records.filter((record) => !terminalReviewRecordExpired(record, input.now));
+    const replayIndex = currentReplayIndex(current.store.replay_index, input.now);
+    const expiredRecords = current.store.records.length - records.length;
+    const expiredReceipts = current.store.replay_index.length - replayIndex.length;
+    if (expiredRecords === 0 && expiredReceipts === 0)
+        return { status: "unchanged", expired_records: 0, expired_receipts: 0 };
+    if (records.length === 0 && replayIndex.length === 0)
+        fs.rmSync(pathname, { force: true });
+    else
+        privateWritePersonalGlossaryReviewRecords(pathname, `${canonicalGlossaryJson(makePersonalGlossaryReviewStore(records, replayIndex))}\n`);
+    return { status: "changed", expired_records: expiredRecords, expired_receipts: expiredReceipts };
+}

package/dist/analytics/profileSignals.js

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