@yadsh/dsh-qa-surface 0.6.1 → 0.7.0

package/lib/admin/service.js

@@ -0,0 +1,897 @@
+import { QaAccountsError } from "../accounts/store.js";
+import { defaultCapabilityConfig, normalizeUserAccess, } from "../access/model.js";
+import { allows } from "./permissions.js";
+import { aggregateQuality } from "./metrics.js";
+import { paginate } from "./paging.js";
+import { deriveQueue } from "./queue.js";
+import { defaultAdminRedactor } from "./redaction.js";
+import { projectTranscript, } from "./conversation-log.js";
+/**
+ * The administrative console's server side.
+ *
+ * Every entry point takes the caller's token and names the permission it
+ * needs; there is no `isAdmin` shortcut and no client-supplied identity. The
+ * browser may only ever read what a role grants, and every write lands in the
+ * audit trail with its before and after images.
+ */
+export const QA_ADMIN_PAGE_DEFAULT = 25;
+export const QA_ADMIN_PAGE_MAX = 100;
+/**
+ * How many conversations one metrics or search pass will open. Reading every
+ * stored log is unbounded work, so the aggregation covers the newest logs and
+ * says so; moving these counters onto a real index is the next iteration.
+ */
+export const QA_ADMIN_SCAN_LIMIT = 200;
+/** How long one projected log may serve the list and metrics before re-reading. */
+const TRANSCRIPT_TTL_MS = 30_000;
+const TRANSCRIPT_CACHE_MAX = 128;
+function isoOf(epochMs) {
+    return new Date(epochMs).toISOString();
+}
+function epochOf(iso) {
+    if (iso === undefined || iso === "")
+        return undefined;
+    const parsed = Date.parse(iso);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}
+function clampLimit(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return QA_ADMIN_PAGE_DEFAULT;
+    return Math.max(1, Math.min(QA_ADMIN_PAGE_MAX, Math.floor(value)));
+}
+function matches(search, ...values) {
+    const needle = search.trim().toLocaleLowerCase();
+    if (needle === "")
+        return true;
+    return values.some((value) => value?.toLocaleLowerCase().includes(needle) === true);
+}
+/**
+ * Treat an absent filter and an explicit null alike. The browser sends the
+ * field either way, and a null that reached a comparison would filter on the
+ * absence of a value instead of meaning "no filter at all".
+ */
+function given(value) {
+    return value === null ? undefined : value;
+}
+/**
+ * Review state of a conversation as a whole: a needs-followup verdict outranks
+ * a completed one, and no review at all is the unreviewed default.
+ */
+function reviewStatusOf(reviews, conversationId) {
+    const mine = reviews.filter((row) => row.conversationId === conversationId);
+    if (mine.length === 0)
+        return "unreviewed";
+    return mine.some((row) => row.status === "needs_followup")
+        ? "needs_followup"
+        : "reviewed";
+}
+export class QaAdminService {
+    options;
+    redactor;
+    transcripts = new Map();
+    constructor(options) {
+        this.options = options;
+        this.redactor = options.redactor ?? defaultAdminRedactor;
+    }
+    // -------------------------------------------------------------------------
+    // Authorization
+    // -------------------------------------------------------------------------
+    requireAccounts() {
+        const accounts = this.options.accounts();
+        if (accounts === undefined) {
+            throw new Error("QA accounts are not enabled on this deployment.");
+        }
+        return accounts;
+    }
+    /**
+     * Resolve the caller and check one permission. The refusal carries the shared
+     * `forbidden` reason, so a browser shows the same audience-safe copy for
+     * every administrative surface it may not open.
+     */
+    require(token, permission) {
+        const accounts = this.requireAccounts();
+        const actor = accounts.currentUser(token);
+        if (!allows(actor.role, permission)) {
+            this.options.logger.warn("admin.forbidden", {
+                userId: actor.id,
+                role: actor.role,
+                permission,
+            });
+            throw new QaAccountsError("forbidden", `the ${actor.role} role does not grant ${permission}`);
+        }
+        return { accounts, actor };
+    }
+    // -------------------------------------------------------------------------
+    // Conversation index
+    // -------------------------------------------------------------------------
+    /**
+     * The deployment's conversation index: one row per reserved QA session,
+     * enriched with the stored header when the deployment can list one. A chat
+     * that exists but has no readable log still appears — the reviewer must see
+     * that it happened.
+     */
+    async index() {
+        const accounts = this.requireAccounts();
+        const directory = new Map(accounts.directory().map((user) => [user.id, user]));
+        const headers = new Map((await this.options.sessionLog.list()).map((header) => [
+            header.id,
+            header,
+        ]));
+        return accounts
+            .listOwnershipRecords()
+            .map((record) => {
+            const header = headers.get(record.sessionId);
+            // A subagent's session is an implementation detail of one answer, not a
+            // conversation a user had.
+            if (header?.parentSessionId !== undefined) {
+                return undefined;
+            }
+            const createdAt = header?.createdAt ?? Date.parse(record.claimedAt);
+            const snapshot = record.capabilitySnapshot;
+            return {
+                conversationId: record.sessionId,
+                userId: record.userId,
+                displayName: directory.get(record.userId)?.displayName ?? record.userId,
+                email: directory.get(record.userId)?.email ?? "",
+                subroleId: record.subroleId ?? "",
+                adminPreview: record.adminPreview === true,
+                createdAt,
+                createdAtIso: isoOf(createdAt),
+                ...(snapshot === undefined
+                    ? {}
+                    : {
+                        effectiveTools: snapshot.tools,
+                        effectiveSkills: snapshot.skills,
+                    }),
+            };
+        })
+            .filter((row) => row !== undefined);
+    }
+    /** One conversation's projected log, cached for the TTL unless asked fresh. */
+    async transcript(conversationId, fresh = false) {
+        const cached = this.transcripts.get(conversationId);
+        const now = this.options.clock?.now() ?? Date.now();
+        if (!fresh && cached !== undefined && now - cached.at < TRANSCRIPT_TTL_MS) {
+            return { ok: true, project: cached.project };
+        }
+        const result = await this.options.sessionLog.read(conversationId);
+        if (!result.ok) {
+            this.transcripts.delete(conversationId);
+            return { ok: false, reason: result.reason };
+        }
+        const project = projectTranscript(result.events, this.redactor);
+        this.transcripts.set(conversationId, { at: now, project });
+        if (this.transcripts.size > TRANSCRIPT_CACHE_MAX) {
+            const oldest = [...this.transcripts.entries()].sort((left, right) => left[1].at - right[1].at)[0];
+            if (oldest !== undefined)
+                this.transcripts.delete(oldest[0]);
+        }
+        return { ok: true, project };
+    }
+    async facts(rows) {
+        const facts = [];
+        for (const row of rows) {
+            const transcript = await this.transcript(row.conversationId);
+            facts.push({
+                conversationId: row.conversationId,
+                userId: row.userId,
+                subroleId: row.subroleId,
+                assistantMessages: transcript.ok
+                    ? transcript.project.messages.filter((message) => message.role === "assistant").length
+                    : 0,
+                createdAt: row.createdAt,
+            });
+        }
+        return facts;
+    }
+    // -------------------------------------------------------------------------
+    // Overview and metrics
+    // -------------------------------------------------------------------------
+    async overview(token) {
+        this.require(token, "conversations.read.all");
+        const rows = await this.index();
+        const metrics = await this.metricsOf(rows);
+        const fresh = [...this.options.quality().allFeedback()].sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+        const queue = await this.queueRows(rows);
+        return Object.freeze({
+            metrics,
+            alerts: this.alertsOf(metrics),
+            recentFeedback: this.feedbackRows(rows, fresh.slice(0, 5), this.options.quality().allReviews()),
+            queue: queue.slice(0, 5),
+        });
+    }
+    async metrics(token) {
+        this.require(token, "analytics.read");
+        return this.metricsOf(await this.index());
+    }
+    async metricsOf(rows) {
+        const quality = this.options.quality();
+        // Feedback and reviews are exact; the message counts come from the bounded
+        // log scan and are labelled as such where they are shown.
+        const scanned = [...rows]
+            .sort((left, right) => right.createdAt - left.createdAt)
+            .slice(0, QA_ADMIN_SCAN_LIMIT);
+        return aggregateQuality({
+            conversations: await this.facts(scanned),
+            feedback: quality.allFeedback(),
+            reviews: quality.allReviews(),
+        });
+    }
+    /** One attention line per condition worth an administrator's time. */
+    alertsOf(metrics) {
+        const alerts = [];
+        if (metrics.unreviewedNegatives > 0) {
+            alerts.push({
+                level: "critical",
+                code: "unreviewed-negatives",
+                count: metrics.unreviewedNegatives,
+            });
+        }
+        if (metrics.positiveRate !== null) {
+            for (const row of metrics.bySubrole) {
+                if (row.rated < 5 || row.positiveRate === null)
+                    continue;
+                if (row.positiveRate <= metrics.positiveRate - 0.1) {
+                    alerts.push({
+                        level: "warning",
+                        code: "subrole-satisfaction",
+                        count: row.rated,
+                        subject: row.key,
+                        rate: row.positiveRate,
+                    });
+                }
+            }
+        }
+        const reasons = new Map();
+        for (const row of this.options.quality().allFeedback()) {
+            if (row.rating !== "negative")
+                continue;
+            for (const reason of row.reasons ?? []) {
+                reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
+            }
+        }
+        for (const [reason, count] of [...reasons].sort((left, right) => right[1] - left[1])) {
+            if (count >= 3) {
+                alerts.push({
+                    level: "warning",
+                    code: "recurring-reason",
+                    count,
+                    subject: reason,
+                });
+            }
+        }
+        return Object.freeze(alerts.map((alert) => Object.freeze(alert)));
+    }
+    // -------------------------------------------------------------------------
+    // Users
+    // -------------------------------------------------------------------------
+    async users(token, query, cursor, limit) {
+        const { accounts } = this.require(token, "users.read");
+        const config = this.options.roles().snapshot();
+        const rows = accounts.listAdminUsers((value) => normalizeUserAccess(value, config));
+        const feedback = this.options.quality().allFeedback();
+        const ownership = accounts.listOwnershipRecords();
+        const enriched = rows.map((user) => Object.freeze({
+            ...user,
+            conversations: ownership.filter((row) => row.userId === user.id).length,
+            feedbackGiven: feedback.filter((row) => row.userId === user.id).length,
+        }));
+        const status = given(query.status);
+        const role = given(query.role);
+        const subroleId = given(query.subroleId);
+        const search = given(query.search) ?? "";
+        const filtered = enriched.filter((user) => {
+            if (status === "active" && user.disabled)
+                return false;
+            if (status === "disabled" && !user.disabled)
+                return false;
+            if (role !== undefined && user.role !== role)
+                return false;
+            if (subroleId !== undefined &&
+                !user.access.allowedSubroles.includes(subroleId)) {
+                return false;
+            }
+            return matches(search, user.displayName, user.fullName, user.email);
+        });
+        const sorted = [...filtered].sort((left, right) => left.displayName.localeCompare(right.displayName, "ru"));
+        return paginate({
+            rows: sorted,
+            keyOf: (row) => row.displayName.toLocaleLowerCase(),
+            idOf: (row) => row.id,
+            cursor,
+            limit: clampLimit(limit),
+        });
+    }
+    async user(token, userId) {
+        const { accounts } = this.require(token, "users.read");
+        const config = this.options.roles().snapshot();
+        const row = accounts.adminUser(userId, (value) => normalizeUserAccess(value, config));
+        if (row === undefined) {
+            throw new QaAccountsError("invalid-credentials", "no such account");
+        }
+        const feedback = this.options.quality().allFeedback();
+        const ownership = accounts
+            .listOwnershipRecords()
+            .filter((record) => record.userId === userId);
+        const catalog = await this.options.access().catalog.snapshot();
+        const effective = row.access.allowedSubroles.map((subroleId) => {
+            const role = config.subroles.find(({ id }) => id === subroleId);
+            const installed = (values, set) => [...new Set(values)].filter((id) => set.has(id)).length;
+            const toolIds = [
+                ...config.common.tools.always,
+                ...config.common.tools.skillGrantable,
+                ...(role?.capabilities.tools.always ?? []),
+                ...(role?.capabilities.tools.skillGrantable ?? []),
+            ];
+            return Object.freeze({
+                subroleId,
+                name: role?.name ?? subroleId,
+                tools: installed(toolIds, catalog.toolIds),
+                skills: installed(config.common.skills, catalog.skillIds) +
+                    installed(role?.capabilities.skills ?? [], catalog.skillIds),
+            });
+        });
+        let messages = 0;
+        for (const record of ownership.slice(0, QA_ADMIN_SCAN_LIMIT)) {
+            const transcript = await this.transcript(record.sessionId);
+            if (transcript.ok)
+                messages += transcript.project.messages.length;
+        }
+        const userFeedback = feedback.filter((item) => item.userId === userId);
+        return Object.freeze({
+            user: Object.freeze({
+                ...row,
+                conversations: ownership.length,
+                feedbackGiven: userFeedback.length,
+            }),
+            effective: Object.freeze(effective),
+            activity: Object.freeze({
+                conversations: ownership.length,
+                messages,
+                positiveRatings: userFeedback.filter(({ rating }) => rating === "positive").length,
+                negativeRatings: userFeedback.filter(({ rating }) => rating === "negative").length,
+            }),
+        });
+    }
+    async updateUser(token, userId, update) {
+        const { accounts, actor } = this.require(token, "users.manage");
+        const config = this.options.roles().snapshot();
+        const before = accounts.adminUser(userId, (value) => normalizeUserAccess(value, config));
+        if (before === undefined) {
+            throw new QaAccountsError("invalid-credentials", "no such account");
+        }
+        const nextRole = given(update.role);
+        const nextDisabled = given(update.disabled);
+        const nextAccess = given(update.access);
+        if (nextRole !== undefined && nextRole !== before.role) {
+            this.assertAdminSurvives(accounts, userId, nextRole);
+            accounts.setAccessRole(userId, nextRole);
+            this.options.quality().appendAudit({
+                actorId: actor.id,
+                action: "authorization.changed",
+                targetType: "user",
+                targetId: userId,
+                before: before.role,
+                after: nextRole,
+            });
+        }
+        if (nextDisabled !== undefined && nextDisabled !== before.disabled) {
+            if (nextDisabled)
+                this.assertAdminSurvives(accounts, userId, "user");
+            accounts.setAccessDisabled(userId, nextDisabled);
+            this.options.quality().appendAudit({
+                actorId: actor.id,
+                action: nextDisabled ? "user.disabled" : "user.enabled",
+                targetType: "user",
+                targetId: userId,
+            });
+        }
+        if (nextAccess !== undefined) {
+            const access = this.exactAssignment(nextAccess, userId);
+            accounts.setAccess(userId, access);
+            this.options.quality().appendAudit({
+                actorId: actor.id,
+                action: "subrole.assignment.changed",
+                targetType: "user",
+                targetId: userId,
+                before: before.access,
+                after: access,
+            });
+        }
+        this.options.logger.info("admin.user-updated", { userId, actor: actor.id });
+        return this.user(token, userId);
+    }
+    /**
+     * Refuse a write that would leave the deployment without a usable admin.
+     * Granting the admin role carries no such risk; demoting or disabling the
+     * last enabled administrator locks everyone out of the console.
+     */
+    assertAdminSurvives(accounts, targetId, nextRole) {
+        if (nextRole === "admin")
+            return;
+        const admins = accounts
+            .listAdminUsers((value) => normalizeUserAccess(value, defaultCapabilityConfig()))
+            .filter((user) => user.role === "admin" && !user.disabled);
+        const survivor = admins.some((user) => user.id !== targetId);
+        if (!survivor) {
+            throw new QaAccountsError("forbidden", "the deployment must keep at least one enabled administrator");
+        }
+    }
+    /** Validate an assignment against the enabled roles before storing it. */
+    exactAssignment(input, userId) {
+        const config = this.options.roles().snapshot();
+        const enabled = new Set(config.subroles.filter(({ enabled }) => enabled).map(({ id }) => id));
+        const allowed = [...new Set(input.allowedSubroles)];
+        if (allowed.length === 0 ||
+            !allowed.every((id) => enabled.has(id)) ||
+            !allowed.includes(input.defaultSubrole)) {
+            this.options.logger.warn("admin.assignment-rejected", { userId });
+            throw new QaAccountsError("invalid-role", "an assignment must name enabled roles and select one of them");
+        }
+        return Object.freeze({
+            allowedSubroles: Object.freeze(allowed),
+            defaultSubrole: input.defaultSubrole,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Conversations
+    // -------------------------------------------------------------------------
+    async conversations(token, query, cursor, limit) {
+        this.require(token, "conversations.read.all");
+        const rows = await this.index();
+        const quality = this.options.quality();
+        const feedback = quality.allFeedback();
+        const reviews = quality.allReviews();
+        const userIdFilter = given(query.userId);
+        const subroleFilter = given(query.subroleId);
+        const ratingFilter = given(query.rating);
+        const reviewFilter = given(query.reviewStatus);
+        const search = given(query.search) ?? "";
+        const from = epochOf(given(query.from) ?? undefined);
+        const to = epochOf(given(query.to) ?? undefined);
+        // A search may name a title, which only the log knows, so the candidate
+        // set is bounded by the newest logs before the text is available.
+        const searchable = search.trim() === ""
+            ? rows
+            : [...rows]
+                .sort((left, right) => right.createdAt - left.createdAt)
+                .slice(0, QA_ADMIN_SCAN_LIMIT);
+        const candidates = [];
+        for (const row of searchable) {
+            if (userIdFilter !== undefined && row.userId !== userIdFilter)
+                continue;
+            if (subroleFilter !== undefined && row.subroleId !== subroleFilter) {
+                continue;
+            }
+            if (from !== undefined && row.createdAt < from)
+                continue;
+            if (to !== undefined && row.createdAt > to)
+                continue;
+            const mine = feedback.filter((item) => item.conversationId === row.conversationId);
+            if (ratingFilter !== undefined &&
+                !mine.some((item) => item.rating === ratingFilter)) {
+                continue;
+            }
+            if (reviewFilter !== undefined &&
+                reviewStatusOf(reviews, row.conversationId) !== reviewFilter) {
+                continue;
+            }
+            // One projection per candidate, reused by the search match and then by
+            // the summary of a page row: the read is cached either way.
+            const transcript = await this.transcript(row.conversationId);
+            const title = transcript.ok ? transcript.project.title : undefined;
+            if (!matches(search, row.displayName, row.email, row.userId, row.conversationId, title)) {
+                continue;
+            }
+            candidates.push(row);
+        }
+        const sorted = candidates.sort((left, right) => right.createdAt - left.createdAt);
+        const page = paginate({
+            rows: sorted,
+            keyOf: (row) => row.createdAtIso,
+            idOf: (row) => row.conversationId,
+            cursor,
+            limit: clampLimit(limit),
+        });
+        const items = [];
+        for (const row of page.items) {
+            items.push(await this.summaryOf(row, feedback, reviews));
+        }
+        return {
+            items: Object.freeze(items),
+            nextCursor: page.nextCursor,
+            total: page.total,
+        };
+    }
+    async summaryOf(row, feedback, reviews) {
+        const transcript = await this.transcript(row.conversationId);
+        const mine = feedback.filter((item) => item.conversationId === row.conversationId);
+        const lastActivity = transcript.ok
+            ? transcript.project.lastActivity
+            : undefined;
+        const title = transcript.ok ? transcript.project.title : undefined;
+        return Object.freeze({
+            conversationId: row.conversationId,
+            userId: row.userId,
+            displayName: row.displayName,
+            subroleId: row.subroleId,
+            createdAt: row.createdAtIso,
+            updatedAt: isoOf(Math.max(row.createdAt, lastActivity ?? row.createdAt)),
+            ...(title === undefined ? {} : { title }),
+            messageCount: transcript.ok ? transcript.project.messages.length : 0,
+            positiveFeedback: mine.filter(({ rating }) => rating === "positive")
+                .length,
+            negativeFeedback: mine.filter(({ rating }) => rating === "negative")
+                .length,
+            reviewStatus: reviewStatusOf(reviews, row.conversationId),
+        });
+    }
+    async conversation(token, conversationId) {
+        const { accounts, actor } = this.require(token, "conversations.read.own");
+        const owner = accounts.ownerIdOf(conversationId);
+        if (owner === undefined) {
+            throw new QaAccountsError("session-owned-elsewhere", "this conversation is unknown to the deployment");
+        }
+        // Reading someone else's conversation is exactly what
+        // `conversations.read.all` buys; owning it is what the base permission buys.
+        if (owner !== actor.id && !allows(actor.role, "conversations.read.all")) {
+            this.options.logger.warn("admin.conversation-forbidden", {
+                userId: actor.id,
+                conversationId,
+            });
+            throw new QaAccountsError("forbidden", "this conversation belongs to another account");
+        }
+        const rows = await this.index();
+        const row = rows.find((entry) => entry.conversationId === conversationId);
+        if (row === undefined) {
+            throw new QaAccountsError("session-owned-elsewhere", "this conversation is unknown to the deployment");
+        }
+        const quality = this.options.quality();
+        const feedback = quality.allFeedback();
+        const reviews = quality.allReviews();
+        const summary = await this.summaryOf(row, feedback, reviews);
+        const transcript = await this.transcript(conversationId, true);
+        const project = transcript.ok ? transcript.project : undefined;
+        const messages = (project?.messages ?? []).map((message) => Object.freeze({
+            ...message,
+            feedback: Object.freeze(feedback.filter((item) => item.conversationId === conversationId &&
+                item.messageId === message.id)),
+            reviews: Object.freeze(reviews.filter((item) => item.conversationId === conversationId &&
+                item.messageId === message.id)),
+        }));
+        return Object.freeze({
+            conversationId,
+            summary,
+            runtime: Object.freeze({
+                subroleId: row.subroleId,
+                adminPreview: row.adminPreview,
+                ...(project?.model === undefined ? {} : { model: project.model }),
+                ...(project?.provider === undefined
+                    ? {}
+                    : { provider: project.provider }),
+                ...(row.effectiveTools === undefined
+                    ? {}
+                    : { effectiveTools: row.effectiveTools }),
+                ...(row.effectiveSkills === undefined
+                    ? {}
+                    : { effectiveSkills: row.effectiveSkills }),
+                ...(project === undefined
+                    ? {}
+                    : { loadedSkills: project.loadedSkills }),
+                ...(transcript.ok
+                    ? {}
+                    : { transcriptUnavailable: transcript.reason }),
+            }),
+            messages: Object.freeze(messages),
+            reviews: Object.freeze(reviews.filter((item) => item.conversationId === conversationId)),
+            queueItems: Object.freeze(deriveQueue({
+                feedback,
+                reviews,
+                manual: quality.manualQueue(),
+                failures: this.failuresOf(conversationId, project),
+            }).filter((item) => item.conversationId === conversationId)),
+        });
+    }
+    failuresOf(conversationId, project) {
+        if (project === undefined)
+            return [];
+        const signals = [];
+        for (const message of project.messages) {
+            for (const call of message.toolCalls ?? []) {
+                if (call.error === undefined)
+                    continue;
+                signals.push({
+                    conversationId,
+                    messageId: message.id,
+                    at: isoOf(call.time ?? message.time),
+                });
+            }
+        }
+        return signals;
+    }
+    async failureSignals(rows) {
+        const signals = [];
+        for (const row of rows) {
+            const transcript = await this.transcript(row.conversationId);
+            if (!transcript.ok)
+                continue;
+            signals.push(...this.failuresOf(row.conversationId, transcript.project));
+        }
+        return signals;
+    }
+    // -------------------------------------------------------------------------
+    // Feedback
+    // -------------------------------------------------------------------------
+    /**
+     * Record the caller's verdict on one assistant message. The conversation must
+     * be the caller's own: a rating is the user's own signal, and nobody rates
+     * someone else's answer on their behalf.
+     */
+    rateMessage(token, conversationId, messageId, input) {
+        const { accounts, actor } = this.require(token, "conversations.read.own");
+        if (accounts.ownerIdOf(conversationId) !== actor.id) {
+            throw new QaAccountsError("forbidden", "feedback may only be given on your own conversations");
+        }
+        const record = this.options
+            .quality()
+            .rateFeedback({ conversationId, messageId, userId: actor.id }, input);
+        this.options.logger.info("admin.feedback-recorded", {
+            conversationId,
+            messageId,
+            rating: record.rating,
+            userId: actor.id,
+        });
+        return record;
+    }
+    async feedback(token, query, cursor, limit) {
+        this.require(token, "reviews.read");
+        const rows = await this.index();
+        const quality = this.options.quality();
+        const reviews = quality.allReviews();
+        const ratingFilter = given(query.rating);
+        const userFilter = given(query.userId);
+        const subroleFilter = given(query.subroleId);
+        const reasonFilter = given(query.reason);
+        const reviewFilter = given(query.reviewStatus);
+        const from = epochOf(given(query.from) ?? undefined);
+        const to = epochOf(given(query.to) ?? undefined);
+        const conversations = new Map(rows.map((row) => [row.conversationId, row]));
+        const filtered = quality.allFeedback().filter((row) => {
+            const conversation = conversations.get(row.conversationId);
+            if (ratingFilter !== undefined && row.rating !== ratingFilter)
+                return false;
+            if (userFilter !== undefined && row.userId !== userFilter)
+                return false;
+            if (subroleFilter !== undefined &&
+                conversation?.subroleId !== subroleFilter) {
+                return false;
+            }
+            if (reasonFilter !== undefined &&
+                !(row.reasons ?? []).includes(reasonFilter)) {
+                return false;
+            }
+            const at = epochOf(row.createdAt);
+            if (from !== undefined && (at === undefined || at < from))
+                return false;
+            if (to !== undefined && (at === undefined || at > to))
+                return false;
+            if (reviewFilter !== undefined &&
+                reviewStatusOf(reviews, row.conversationId) !== reviewFilter) {
+                return false;
+            }
+            return true;
+        });
+        const sorted = [...filtered].sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+        const page = paginate({
+            rows: sorted,
+            keyOf: (row) => row.createdAt,
+            idOf: (row) => row.id,
+            cursor,
+            limit: clampLimit(limit),
+        });
+        // Titles are read for the rows on this page only: a title lives in the
+        // conversation's log, and paging is what keeps that work bounded.
+        const titles = new Map();
+        for (const row of page.items) {
+            const transcript = await this.transcript(row.conversationId);
+            titles.set(row.conversationId, transcript.ok ? transcript.project.title : undefined);
+        }
+        return {
+            items: Object.freeze(this.feedbackRows(rows, page.items, reviews, titles)),
+            nextCursor: page.nextCursor,
+            total: page.total,
+        };
+    }
+    feedbackRows(rows, feedback, reviews, titles = new Map()) {
+        const conversations = new Map(rows.map((row) => [row.conversationId, row]));
+        return feedback.map((row) => {
+            const conversation = conversations.get(row.conversationId);
+            const title = titles.get(row.conversationId);
+            return Object.freeze({
+                ...row,
+                displayName: conversation?.displayName ?? row.userId,
+                subroleId: conversation?.subroleId ?? "",
+                ...(title === undefined ? {} : { conversationTitle: title }),
+                reviewStatus: reviewStatusOf(reviews, row.conversationId),
+            });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Review queue and results
+    // -------------------------------------------------------------------------
+    async queueRows(rows) {
+        const conversations = rows ?? (await this.index());
+        const quality = this.options.quality();
+        const reviews = quality.allReviews();
+        const byId = new Map(conversations.map((row) => [row.conversationId, row]));
+        const queue = deriveQueue({
+            feedback: quality.allFeedback(),
+            reviews,
+            manual: quality.manualQueue(),
+            failures: await this.failureSignals([...conversations]
+                .sort((left, right) => right.createdAt - left.createdAt)
+                .slice(0, QA_ADMIN_SCAN_LIMIT)),
+        });
+        const result = [];
+        for (const item of queue) {
+            const row = byId.get(item.conversationId);
+            if (row === undefined)
+                continue;
+            const transcript = await this.transcript(item.conversationId);
+            const review = reviews.find((entry) => entry.id === item.reviewId);
+            result.push(Object.freeze({
+                ...item,
+                displayName: row.displayName,
+                subroleId: row.subroleId,
+                ...(transcript.ok && transcript.project.title !== undefined
+                    ? { title: transcript.project.title }
+                    : {}),
+                raisedAtLabel: item.raisedAt,
+                ...(review === undefined
+                    ? {}
+                    : {
+                        issueSummary: review.issues,
+                        severity: review.severity,
+                    }),
+            }));
+        }
+        return Object.freeze(result);
+    }
+    async reviewQueue(token, cursor, limit) {
+        this.require(token, "reviews.read");
+        const rows = await this.queueRows();
+        return paginate({
+            rows,
+            keyOf: (row) => `${row.priority}:${row.raisedAt}`,
+            idOf: (row) => `${row.conversationId}:${row.messageId ?? ""}:${row.feedbackId ?? row.reviewId ?? ""}`,
+            cursor,
+            limit: clampLimit(limit),
+        });
+    }
+    /** Park a conversation for review without rating it. */
+    queueConversation(token, conversationId, messageId) {
+        const { accounts, actor } = this.require(token, "reviews.write");
+        if (accounts.ownerIdOf(conversationId) === undefined) {
+            throw new QaAccountsError("session-owned-elsewhere", "this conversation is unknown to the deployment");
+        }
+        const entry = this.options
+            .quality()
+            .enqueueReview(actor.id, conversationId, messageId);
+        this.options.quality().appendAudit({
+            actorId: actor.id,
+            action: "review.queued",
+            targetType: "conversation",
+            targetId: conversationId,
+            after: { messageId: entry.messageId ?? null },
+        });
+        return {
+            conversationId,
+            ...(entry.messageId === undefined ? {} : { messageId: entry.messageId }),
+            reason: "manual",
+            priority: "normal",
+            status: "unreviewed",
+            raisedAt: entry.createdAt,
+        };
+    }
+    /** Save a reviewer's verdict, and take the item out of the queue when done. */
+    saveReview(token, input) {
+        const { accounts, actor } = this.require(token, "reviews.write");
+        if (accounts.ownerIdOf(input.conversationId) === undefined) {
+            throw new QaAccountsError("session-owned-elsewhere", "this conversation is unknown to the deployment");
+        }
+        const quality = this.options.quality();
+        const { review, created } = quality.saveReview(actor.id, input);
+        quality.appendAudit({
+            actorId: actor.id,
+            action: created ? "conversation.reviewed" : "review.updated",
+            targetType: "conversation",
+            targetId: input.conversationId,
+            after: review,
+        });
+        if (review.status === "needs_followup") {
+            quality.enqueueReview(actor.id, input.conversationId, input.messageId);
+        }
+        else {
+            quality.dequeueReview(input.conversationId, input.messageId);
+        }
+        this.options.logger.info("admin.review-saved", {
+            conversationId: input.conversationId,
+            reviewerId: actor.id,
+            status: review.status,
+            severity: review.severity,
+        });
+        return review;
+    }
+    // -------------------------------------------------------------------------
+    // Audit
+    // -------------------------------------------------------------------------
+    /**
+     * The audit trail as one table. Two writers keep records — the capability
+     * service, whose repository predates the console, and the quality store —
+     * and an administrator expects one timeline, so both are normalized here.
+     */
+    async audit(token, query, cursor, limit) {
+        this.require(token, "audit.read");
+        const actorFilter = given(query.actorId);
+        const actionFilter = given(query.action);
+        const from = epochOf(given(query.from) ?? undefined);
+        const to = epochOf(given(query.to) ?? undefined);
+        const rows = [
+            ...this.accessAuditEvents(),
+            ...this.options.quality().auditEvents(),
+        ]
+            .filter((row) => {
+            if (actorFilter !== undefined && row.actorId !== actorFilter) {
+                return false;
+            }
+            if (actionFilter !== undefined && row.action !== actionFilter) {
+                return false;
+            }
+            const at = epochOf(row.timestamp);
+            if (from !== undefined && (at === undefined || at < from))
+                return false;
+            if (to !== undefined && (at === undefined || at > to))
+                return false;
+            return true;
+        })
+            .sort((left, right) => right.timestamp === left.timestamp
+            ? right.id.localeCompare(left.id)
+            : right.timestamp.localeCompare(left.timestamp));
+        return paginate({
+            rows,
+            keyOf: (row) => row.timestamp,
+            idOf: (row) => row.id,
+            cursor,
+            limit: clampLimit(limit),
+        });
+    }
+    /** Capability-policy events, reshaped into the console's audit vocabulary. */
+    accessAuditEvents() {
+        const actions = {
+            "subrole.created": "subrole.created",
+            "subrole.updated": "subrole.updated",
+            "subrole.deleted": "subrole.deleted",
+            "common.updated": "common_capabilities.updated",
+            "assignment.updated": "subrole.assignment.changed",
+        };
+        const events = [];
+        const source = this.options.roles().audit();
+        source.forEach((event, index) => {
+            const action = actions[event.action];
+            if (action === undefined)
+                return;
+            events.push(Object.freeze({
+                id: `policy:${index}:${event.timestamp}`,
+                timestamp: event.timestamp,
+                actorId: event.actorId,
+                action,
+                targetType: "capability",
+                ...(event.targetId === undefined ? {} : { targetId: event.targetId }),
+                ...(event.before === undefined ? {} : { before: event.before }),
+                ...(event.after === undefined ? {} : { after: event.after }),
+            }));
+        });
+        return events;
+    }
+}
+//# sourceMappingURL=service.js.map