@yadsh/dsh-qa-surface 0.6.1 → 0.7.0

package/lib/types/access/capability-catalog.d.ts

@@ -0,0 +1,37 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { SkillSummary } from "@deepseek-ai/dsh-skill";
+import type { QaCapabilityDescriptor, QaSkillDescriptor } from "../types.js";
+export interface CapabilityCatalogSnapshot {
+    readonly descriptors: readonly QaCapabilityDescriptor[];
+    readonly toolIds: ReadonlySet<string>;
+    /** Installed skills a model-facing catalog may list. */
+    readonly skillIds: ReadonlySet<string>;
+    /** Installed skills a person may invoke, including model-hidden ones. */
+    readonly userSkillIds: ReadonlySet<string>;
+    readonly skills: ReadonlyMap<string, SkillSummary>;
+    /** Normalized `metadata.qa-surface` of every discovered skill. */
+    readonly skillMetadata: ReadonlyMap<string, QaSkillDescriptor>;
+}
+/** Read-only adapter over the current DSH registries. */
+export declare class QaCapabilityCatalog {
+    private readonly ctx;
+    private readonly additionalToolNames;
+    /** Role ids used to report unknown subrole ids in skill metadata. */
+    private readonly knownSubroles;
+    constructor(ctx: Context, additionalToolNames?: () => readonly string[], 
+    /** Role ids used to report unknown subrole ids in skill metadata. */
+    knownSubroles?: () => readonly string[]);
+    snapshot(agent?: Agent): Promise<CapabilityCatalogSnapshot>;
+    /**
+     * Read `metadata.qa-surface` of every discovered skill.
+     *
+     * The registry exposes metadata on loaded definitions only, so discovery has
+     * to fetch each body once. A provider that fails or a skill that disappears
+     * between the two reads degrades to the fail-closed descriptor instead of
+     * failing the whole catalog.
+     */
+    private readSkillMetadata;
+}
+export declare function withMissingCapabilities(descriptors: readonly QaCapabilityDescriptor[], configuredTools: readonly string[], configuredSkills: readonly string[]): readonly QaCapabilityDescriptor[];
+//# sourceMappingURL=capability-catalog.d.ts.map

package/lib/types/access/model.d.ts

@@ -0,0 +1,60 @@
+import type { QaCapabilityConfig, QaCapabilityDescriptor, QaCapabilitySelection, QaEffectiveCapabilityPolicy, QaSkillAccess, QaSkillAssignmentOverride, QaSkillDescriptor, QaSubrole, QaToolSelection, QaUserAccess } from "../types.js";
+/**
+ * Normalize one Tool selection, accepting the pre-split flat list.
+ *
+ * A flat list predates skill grants and can only mean "always visible": the
+ * legacy reading is the narrower one, so an upgraded deployment never hands
+ * out a tool it did not hand out before.
+ * @param value - split selection, legacy string list, or nothing.
+ * @param label - prefix for validation errors.
+ */
+export declare function normalizeToolSelection(value: QaToolSelection | readonly string[] | undefined, label?: string): QaToolSelection;
+export declare function normalizeCapabilitySelection(value: Partial<QaCapabilitySelection> | undefined): QaCapabilitySelection;
+export declare function normalizeSubrole(value: QaSubrole): QaSubrole;
+export declare function normalizeSkillOverrides(value: readonly QaSkillAssignmentOverride[] | undefined): readonly QaSkillAssignmentOverride[];
+export declare function normalizeCapabilityConfig(value: QaCapabilityConfig): QaCapabilityConfig;
+export declare function defaultCapabilityConfig(): QaCapabilityConfig;
+export declare function enabledSubroles(config: QaCapabilityConfig): readonly QaSubrole[];
+export declare function enabledSubroleIds(config: QaCapabilityConfig): readonly string[];
+/** The Common and subrole Tool selections that apply to one subrole. */
+export declare function roleToolSelection(config: QaCapabilityConfig, subroleId: string): QaToolSelection;
+/** The ceiling that bounds what one activated skill may add to the toolset. */
+export declare function roleGrantCeiling(config: QaCapabilityConfig, subroleId: string): readonly string[];
+/** Missing assignments migrate to the first enabled role, never to all roles. */
+export declare function normalizeUserAccess(value: Partial<QaUserAccess> | undefined, config: QaCapabilityConfig): QaUserAccess;
+export interface CapabilityAvailability {
+    readonly tools: ReadonlySet<string>;
+    /** Installed skills a model-facing catalog may list. */
+    readonly skills: ReadonlySet<string>;
+    /** Installed skills a person may invoke; defaults to the model-facing set. */
+    readonly userSkills?: ReadonlySet<string>;
+}
+export interface ResolveCapabilityPolicyInput {
+    readonly config: QaCapabilityConfig;
+    readonly subroleId: string;
+    readonly systemTools: readonly string[];
+    readonly systemSkills: readonly string[];
+    readonly available: CapabilityAvailability;
+    /** Normalized `metadata.qa-surface` of every discovered skill. */
+    readonly skillMetadata?: ReadonlyMap<string, QaSkillDescriptor>;
+    /** Revision recorded with the session snapshot; opaque to enforcement. */
+    readonly revision?: string;
+}
+export declare function resolveCapabilityPolicy({ config, subroleId, systemTools, systemSkills, available: installed, skillMetadata, revision, }: ResolveCapabilityPolicyInput): QaEffectiveCapabilityPolicy;
+export interface ResolveSkillAccessInput {
+    readonly config: QaCapabilityConfig;
+    /** Every discovered skill with its normalized metadata. */
+    readonly descriptors: ReadonlyMap<string, QaSkillDescriptor>;
+    /** Catalog rows for skills, used for description, source and presence. */
+    readonly rows: readonly QaCapabilityDescriptor[];
+    readonly installedTools: ReadonlySet<string>;
+}
+/**
+ * Project every skill for the administration surface.
+ *
+ * The declared audience is reported next to the effective one, so an
+ * administrator can see which roles a skill asked for and which it got.
+ * @param input - configuration, resolved metadata and the installed catalog.
+ */
+export declare function resolveSkillAccess(input: ResolveSkillAccessInput): readonly QaSkillAccess[];
+//# sourceMappingURL=model.d.ts.map

package/lib/types/access/role-repository.d.ts

@@ -0,0 +1,32 @@
+import type { QaAccessAuditEvent, QaCapabilityConfig, QaCapabilitySelection, QaSkillAssignmentOverride, QaSubrole } from "../types.js";
+export declare function defaultCapabilityFilePath(): string;
+/** Atomic, externally reloadable source of truth for roles and their audit. */
+export declare class QaRoleRepository {
+    readonly filePath: string;
+    private file;
+    private fileStamp;
+    constructor(filePath?: string);
+    snapshot(): QaCapabilityConfig;
+    audit(): readonly QaAccessAuditEvent[];
+    create(actorId: string, input: QaSubrole): QaSubrole;
+    update(actorId: string, id: string, input: QaSubrole): QaSubrole;
+    delete(actorId: string, id: string): void;
+    updateCommon(actorId: string, input: QaCapabilitySelection): QaCapabilitySelection;
+    /**
+     * Replace one skill's administrator overlay.
+     *
+     * An overlay with nothing left to declare is removed outright, so clearing a
+     * row in the administration surface leaves the file as if it was never set.
+     * @param actorId - the administrator performing the change.
+     * @param input - the overlay as edited in the browser.
+     * @returns every overlay in force after the change.
+     */
+    updateSkillOverride(actorId: string, input: QaSkillAssignmentOverride): readonly QaSkillAssignmentOverride[];
+    recordAssignment(actorId: string, targetId: string, before: unknown, after: unknown): void;
+    private replace;
+    private appendAudit;
+    private reload;
+    private load;
+    private persist;
+}
+//# sourceMappingURL=role-repository.d.ts.map

package/lib/types/access/service.d.ts

@@ -0,0 +1,57 @@
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaAccounts } from "../accounts/store.js";
+import type { QaAgentToolGrants } from "../enforcement/tool-grants.js";
+import type { QaAccessAdminSnapshot, QaCapabilityConfig, QaCapabilityDescriptor, QaCapabilitySelection, QaCurrentAccess, QaEffectiveCapabilityPolicy, QaSessionAccess, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, ResolvedQaSurfaceConfig } from "../types.js";
+import { QaCapabilityCatalog, type CapabilityCatalogSnapshot } from "./capability-catalog.js";
+import { QaRoleRepository } from "./role-repository.js";
+export interface QaResolvedSessionPolicy {
+    readonly policy: QaEffectiveCapabilityPolicy;
+    readonly skills: CapabilityCatalogSnapshot["skills"];
+    readonly skillMetadata: CapabilityCatalogSnapshot["skillMetadata"];
+    /** Preview sessions label their own activation records. */
+    readonly adminPreview: boolean;
+    /**
+     * Build the live tool policy of one agent. The admission calls this only
+     * when it installs a policy, so a repeated attestation never stacks a second
+     * scoped restriction.
+     */
+    readonly createGrants: () => QaAgentToolGrants;
+}
+/** Server-only orchestration of roles, assignments, discovery and snapshots. */
+export declare class QaAccessService {
+    private readonly options;
+    readonly roles: QaRoleRepository;
+    readonly catalog: QaCapabilityCatalog;
+    constructor(ctx: Context, options: {
+        readonly accounts: () => QaAccounts | undefined;
+        readonly config: () => ResolvedQaSurfaceConfig;
+        readonly logger: PluginLogger;
+        readonly repository?: QaRoleRepository;
+        readonly dynamicToolNames?: () => readonly string[];
+    });
+    current(token: string): QaCurrentAccess;
+    session(token: string, sessionId: string): QaSessionAccess;
+    reserveSession(token: string, sessionId: string, requestedSubrole: string | null, adminPreview: boolean): import("../types.js").QaAccountUserPublic;
+    policyForSession(token: string, sessionId: string, agent: Agent): Promise<QaResolvedSessionPolicy | undefined>;
+    /** Activation history of one session, for review and quality analysis. */
+    skillActivations(token: string, sessionId: string): readonly QaSkillActivationRecord[];
+    /** Append one activation attempt; a lost record never fails the session. */
+    private recordSkillActivation;
+    adminSnapshot(token: string): Promise<QaAccessAdminSnapshot>;
+    /** Replace or clear one skill's administrator overlay. */
+    updateSkillOverride(token: string, input: QaSkillAssignmentOverride): readonly QaSkillAssignmentOverride[];
+    createSubrole(token: string, input: QaSubrole): QaSubrole;
+    updateSubrole(token: string, id: string, input: QaSubrole): QaSubrole;
+    deleteSubrole(token: string, id: string, replacementId: string | null): void;
+    updateCommon(token: string, input: QaCapabilitySelection): QaCapabilitySelection;
+    updateAssignment(token: string, userId: string, input: QaUserAccess): QaUserAccess;
+    private requireAccounts;
+    /** The activation diagnostic is runtime plumbing, not an administrator grant. */
+    private systemRequiredTools;
+    private requireAdmin;
+}
+export declare function validateCapabilityConfig(config: QaCapabilityConfig): QaCapabilityConfig;
+export type { QaCapabilityDescriptor };
+//# sourceMappingURL=service.d.ts.map

package/lib/types/access/skill-metadata.d.ts

@@ -0,0 +1,53 @@
+import type { QaSkillAssignmentOverride, QaSkillDescriptor, QaSkillHealth } from "../types.js";
+/** The fail-closed descriptor of a skill that declares nothing. */
+export declare function unassignedSkill(name: string): QaSkillDescriptor;
+/**
+ * Read and normalize one skill's `metadata.qa-surface` block.
+ *
+ * The block is advisory input, never an authority: it decides who may see the
+ * skill and which tools the skill needs, while the role ceiling still decides
+ * whether a tool can ever be granted. Malformed input degrades to the
+ * fail-closed default and is reported instead of throwing, because one broken
+ * skill must not take down discovery for the whole deployment.
+ * @param name - the skill name the registry resolved, not the metadata's.
+ * @param metadata - the raw frontmatter `metadata` object, if any.
+ * @param knownSubroles - role ids that currently exist, for typo reporting.
+ * @returns the normalized descriptor with every complaint in `warnings`.
+ */
+export declare function parseQaSkillMetadata(name: string, metadata: Readonly<Record<string, unknown>> | undefined, knownSubroles: ReadonlySet<string>): QaSkillDescriptor;
+/** Validate one administrator overlay row before it reaches the policy file. */
+export declare function normalizeSkillOverride(value: QaSkillAssignmentOverride): QaSkillAssignmentOverride;
+/** One skill's effective audience after the administrator overlay. */
+export interface QaSkillVisibility {
+    readonly declaredTo: readonly string[];
+    readonly visibleTo: readonly string[];
+    readonly addedByAdmin: readonly string[];
+    readonly removedByAdmin: readonly string[];
+    readonly disabled: boolean;
+    /** Whether the overlay actually changed the declared outcome. */
+    readonly overridden: boolean;
+}
+/**
+ * Merge one skill's declared audience with its administrator overlay.
+ *
+ * The declared list is only a default: an administrator may extend it, force
+ * the skill on for every role, or withdraw it. A withdrawal always wins over
+ * an addition, so a contradictory pair of edits can only narrow access.
+ * @param descriptor - normalized metadata of the skill.
+ * @param override - administrator overlay, when one exists.
+ * @param enabledRoles - ids of subroles that are currently enabled.
+ */
+export declare function resolveSkillVisibility(descriptor: QaSkillDescriptor, override: QaSkillAssignmentOverride | undefined, enabledRoles: readonly string[]): QaSkillVisibility;
+/**
+ * Computed health of one skill for the administration table.
+ *
+ * `blocked` and `degraded` differ only in what `requireAll` promises: a strict
+ * skill refuses to activate at all, a best-effort one activates with a warning.
+ * @param descriptor - normalized metadata carrying the requirement list.
+ * @param available - required tools that are installed and grantable for at
+ *   least one role that can see the skill.
+ * @param missing - required tools no visible role could ever grant.
+ * @param visibleTo - roles that currently see the skill.
+ */
+export declare function skillHealth(descriptor: QaSkillDescriptor, available: number, missing: number, visibleTo: readonly string[]): QaSkillHealth;
+//# sourceMappingURL=skill-metadata.d.ts.map

package/lib/types/account-remotes.d.ts

@@ -13,6 +13,12 @@ export interface QaAccountRemotes {
     resolve(config: ResolvedQaSurfaceConfig): QaAccounts | undefined;
     /** Map a store failure onto the shared `(reason: <code>)` wire marker. */
     run<T>(operation: () => T, sessionIdForLog?: string): T;
+    /**
+     * The same mapping for an asynchronous body. A refusal thrown after an
+     * `await` never reaches a synchronous `run`, and the administrative reads
+     * await stored logs before they can decide anything.
+     */
+    runAsync<T>(operation: () => Promise<T>, sessionIdForLog?: string): Promise<T>;
     register(email: string, password: string): QaAccountSession;
     login(email: string, password: string): QaAccountSession;
     /** Identity probe; safe to call with an empty or expired token. */

package/lib/types/accounts/errors.d.ts

@@ -3,7 +3,7 @@
  * marker pattern the attestation path established; the browser maps them to
  * audience-safe copy and the precise cause stays in the Host logs.
  */
-export type QaAccountsErrorReason = "auth-required" | "admin-required" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-profile" | "profile-disabled" | "invalid-starters" | "starters-disabled" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere";
+export type QaAccountsErrorReason = "auth-required" | "admin-required" | "forbidden" | "invalid-credentials" | "account-disabled" | "email-taken" | "invalid-email" | "invalid-display-name" | "invalid-profile" | "profile-disabled" | "invalid-starters" | "starters-disabled" | "invalid-role" | "weak-password" | "registration-disabled" | "rate-limited" | "session-owned-elsewhere";
 export declare class QaAccountsError extends Error {
     readonly reason: QaAccountsErrorReason;
     constructor(reason: QaAccountsErrorReason, message: string);

package/lib/types/accounts/file.d.ts

@@ -1,5 +1,5 @@
 import type { Stats } from "node:fs";
-import type { QaAccountRole } from "../types.js";
+import type { QaAccountRole, QaEffectiveCapabilityPolicy, QaSkillActivationRecord, QaUserAccess } from "../types.js";
 /** One account's self-declared profile as it rests in the accounts file. */
 export interface StoredProfile {
     fullName?: string;
@@ -38,16 +38,27 @@ export interface StoredUser {
     profile?: StoredProfile;
     /** Absent until the owner customizes the starter buttons. */
     starters?: StoredStarters;
+    /** Agent capability profiles assigned by an administrator. */
+    qaAccess?: QaUserAccess;
+}
+export interface StoredOwnership {
+    readonly userId: string;
+    readonly claimedAt: string;
+    /** Pinned at creation; absent only on sessions predating subroles. */
+    readonly subroleId?: string;
+    /** Admin preview is an explicit session fact, never inferred from role=admin. */
+    readonly adminPreview?: boolean;
+    /** First successful admission freezes the actually installed capabilities. */
+    readonly capabilitySnapshot?: QaEffectiveCapabilityPolicy;
+    /** Skill activations in order: what the model gained, and when it gained it. */
+    readonly skillActivations?: readonly QaSkillActivationRecord[];
 }
 export interface AccountsFile {
     readonly version: 1;
     /** HMAC key for account tokens; rotated on password change by rewriting it. */
     readonly secret: string;
     readonly users: StoredUser[];
-    readonly ownership: Record<string, {
-        readonly userId: string;
-        readonly claimedAt: string;
-    }>;
+    readonly ownership: Record<string, StoredOwnership>;
 }
 /** mtime+size pair identifying one on-disk version of the accounts file. */
 export interface FileStamp {

package/lib/types/accounts/store.d.ts

@@ -1,5 +1,5 @@
-import type { QaAccountIdentityField, QaAccountProfile, QaAccountProfileInput, QaAccountRole, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaClaimResult, QaOwnershipEntry, QaWhoamiResult } from "../types.js";
-import type { StoredUser } from "./file.js";
+import type { QaAccountIdentityField, QaAccountProfile, QaAccountProfileInput, QaAccountRole, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaAccessUser, QaAdminAccountRow, QaClaimResult, QaEffectiveCapabilityPolicy, QaOwnershipEntry, QaSkillActivationRecord, QaUserAccess, QaWhoamiResult } from "../types.js";
+import type { StoredOwnership, StoredUser } from "./file.js";
 export { QaAccountsError } from "./errors.js";
 export type { QaAccountsErrorReason } from "./errors.js";
 export { defaultAccountsFilePath } from "./file.js";
@@ -58,6 +58,8 @@ export declare class QaAccounts {
     private mintToken;
     /** The account behind a token, or an auth-required refusal. */
     requireUser(token: string): StoredUser;
+    /** Public identity behind a token; used by server-side access services. */
+    currentUser(token: string): QaAccountUserPublic;
     /**
      * Ownership gate for one session: claim unowned sessions for the requesting
      * user (first come, first served — the pre-accounts migration path), refuse
@@ -69,7 +71,10 @@ export declare class QaAccounts {
      * the Session exists. Browser callers therefore never get a race window in
      * which they can claim another user's newly created chat.
      */
-    reserveSession(token: string, sessionId: string): QaAccountUserPublic;
+    reserveSession(token: string, sessionId: string, access?: {
+        readonly subroleId: string;
+        readonly adminPreview?: boolean;
+    }): QaAccountUserPublic;
     /** Roll back a reservation if Host creation failed before a chat existed. */
     releaseSessionReservation(userId: string, sessionId: string): void;
     /** Bulk-claim a browser's local chat index; foreign ids come back as conflicts. */
@@ -91,12 +96,87 @@ export declare class QaAccounts {
         readonly createdAt: string;
         readonly lastLoginAt: string | null;
     }[];
+    /** Browser-safe administration rows with capability assignments. */
+    listAccessUsers(resolve: (stored: QaUserAccess | undefined) => QaUserAccess): readonly QaAccessUser[];
+    /**
+     * Every account with the administrative columns the admin console renders:
+     * identity, status, authorization role, assignment and the timestamps of the
+     * account's own life. Credentials and token material are never projected.
+     */
+    listAdminUsers(resolve: (stored: QaUserAccess | undefined) => QaUserAccess): readonly QaAdminAccountRow[];
+    /**
+     * Identity columns of every account, without their capability assignment.
+     * The console's name lookup: an audit row or a queue entry names an account
+     * by id, and the table needs a label for it.
+     */
+    directory(): readonly {
+        readonly id: string;
+        readonly email: string;
+        readonly displayName: string;
+        readonly role: QaAccountRole;
+        readonly disabled: boolean;
+    }[];
+    /** One account's administrative row, or undefined for an unknown id. */
+    adminUser(userId: string, resolve: (stored: QaUserAccess | undefined) => QaUserAccess): QaAdminAccountRow | undefined;
+    /**
+     * Every session reservation with its pinned role and capability snapshot.
+     * This is the deployment's own conversation index: a QA chat exists here
+     * from the moment its id is reserved, before any message is written.
+     */
+    listOwnershipRecords(): readonly {
+        readonly sessionId: string;
+        readonly userId: string;
+        readonly claimedAt: string;
+        readonly subroleId?: string;
+        readonly adminPreview?: boolean;
+        readonly capabilitySnapshot?: QaEffectiveCapabilityPolicy;
+    }[];
+    /** Replace one account's authorization role, addressed by stable id. */
+    setAccessRole(userId: string, role: QaAccountRole): QaAccountUserPublic;
+    /**
+     * Disable or enable one account by id. Same semantics as the operator
+     * {@link setUserDisabled}: disabling also invalidates every live token, and
+     * enabling does not bring the old ones back.
+     */
+    setAccessDisabled(userId: string, disabled: boolean): QaAccountUserPublic;
+    /** Stored assignment for one account; callers normalize missing legacy rows. */
+    accessOf(userId: string): QaUserAccess | undefined;
+    /** Admin-owned assignment write addressed by stable account id. */
+    setAccess(userId: string, access: QaUserAccess): QaUserAccess;
+    /** Persisted role and immutable policy record for one Host session. */
+    sessionAccess(sessionId: string): StoredOwnership | undefined;
+    /** Migrate a pre-subrole session or finalize its first policy snapshot. */
+    updateSessionAccess(sessionId: string, update: {
+        readonly subroleId?: string;
+        readonly adminPreview?: boolean;
+        readonly capabilitySnapshot?: QaEffectiveCapabilityPolicy;
+    }): StoredOwnership;
+    /**
+     * Append one skill activation attempt to a session's history.
+     *
+     * The record is the reviewable half of a dynamic tool grant: it names what
+     * the skill asked for, what it received and what it was refused. The list is
+     * bounded, because a long session may activate skills many times and the
+     * oldest entries stop being interesting long before the file does.
+     * @param sessionId - the session the activation belongs to.
+     * @param entry - the attempt to append.
+     * @param limit - how many entries to keep, newest last.
+     * @returns the stored history after the append.
+     */
+    recordSkillActivation(sessionId: string, entry: QaSkillActivationRecord, limit: number): readonly QaSkillActivationRecord[];
     /** Create an account outside the self-registration gate. */
     addUser(email: string, password: string, options?: {
         displayName?: string;
         role?: QaAccountRole;
     }): QaAccountUserPublic;
     private editUser;
+    /**
+     * Same read-modify-write as {@link editUser}, addressed by account id. The
+     * administrative console works in ids: an email is a credential-shaped
+     * handle the operator may change, while the id is what conversations,
+     * feedback and audit rows already reference.
+     */
+    private editUserById;
     /** Grant or revoke the admin role. */
     setUserRole(email: string, role: QaAccountRole): QaAccountUserPublic;
     /**

package/lib/types/admin/conversation-log.d.ts

@@ -0,0 +1,39 @@
+import type { QaConversationMessage } from "../types.js";
+import type { QaAdminRedactor } from "./redaction.js";
+/**
+ * Projection of a stored session log into the reviewer's transcript.
+ *
+ * The admin viewer reads the event log rather than the live agent state: a
+ * conversation is reviewed weeks after it happened, usually on a process that
+ * has never had it open. The projection therefore walks the raw event order and
+ * shows what the log recorded — it does not re-derive model history, so a
+ * compaction or a surface replacement never hides evidence from a reviewer.
+ *
+ * Messages are identified by their event `seq`, the one identity both the
+ * durable log and the browser transcript agree on. A rating recorded against
+ * `seq` keeps pointing at the same assistant message after the log is replayed.
+ */
+/** The events read back from durable storage; only these fields are used. */
+export interface StoredSessionEvent {
+    readonly seq: number;
+    readonly time?: number;
+    readonly type: string;
+    readonly data?: unknown;
+}
+export interface QaProjectedTranscript {
+    readonly title?: string;
+    readonly messages: readonly QaConversationMessage[];
+    readonly model?: string;
+    readonly provider?: string;
+    /** Skills the model loaded, in first-use order, from its skill tool calls. */
+    readonly loadedSkills: readonly string[];
+    /** Newest event time in the log, when the log carried one. */
+    readonly lastActivity?: number;
+}
+/**
+ * Project one log into the review transcript. Unknown event types are skipped,
+ * not refused: a deployment may carry plugin events this package has never
+ * heard of, and a review console must still show the conversation.
+ */
+export declare function projectTranscript(events: readonly StoredSessionEvent[], redactor: QaAdminRedactor): QaProjectedTranscript;
+//# sourceMappingURL=conversation-log.d.ts.map

package/lib/types/admin/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The administrative console's server side: authorization, conversation
+ * queries over stored session logs, the quality records (feedback, reviews,
+ * the derived queue, the audit trail) and their aggregations.
+ */
+export { QaAdminService } from "./service.js";
+export type { QaAdminServiceOptions } from "./service.js";
+export { QA_ADMIN_PAGE_DEFAULT, QA_ADMIN_PAGE_MAX, QA_ADMIN_SCAN_LIMIT, } from "./service.js";
+export { allows, permissionsOf, readsEveryConversation, } from "./permissions.js";
+export { QaQualityStore, defaultQualityFilePath } from "./quality-store.js";
+export type { QaManualQueueEntry } from "./quality-store.js";
+export { QA_FEEDBACK_REASONS, QA_FEEDBACK_RATINGS, QA_QUALITY_ISSUES, QA_QUALITY_SEVERITIES, QA_REMEDIATION_TARGETS, } from "./quality-store.js";
+export { aggregateQuality } from "./metrics.js";
+export type { QaConversationFact } from "./metrics.js";
+export { deriveQueue } from "./queue.js";
+export type { QaQueueInput, QaToolFailureSignal } from "./queue.js";
+export { paginate } from "./paging.js";
+export { projectTranscript } from "./conversation-log.js";
+export type { QaProjectedTranscript, StoredSessionEvent, } from "./conversation-log.js";
+export { createSessionLogReader, staticSessionLogReader, } from "./session-log.js";
+export type { QaSessionLogReader, QaSessionReadResult, QaStoredSessionHeader, } from "./session-log.js";
+export { defaultAdminRedactor, maskSecrets } from "./redaction.js";
+export type { QaAdminRedactor } from "./redaction.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/types/admin/metrics.d.ts

@@ -0,0 +1,29 @@
+import type { QaConversationReview, QaFeedbackRating, QaMessageFeedback, QaQualityMetrics } from "../types.js";
+/**
+ * Quality aggregation.
+ *
+ * The numbers here are named for what they are. A thumbs-up is a user
+ * satisfaction signal, not an accuracy measurement: this module never reports
+ * a rate that reads as ground truth, and the API surfaces carry the same
+ * wording (spec §26).
+ */
+/** What one conversation contributes, however cheaply it was obtained. */
+export interface QaConversationFact {
+    readonly conversationId: string;
+    readonly userId: string;
+    readonly subroleId: string;
+    readonly assistantMessages: number;
+    /** Epoch ms of the conversation's creation, for the activity window. */
+    readonly createdAt: number;
+}
+export interface QaAggregationInput {
+    readonly conversations: readonly QaConversationFact[];
+    readonly feedback: readonly QaMessageFeedback[];
+    readonly reviews: readonly QaConversationReview[];
+    /** Days of feedback history the trend shows; older buckets are dropped. */
+    readonly trendDays?: number;
+}
+export declare function aggregateQuality({ conversations, feedback, reviews, trendDays, }: QaAggregationInput): QaQualityMetrics;
+/** One rating's contribution to a conversation row, without re-reading logs. */
+export declare function countRatings(feedback: readonly QaMessageFeedback[]): Readonly<Record<QaFeedbackRating, number>>;
+//# sourceMappingURL=metrics.d.ts.map

package/lib/types/admin/paging.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cursor paging shared by every administrative list. Admin tables read from
+ * append-only files whose newest entries arrive last, so a list is always
+ * materialized newest-first and a cursor names the last row the caller saw.
+ *
+ * The cursor is the row's sort key plus its identity, never an offset: rows
+ * keep arriving while a reviewer pages, and an offset would then skip or
+ * repeat entries.
+ */
+export interface QaPage<T> {
+    readonly items: readonly T[];
+    readonly nextCursor: string | null;
+    readonly total: number;
+}
+export interface QaPageRequest<T> {
+    /** Rows in their final order, newest first. */
+    readonly rows: readonly T[];
+    /** The composite sort key of one row; must be unique together with the id. */
+    readonly keyOf: (row: T) => string;
+    /** The row's stable identity. */
+    readonly idOf: (row: T) => string;
+    /** Cursor returned by the previous page; absent for the first page. */
+    readonly cursor?: string | undefined;
+    /** Requested page size, clamped by the caller's own bounds. */
+    readonly limit: number;
+}
+/**
+ * Slice one page out of an already-sorted list. An unknown cursor is treated as
+ * the start of the list: it can only mean the row was trimmed away since the
+ * caller last paged, in which case restarting is the honest answer.
+ */
+export declare function paginate<T>({ rows, keyOf, idOf, cursor, limit, }: QaPageRequest<T>): QaPage<T>;
+//# sourceMappingURL=paging.d.ts.map

package/lib/types/admin/permissions.d.ts

@@ -0,0 +1,10 @@
+import type { QaAccountRole, QaPermission } from "../types.js";
+/** Every permission this package knows; the Remote surface validates against it. */
+export declare const QA_PERMISSIONS: readonly QaPermission[];
+/** The permissions one authorization role grants, deduplicated. */
+export declare function permissionsOf(role: QaAccountRole): readonly QaPermission[];
+/** Whether one role grants one permission. */
+export declare function allows(role: QaAccountRole, permission: QaPermission): boolean;
+/** Whether this role may read conversations it does not own. */
+export declare function readsEveryConversation(role: QaAccountRole): boolean;
+//# sourceMappingURL=permissions.d.ts.map

package/lib/types/admin/quality-store.d.ts

@@ -0,0 +1,82 @@
+import type { QaAdminAuditAction, QaAdminAuditEvent, QaConversationReview, QaConversationReviewInput, QaFeedbackReason, QaFeedbackRating, QaMessageFeedback, QaMessageFeedbackInput, QaQualityIssueType, QaQualitySeverity, QaRemediationTarget } from "../types.js";
+/**
+ * The durable quality file: user feedback, reviewer results, the manual review
+ * queue and the administrative audit trail.
+ *
+ * It is deliberately separate from the capability policy file: role
+ * configuration is a deployment artifact an operator may replace wholesale,
+ * while feedback and reviews are user data that must survive such a reset.
+ */
+export declare const QA_FEEDBACK_RATINGS: readonly QaFeedbackRating[];
+export declare const QA_FEEDBACK_REASONS: readonly QaFeedbackReason[];
+export declare const QA_QUALITY_ISSUES: readonly QaQualityIssueType[];
+export declare const QA_QUALITY_SEVERITIES: readonly QaQualitySeverity[];
+export declare const QA_REMEDIATION_TARGETS: readonly QaRemediationTarget[];
+export interface QaManualQueueEntry {
+    readonly conversationId: string;
+    readonly messageId?: string;
+    /** The reviewer who parked it; a queue entry is a deliberate act. */
+    readonly userId: string;
+    readonly createdAt: string;
+}
+export declare function defaultQualityFilePath(): string;
+/**
+ * Atomic, externally reloadable store for the quality layer. Writes are
+ * synchronous and persisted with a temp file plus rename, matching the accounts
+ * and capability files: LAN scale keeps this trivial, and a reload probe keeps
+ * a second process's write visible.
+ *
+ * Rows are re-validated on read rather than trusted: a hand-edited file cannot
+ * inject a record the writers would have refused. A malformed row is reported
+ * instead of dropped — writes are atomic, so it can only mean someone edited
+ * the file, and silently discarding a user's record would hide that.
+ */
+export declare class QaQualityStore {
+    readonly filePath: string;
+    private file;
+    private fileStamp;
+    constructor(filePath?: string);
+    /**
+     * Record or replace one user's rating of one message. Re-rating the same
+     * message overwrites in place rather than appending: a reviewer reads the
+     * user's current verdict, and the first-seen time stays with it.
+     */
+    rateFeedback(input: {
+        readonly conversationId: string;
+        readonly messageId: string;
+        readonly userId: string;
+    }, feedback: QaMessageFeedbackInput): QaMessageFeedback;
+    allFeedback(): readonly QaMessageFeedback[];
+    /** Ratings of one conversation, newest first. */
+    feedbackOfConversation(conversationId: string): readonly QaMessageFeedback[];
+    /** One exact rating, for the viewer's per-message thumbs state. */
+    feedbackOf(conversationId: string, messageId: string, userId: string): QaMessageFeedback | undefined;
+    /** Save a reviewer's result, replacing that reviewer's earlier verdict. */
+    saveReview(reviewerId: string, input: QaConversationReviewInput): {
+        readonly review: QaConversationReview;
+        readonly created: boolean;
+    };
+    allReviews(): readonly QaConversationReview[];
+    reviewsOfConversation(conversationId: string): readonly QaConversationReview[];
+    /** Park one conversation for review; re-parking the same target is a no-op. */
+    enqueueReview(userId: string, conversationId: string, messageId?: string): QaManualQueueEntry;
+    /** Drop a manual queue entry once a reviewer has answered it. */
+    dequeueReview(conversationId: string, messageId?: string): boolean;
+    manualQueue(): readonly QaManualQueueEntry[];
+    /** Append one administrative action to the audit trail. */
+    appendAudit(input: {
+        readonly actorId: string;
+        readonly action: QaAdminAuditAction;
+        readonly targetType?: string | undefined;
+        readonly targetId?: string | undefined;
+        readonly before?: unknown;
+        readonly after?: unknown;
+    }): QaAdminAuditEvent;
+    auditEvents(): readonly QaAdminAuditEvent[];
+    /** Serialize one before/after value, refusing what no reader could use. */
+    private snapshot;
+    private reload;
+    private load;
+    private persist;
+}
+//# sourceMappingURL=quality-store.d.ts.map