@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.1

package/lib/types/client/openInSidebar.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Open a knowledge document in the product's own right-hand file window.
+ *
+ * The knowledge page does not draw a document preview of its own. Opening a document
+ * hands it to the host's sidebar, which is the surface every other file in the
+ * workspace opens into: tab strip, path input, preview/edit toggle, save, refresh,
+ * outline. The knowledge page owns none of that chrome.
+ *
+ * Two host services are involved, both published before any panel mounts:
+ *
+ * - `sidebarRight` (`ui-sidebar-right`) owns the column. Its `openResource` claims the
+ *   address, places it, and **reveals the column in the same step** -- the column
+ *   expands as part of opening, so a document handed to it cannot land in a collapsed
+ *   panel the reader never sees.
+ * - `sidebarRightTabs` is the tab-type registry, whose ranking decides which kind
+ *   claims a file address. Asking it keeps this open on the host's normal path instead
+ *   of hard-coding a kind.
+ *
+ * The address is built with the official `fileAddressFor`, so a document opened from
+ * here dedupes against the tab the chat file-link path already opened for the same
+ * file rather than opening a second tab onto it.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Outcome of asking the host to show a document. */
+export type OpenOutcome = 'opened' | 'no-context' | 'no-registry' | 'unclaimed' | 'no-column';
+/**
+ * Ask the host to open a document in its right-hand file window.
+ *
+ * @param ctx - the client context the page was injected with.
+ * @param sessionId - the conversation the sidebar column is scoped to.
+ * @param cwd - the session's workspace root, used to shorten the address to a
+ *   session-relative one so it dedupes against chat-opened tabs.
+ * @param absolutePath - the document's absolute path inside the workspace.
+ * @returns Why it did or did not open; the caller reports the failure rather than
+ *   appearing to do nothing.
+ */
+export declare function openInSidebar(ctx: unknown, sessionId: string | undefined, cwd: string | undefined, absolutePath: string): OpenOutcome;
+/**
+ * Return the right column's width to the page.
+ *
+ * Called when the knowledge page stops showing a document. It is deliberately separate
+ * from {@link openInSidebar} rather than a mode flag: the two states need different
+ * frames, and closing the track is what restores the page's own width. A host without
+ * the layout service is left alone -- the page simply keeps whatever it had.
+ * @param ctx - the client context the page runs in.
+ */
+/**
+ * Report whether the host's right column is currently expanded.
+ *
+ * The page uses this to decide whether it may keep its own content column: a document
+ * opened in the reader means the page's column is redundant, but only while the reader
+ * is actually on screen. Reading it live (instead of tracking it in React state) keeps
+ * the page and the frame from disagreeing when the reader closes the column themselves.
+ * A host without the column service reports `false`, which keeps the page's own layout.
+ * @param ctx - the client context the page runs in.
+ * @returns whether the column is expanded right now.
+ */
+export declare function readColumnExpanded(ctx: unknown): boolean;
+export declare function closeSidebar(ctx: unknown): void;
+/** Whether a failure means the host's right column is simply not on this profile. */
+export declare function isHostMissing(outcome: OpenOutcome): boolean;

package/lib/types/client/ownerLabel.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Who a knowledge document belongs to, derived from where it is stored.
+ *
+ * The list route reports a path and a location, not an owner: ownership is a property of
+ * the bucket, and every rule below is a rule about that bucket. Keeping the derivation
+ * here (rather than in the row renderer) does two things. It stays testable without a
+ * DOM, and it keeps the answer honest — nothing is invented when the information is not
+ * there, because a wrong owner is worse than an unflattering one.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/ownerLabel
+ */
+/** What the caller knows about itself, as far as ownership is concerned. */
+export interface OwnerContext {
+    /** The caller's DataOps id, so `personal/<id>` can be recognised as one's own folder. */
+    callerId?: string;
+    /** The caller's own department code, for naming the department bucket. */
+    departmentCode?: string;
+    /** The caller's own department name; falls back to the code when absent. */
+    departmentName?: string;
+}
+/** One resolved owner cell. */
+export interface OwnerLabel {
+    /** Which rule produced the label, so the renderer can style it without re-parsing. */
+    kind: 'global' | 'department' | 'self' | 'person' | 'unknown';
+    /** The text to show. */
+    label: string;
+}
+/**
+ * Resolve the owner of one document.
+ *
+ * `labels` carries the three strings this module cannot know: what to call the shared
+ * bucket, what to call the caller's own folder, and what to show when a path is outside
+ * every bucket. Passing them in keeps the module free of locale plumbing.
+ */
+export declare function ownerLabelOf(relPath: string, context: OwnerContext, labels: {
+    global: string;
+    self: string;
+    unknown: string;
+}): OwnerLabel;

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

@@ -0,0 +1,69 @@
+/**
+ * Page slicing for every table in the knowledge surface.
+ *
+ * A pure module rather than a hook: the rule worth testing is arithmetic, and a hook
+ * would need a renderer to exercise. The component owns the page and size as state;
+ * this answers what that state should display.
+ *
+ * The one rule that matters is the clamp. A reader can be on page 7 of a table when a
+ * filter, a search word or a re-read shrinks it to two pages, and obeying "page 7"
+ * literally renders an empty table with a pager that still says there is data. So the
+ * requested page is clamped into range and the clamped value is returned, which is what
+ * the owner writes back into its own state.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/paging
+ */
+/** Page sizes every table offers, in the order the control shows them. */
+export declare const PAGE_SIZES: readonly [20, 50, 100];
+/** The page size a fresh table starts on. */
+export declare const DEFAULT_PAGE_SIZE = 20;
+/** One page of rows plus the numbers a pager draws. */
+export interface Page<T> {
+    /** The rows on this page, in order. */
+    rows: T[];
+    /** 1-based page actually shown, clamped into range. */
+    page: number;
+    /** Total number of pages; never zero, so no pager can say "page 1 of 0". */
+    pageCount: number;
+    /** Total row count across all pages. */
+    total: number;
+}
+/**
+ * Whether a table of this size needs a pager at all.
+ *
+ * A single page has nothing to page through, so the control row is not drawn: an
+ * always-visible pager on a three-row table is furniture that implies the reader is
+ * missing something. Empty is the same answer for the same reason.
+ * @param total - row count before slicing.
+ * @param pageSize - rows per page.
+ * @returns true when there is more than one page.
+ */
+export declare function needsPager(total: number, pageSize: number): boolean;
+/**
+ * Slice one page out of a list that is already in display order.
+ *
+ * Ordering is the caller's job and happens BEFORE this call: pagination must never
+ * reorder, or turning a page would appear to sort the table differently. The same
+ * applies to filtering -- a filtered list is what gets paged, so the count in the pager
+ * is the count of matches rather than of the whole table.
+ *
+ * @param rows - rows already filtered and ordered.
+ * @param page - 1-based page requested; clamped into range.
+ * @param pageSize - rows per page; a non-positive or non-integer value falls back.
+ * @returns The page and the numbers to draw.
+ */
+export declare function paginate<T>(rows: readonly T[], page: number, pageSize: number): Page<T>;
+/**
+ * The 1-based page a size change should land on.
+ *
+ * Keeping the first visible row in view is the point: a reader who switches from 20 to
+ * 100 rows is looking at row 41, so the page they want is the one containing it, not
+ * page 1 and not page 3 of the old numbering. Clamping in {@link paginate} then keeps
+ * that answer in range if the list is shorter than expected.
+ *
+ * @param currentPage - page shown before the change.
+ * @param previousSize - size in force before the change.
+ * @param nextSize - size being chosen.
+ * @returns The 1-based page to request.
+ */
+export declare function pageAfterSizeChange(currentPage: number, previousSize: number, nextSize: number): number;

package/lib/types/client/permissionRows.d.ts

@@ -0,0 +1,265 @@
+/**
+ * The pure half of the permissions overview: how one grant table reads two ways.
+ *
+ * Kept apart from the rendering module for a real reason, not for tidiness: a
+ * component module imports the primitives package, which imports CSS, and a Node
+ * test runner cannot load a `.css` file. The grouping rules are the part worth
+ * testing without a DOM, so they live somewhere a plain import can reach.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/permissionRows
+ */
+import type { GrantView, KnowledgeGrantSubjectType } from '../api.ts';
+/** One person's holdings, as the person view renders them. */
+export interface PersonHoldings {
+    /** Principal id the grants name. */
+    principalId: string;
+    /** Principal kind, so the type column can name it. */
+    principalType: KnowledgeGrantSubjectType;
+    /** Display name when a directory entry resolved one, else the id. */
+    label: string;
+    /** Distinct paths this person may touch. */
+    paths: string[];
+    /** Which actions the person holds, collapsed so a full house reads `all`. */
+    actions: string[];
+    /**
+     * Roles the person reaches through a `role` grant they belong to.
+     *
+     * Empty when the directory does not know the membership: a role grant names the
+     * ROLE, not the people in it, so this is only populated when a directory entry
+     * declared the membership.
+     */
+    roles: string[];
+    /** Most recent grant instant across this person's rows, ISO-8601. */
+    latestAt: string;
+    /** The grants this row covers, so a revoke can name exactly what it removes. */
+    grants: GrantView[];
+}
+/** One resource and everyone who may reach it. */
+export interface ResourceHoldings {
+    /** Path, relative to the mount point. */
+    relPath: string;
+    /** Whether it is a file or a directory. */
+    kind: 'file' | 'directory';
+    /** Everyone holding any action on it, grouped by principal kind. */
+    principals: Array<{
+        principalType: KnowledgeGrantSubjectType;
+        principalId: string;
+        label: string;
+        actions: string[];
+        latestAt: string;
+        grants: GrantView[];
+    }>;
+}
+/**
+ * The result of reading a set of grants as permissions.
+ *
+ * `known: false` carries a reason rather than an empty list, because "we could not
+ * work this out" and "this principal holds nothing" must not render the same way: the
+ * first is a fault the reader should see, and collapsing it into an empty set is how a
+ * denial gets invented. See {@link resolveActions}.
+ */
+export interface ResolvedActions {
+    /** Actions held, in display order. Empty when `known` is false. */
+    actions: string[];
+    /**
+     * Whether the full set could be determined.
+     *
+     * False when part of the input could not be read -- an inheritance path that was
+     * unavailable, or a grant whose action is a word this build does not know.
+     */
+    known: boolean;
+    /** Why the set is incomplete, when it is. Shown to the reader beside the actions. */
+    reason?: string;
+}
+/**
+ * Union a principal's grants into the permission set it actually holds.
+ *
+ * UNION, never intersection and never "the first row": a principal reaches a resource
+ * through several grants (a direct one and one inherited from each role), and what
+ * they may do is everything any of those grants allows. Reading one row is what made
+ * an administrator display as read-only.
+ *
+ * An unrecognised action word makes the whole answer unknown rather than being
+ * skipped. Skipping it would under-report, and under-reporting a permission is the
+ * direction that misleads an operator into thinking access is safe to ignore.
+ *
+ * @param actions - every action string from every grant reaching this principal.
+ * @returns The unioned set, or an explicit unknown with the reason.
+ */
+export declare function resolveActions(actions: readonly string[]): ResolvedActions;
+/**
+ * Whether a resolved set confers the ability to change a document.
+ *
+ * Used by the page to check itself against what the reader can actually do. `manage`
+ * implies write in this model: it is the full-control level, and a principal holding
+ * it can move and delete.
+ * @param resolved - the unioned permission set.
+ * @returns true when writing is possible, or unknown.
+ */
+export declare function canWriteWith(resolved: ResolvedActions): boolean | undefined;
+/**
+ * Collapse a set of action strings into the shortest describing list.
+ *
+ * A thin view over {@link resolveActions} so there is ONE vocabulary and ONE union
+ * rule in the browser: this used to be a second implementation filtering on
+ * `create`/`update`/`delete`, which silently dropped every `write` and `manage` grant.
+ *
+ * Kept as an exported name because the older callers and their tests use it.
+ * @param actions - raw action strings from grants.
+ * @returns The unioned actions in display order; unknown words are dropped here,
+ *   which is why a surface that must not under-report calls {@link resolveActions}.
+ */
+export declare function summarizeActions(actions: readonly string[]): string[];
+/**
+ * Group grants by the principal they name.
+ *
+ * A principal appearing in several grants is one row: "what does 张三 have" is a
+ * question about a person, and splitting them across rows because they hold two
+ * paths would answer it wrong.
+ *
+ * @param grants - the grant table.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @returns one entry per principal, ordered by label then id.
+ */
+export declare function groupHoldingsByPrincipal(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>): PersonHoldings[];
+/**
+ * Group grants by the resource they cover.
+ *
+ * @param grants - the grant table.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @returns one entry per path, ordered by path.
+ */
+export declare function groupHoldingsByResource(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>): ResourceHoldings[];
+/**
+ * Format a grant instant the way the reference table does.
+ *
+ * DataOps' permission preview prints `YYYY/MM/DD HH:mm` and a dash for a missing
+ * value, so a reader comparing the two surfaces sees the same date. The raw
+ * ISO-8601 string the API returns is not that.
+ * @param value - ISO-8601 instant, or an empty string when the backend sent none.
+ * @returns The formatted instant, or a dash when there is nothing to show.
+ */
+export declare function formatGrantInstant(value: string): string;
+/**
+ * One DataOps account as the user directory reports it, reduced to what grouping needs.
+ *
+ * `roles` is what makes inheritance visible: a role grant names the ROLE, so without
+ * the membership list the page can only show role grants as belonging to nobody. The
+ * directory is the only source for it, and it is administrator-only -- see
+ * {@link DirectoryState}.
+ */
+export interface DirectoryUser {
+    /** DataOps user id, which is what a `user` grant names. */
+    userId: string;
+    /** Login name, shown beside the display name so two "张伟" can be told apart. */
+    username: string;
+    /** Display name, when the account has one. */
+    displayName: string;
+    /** Role codes this account belongs to. */
+    roleCodes: string[];
+}
+/**
+ * Whether the user directory could be read.
+ *
+ * Three states, not two. "Nobody holds a role" and "we could not look" produce the same
+ * empty membership map, and rendering them the same way is how a page ends up telling
+ * an operator that nobody has inherited access when the truth is that the read failed.
+ */
+export type DirectoryState = {
+    kind: 'available';
+    users: readonly DirectoryUser[];
+} | {
+    kind: 'unavailable';
+    reason: string;
+};
+/** One account's holdings, as the by-person view renders them. */
+export interface AccountHoldings {
+    /** The account id. */
+    userId: string;
+    /** Login name, for disambiguating identical display names. */
+    username?: string;
+    /** Display name, or the id when the account is not in the directory. */
+    label: string;
+    /** Distinct paths this account reaches, directly or through a role. */
+    paths: string[];
+    /** The unioned permission set, never narrowed by a single grant. */
+    resolved: ResolvedActions;
+    /** Direct grants the account holds itself. */
+    directGrants: GrantView[];
+    /**
+     * Role codes the account inherits through.
+     *
+     * Empty when the directory could not be read; {@link inheritanceKnown} says which.
+     */
+    viaRoles: string[];
+    /** Whether the inheritance half of this row was actually determined. */
+    inheritanceKnown: boolean;
+    /** Why inheritance is unknown, when it is. */
+    inheritanceReason?: string;
+    /** Most recent grant instant across the rows this account covers. */
+    latestAt: string;
+}
+/** One role's holdings, as the by-role view renders them. */
+export interface RoleHoldings {
+    /** Role code, which is what a `role` grant names. */
+    roleCode: string;
+    /** Role display name when the directory resolved one, else the code. */
+    label: string;
+    /** Distinct paths the role covers. */
+    paths: string[];
+    /** The unioned permission set for this role. */
+    resolved: ResolvedActions;
+    /** Grants that name this role. */
+    grants: GrantView[];
+    /** How many directory accounts belong to this role, when the directory is known. */
+    memberCount?: number;
+    /** Most recent grant instant across this role's rows. */
+    latestAt: string;
+}
+/**
+ * Group grants by the DataOps ACCOUNT that holds them.
+ *
+ * The account is the row grain because "who can see this" is a question about people.
+ * A role grant confers access on every member of that role, so its paths are attributed
+ * to each member here -- otherwise a reader whose access is entirely role-derived would
+ * appear on no row at all, and the page would say "nobody has access" to somebody who
+ * can write.
+ *
+ * Three sources are merged, and the merge is a UNION:
+ * 1. direct `user` grants;
+ * 2. grants held by any role the account belongs to (inherited);
+ * 3. nothing else -- the built-in administrator levels are already rows in the grant
+ *    table (`source: 'seed'`), so hard-coding them here would create a second authority
+ *    that could disagree with the backend.
+ *
+ * @param grants - the whole grant table.
+ * @param directory - the user directory, or the reason it could not be read.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @returns One row per account that holds or inherits at least one grant, sorted by label.
+ */
+export declare function groupHoldingsByAccount(grants: readonly GrantView[], directory: DirectoryState, labels?: Readonly<Record<string, string>>): AccountHoldings[];
+/**
+ * Group grants by the ROLE they name.
+ *
+ * The same grants the old "by person" table showed, now labelled as what they are: a
+ * role is not a person, and putting it under "by person" told the reader that the
+ * administrators were the only people with access.
+ *
+ * A role whose grants are all unreadable still gets a row with `known: false`: that is
+ * the safety net against rendering "no permission" for a read failure.
+ *
+ * @param grants - the whole grant table.
+ * @param labels - display names by `principalType:principalId`, optional.
+ * @param memberCounts - role code -> member count, when the directory is known.
+ * @returns One row per role named by at least one grant, sorted by label.
+ */
+export declare function groupHoldingsByRole(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>, memberCounts?: ReadonlyMap<string, number>): RoleHoldings[];
+/**
+ * Build the role -> member-count map from a directory.
+ *
+ * Only meaningful when the directory is known; returns undefined otherwise so the row
+ * omits the count rather than claiming zero members.
+ * @param directory - the user directory state.
+ * @returns Counts by role code, or undefined when unavailable.
+ */
+export declare function roleMemberCounts(directory: DirectoryState): Map<string, number> | undefined;

package/lib/types/client/progressRules.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The progress strip's two decisions, kept out of the component.
+ *
+ * Both are answers about data rather than about React: whether a batch is finished, and
+ * whether a retry button would help. They live here because a `.tsx` module that imports
+ * the UI primitives cannot be loaded by the test runner (the primitives package imports
+ * CSS at module scope, which the runner cannot resolve), so a test that imported the
+ * component would fail before reaching any assertion.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Whether the strip may fold now.
+ *
+ * Folded means "one summary line instead of a list". It folds when every task in both
+ * groups reached a terminal state AND the batch has not been folded before -- the
+ * second half is what stops it re-folding after a reader expanded a finished batch to
+ * read which file failed.
+ * @param uploads - the current batch's rows.
+ * @param extractions - the extraction tasks the Host reports.
+ * @param alreadyFolded - whether a fold already happened for this batch.
+ * @returns Whether to fold.
+ */
+export declare function shouldFoldStrip(uploads: readonly {
+    state: string;
+}[], extractions: readonly {
+    state: string;
+}[], alreadyFolded: boolean): boolean;
+/**
+ * Whether a retry button would help for this state.
+ *
+ * Only a failure is worth retrying. `unsupported` means no extractor exists for the
+ * type, so a retry fails identically and the button would be a lie; the pending and
+ * running states are already being handled.
+ * @param state - the extraction state.
+ * @returns Whether to offer a retry.
+ */
+export declare function canRetryExtraction(state: string): boolean;
+/**
+ * A failure reason that survives a response which is not JSON.
+ *
+ * A gateway answering 502 sends HTML, and `response.json()` rejects on it. If that
+ * rejection escaped, the row would report "failed" with no reason at all -- which is
+ * exactly the silence this strip exists to remove. So the body is attempted, and an
+ * unreadable body falls back to the status code, which still tells the reader whether
+ * the server refused them (4xx) or broke (5xx).
+ * @param body - the parsed body, when it parsed.
+ * @param status - the HTTP status.
+ * @returns A sentence a reader can act on.
+ */
+export declare function failureReason(body: {
+    error?: unknown;
+    code?: unknown;
+} | undefined, status: number): string;

package/lib/types/client/referenceTargets.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for the reference picker and the batch menu.
+ *
+ * Kept out of the components because the parts worth testing are the decisions, not the
+ * rendering: how a selection becomes a target list, what the batch label says, and which
+ * entries a paste loop should attempt. The components are wired to these, so a change in
+ * behaviour here is what the tests below pin down; the real DOM interaction is covered by
+ * the browser walkthrough instead.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One entry a reference will be inserted for, in absolute path form. */
+export interface ReferenceTarget {
+    /** Absolute path as the tree and the routes speak it. */
+    path: string;
+    /** True for a directory (folder mention) rather than a document (file chip). */
+    isDir: boolean;
+}
+/** One row a batch action covers. */
+export interface BatchRow {
+    /** Path relative to the knowledge root. */
+    relPath: string;
+    /** Display name, for menu copy. */
+    name: string;
+    /** Whether the row is a directory. */
+    isDir: boolean;
+}
+/**
+ * The entries a picker opened on `relPath` should insert.
+ *
+ * A multi-row selection wins when it contains the clicked row, because that is the set
+ * the reader could see highlighted. Otherwise the click is a single-row action on the row
+ * under the pointer -- which is also what happens when the clicked row sits outside the
+ * selection, since acting on a batch the reader did not point at would be a surprise.
+ * @param relPath - the row the `@` button was pressed on.
+ * @param selection - the rows the explorer reports as selected, if any.
+ * @returns One target, or every selected row when the click was inside the selection.
+ */
+export declare function referenceTargetsFor(relPath: string, selection?: readonly BatchRow[]): ReferenceTarget[];
+/**
+ * The rows a menu opened on one row should act on.
+ *
+ * Mirrors {@link referenceTargetsFor}: a right-click inside a multi-selection acts on the
+ * whole selection, and anywhere else acts on the one row. The menu and the picker must
+ * agree, or a "delete 3 items" dialog would reference four.
+ * @param target - the row under the pointer.
+ * @param selection - the rows marked selected, if any.
+ * @returns The rows the batch entries cover, or an empty list for a single-row menu.
+ */
+export declare function batchRowsFor(target: BatchRow, selection?: readonly BatchRow[]): BatchRow[];
+/**
+ * Fill a batch label's `{n}` placeholder.
+ *
+ * A separate function so the count is formatted in one place: a label that prints the
+ * rows it will touch must never print a different number from the rows it does touch.
+ * @param template - the locale string, containing `{n}`.
+ * @param count - how many rows.
+ * @returns The label with the count substituted.
+ */
+export declare function batchLabel(template: string, count: number): string;

package/lib/types/client/roleSummary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What each role in the grant table actually amounts to.
+ *
+ * A role is not stored anywhere: it exists because grants name it. That is a good
+ * property to inherit — a role cannot outlive its resources or appear with none —
+ * but it means "list the roles" is a question about the grants, answered by
+ * reading them. This module is that reading, kept out of the component so it can
+ * be tested without a DOM.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/roleSummary
+ */
+import type { GrantView } from '../api.ts';
+/** One role as the overview shows it. */
+export interface RoleSummary {
+    /** Role id, which is the `principalId` its grants carry. */
+    id: string;
+    /** Display name, falling back to the id when no locale entry matches. */
+    label: string;
+    /** Actions granted anywhere by this role, collapsed so a full house reads `all`. */
+    actions: string[];
+    /** Distinct paths it reaches. */
+    paths: string[];
+    /** Whether this is one of the two the product ships with. */
+    builtIn: boolean;
+}
+/**
+ * Collapse raw action strings into the shortest describing list.
+ *
+ * The client needs this independently of the server: the overview renders grants
+ * the server already wrote, so it summarizes what is there rather than what a
+ * request asked for.
+ *
+ * @param actions - raw action strings.
+ * @returns `['all']` when all four concrete actions are held, else the subset.
+ */
+export declare function summarizeRoleActions(actions: readonly string[]): string[];
+/**
+ * Read the roles out of a grant table.
+ *
+ * Only `role` grants contribute: a user grant is not a role, and inventing one
+ * per user would flood the list with rows that mean nothing.
+ *
+ * @param grants - the grant table.
+ * @param locale - `zh` or `en`, for the built-in role names.
+ * @returns one entry per role named by a grant, built-ins first then alphabetical.
+ */
+export declare function buildRoleSummaries(grants: readonly GrantView[], locale?: 'zh' | 'en'): RoleSummary[];