@gaia-ai/addon-gaia-ui 0.7.0 → 0.8.0

package/dist/src/Entity/cycle.d.ts

@@ -0,0 +1,18 @@
+/** Next value in a cyclic list; `null` (== "all") wraps at both ends. */
+export declare function cycleValue<T>(values: readonly T[], current: T | null): T | null;
+/** The closed cycle order; null ("all") wraps at both ends via cycleValue. */
+export declare const CLOSED_FILTER_VALUES: readonly [false, true];
+/**
+ * Rows per page in the project ticket and run lists (GAIA-292 D1).
+ *
+ * Lives here, beside the shared closed cycle, because BOTH slices need it and
+ * `Entity/cycle.ts` is the slice-less module they may each import without
+ * closing the G1 cycle.
+ *
+ * 20 since the operator's live review of GAIA-292; the spec's measurements and
+ * D6 were taken at 15, and the spec records the change rather than hiding it.
+ *
+ * The parent picker deliberately does NOT use this: it reads one un-paged bag of
+ * `PARENT_PAGE_SIZE` candidates and discloses truncation at that number.
+ */
+export declare const LIST_PAGE_SIZE = 20;

package/dist/src/Entity/cycle.js

@@ -0,0 +1,30 @@
+// The shared list-cycling primitive. Slice-less like `transport.ts` — BOTH the
+// ticket and the run slice import it, and the entity slices must stay acyclic
+// (G1): a run → ticket import would close the project → ticket → run → ticket
+// cycle (GAIA-282; the ticket query module re-exports both symbols so its
+// established import sites keep working).
+/** Next value in a cyclic list; `null` (== "all") wraps at both ends. */
+export function cycleValue(values, current) {
+    if (current == null)
+        return values[0] ?? null;
+    const i = values.indexOf(current);
+    if (i < 0 || i === values.length - 1)
+        return null;
+    return values[i + 1] ?? null;
+}
+/** The closed cycle order; null ("all") wraps at both ends via cycleValue. */
+export const CLOSED_FILTER_VALUES = [false, true];
+/**
+ * Rows per page in the project ticket and run lists (GAIA-292 D1).
+ *
+ * Lives here, beside the shared closed cycle, because BOTH slices need it and
+ * `Entity/cycle.ts` is the slice-less module they may each import without
+ * closing the G1 cycle.
+ *
+ * 20 since the operator's live review of GAIA-292; the spec's measurements and
+ * D6 were taken at 15, and the spec records the change rather than hiding it.
+ *
+ * The parent picker deliberately does NOT use this: it reads one un-paged bag of
+ * `PARENT_PAGE_SIZE` candidates and discloses truncation at that number.
+ */
+export const LIST_PAGE_SIZE = 20;

package/dist/src/Entity/project/Data/project.d.ts

@@ -0,0 +1,8 @@
+import type { DropshClient } from '../../../types.js';
+export interface ResolvedProject {
+    id: string;
+    name: string;
+    slug: string;
+}
+/** Resolve project identity without reading any project-owned collections. */
+export declare function resolveProject(client: DropshClient, slug: string): Promise<ResolvedProject>;

package/dist/src/Entity/project/Data/project.js

@@ -0,0 +1,12 @@
+/** Resolve project identity without reading any project-owned collections. */
+export async function resolveProject(client, slug) {
+    const document = await client
+        .collection('gaia_project')
+        .where('name', '=', slug)
+        .first();
+    return {
+        id: document?.id ?? slug,
+        name: document?.attr('name') ?? slug,
+        slug,
+    };
+}

package/dist/src/Entity/project/Data/projects.d.ts

@@ -3,6 +3,9 @@ import { type ConductorStatus } from '../../conductor/Data/liveness.js';
 /** A derived project row: one distinct project + its liveliest conductor. */
 export interface ProjectRow {
     project: string;
+    projectId: string;
+    projectName: string;
+    projectSlug: string;
     derivedStatus: ConductorStatus;
     lastSeen: number | null;
     ageLabel: string;

package/dist/src/Entity/project/Data/projects.js

@@ -74,6 +74,9 @@ export async function loadProjectRows({ client, nowSeconds, }) {
     }
     return [...best.entries()].map(([project, b]) => ({
         project,
+        projectId: [...projectNameById.entries()].find(([, name]) => name === project)?.[0] ?? project,
+        projectName: project,
+        projectSlug: project,
         derivedStatus: b.derivedStatus,
         lastSeen: b.lastSeen,
         ageLabel: humanizeAge(b.lastSeen, now),

package/dist/src/Entity/project/Data/with-tickets.d.ts

@@ -16,5 +16,10 @@ export interface ProjectWithTickets {
  * The ticket listing delegates to {@link loadFilteredTickets} with empty
  * criteria — one include-aware `client.get` path shared with the search/filter
  * load, so both resolve parent/conductor identically (no dual-mapper drift).
+ *
+ * It takes the loader's FIRST page and drops the `hasNext` beside it (GAIA-292):
+ * this read has no paging affordance of its own — it is the overview header's
+ * ticket bag, not the paged Tickets tab — so the flag has no consumer here and
+ * carrying it would imply a control that does not exist.
  */
 export declare function loadProjectWithTickets(client: DropshClient, projectSlug: string): Promise<ProjectWithTickets>;

package/dist/src/Entity/project/Data/with-tickets.js

@@ -6,6 +6,7 @@
 // `loadFilteredTickets` so the search/filter path and this one resolve
 // parent/conductor through the same mapper, with no dual-mapper drift.
 import { loadFilteredTickets, } from '../../ticket/Data/tickets.js';
+import { resolveProject } from './project.js';
 /**
  * Resolve a `gaia_project` by its slug (the registry `project`, which matches
  * the project's `name`) and list its tickets, most-recently-changed first.
@@ -13,24 +14,25 @@ import { loadFilteredTickets, } from '../../ticket/Data/tickets.js';
  * The ticket listing delegates to {@link loadFilteredTickets} with empty
  * criteria — one include-aware `client.get` path shared with the search/filter
  * load, so both resolve parent/conductor identically (no dual-mapper drift).
+ *
+ * It takes the loader's FIRST page and drops the `hasNext` beside it (GAIA-292):
+ * this read has no paging affordance of its own — it is the overview header's
+ * ticket bag, not the paged Tickets tab — so the flag has no consumer here and
+ * carrying it would imply a control that does not exist.
  */
 export async function loadProjectWithTickets(client, projectSlug) {
-    const projectRes = await client
-        .collection('gaia_project')
-        .where('name', '=', projectSlug)
-        .first();
-    const projectId = projectRes?.id ?? projectSlug;
-    const tickets = await loadFilteredTickets(client, projectId, {
+    const project = await resolveProject(client, projectSlug);
+    const page = await loadFilteredTickets(client, project.id, {
         query: '',
         state: null,
-        type: null,
+        // closed: null — this is the project overview read, not the ticket list;
+        // it keeps "show everything" (spec D6).
+        closed: null,
+        parent: null,
+        who: null,
     });
     return {
-        project: {
-            id: projectId,
-            name: projectRes?.attr('name') ?? projectSlug,
-            slug: projectSlug,
-        },
-        tickets,
+        project,
+        tickets: page.rows,
     };
 }

package/dist/src/Entity/project/Screen/project-picker.d.ts

@@ -0,0 +1,36 @@
+import { BaseScreen, type ScreenContext } from '../../../Screen/screen.js';
+import { type PickerCandidate } from '../Component/project-picker/index.js';
+export interface ProjectPickerInput {
+    readonly candidates: readonly PickerCandidate[];
+    readonly repo: string;
+}
+export declare const projectPickerInputContext: import("../../../Routing/context.js").ContextKey<ProjectPickerInput>;
+export declare class ProjectPickerScreen extends BaseScreen {
+    readonly frameId = "project-picker";
+    topTab(): {
+        readonly level: "root";
+        readonly tab: "projects";
+    };
+    static readonly route: {
+        id: string;
+        path: string;
+        parent: string;
+        fallback: {
+            routeId: string;
+        };
+        context: (_params: Readonly<Record<string, string>>, state: unknown, base: import("../../../Routing/context.js").ContextBag) => import("../../../Routing/context.js").ContextBag;
+    };
+    readonly id: string;
+    private candidates;
+    private repo;
+    selectedIndex: number;
+    enter(context: ScreenContext): void;
+    get rows(): readonly PickerCandidate[];
+    render(): string[];
+    renderNonInteractive(): string[];
+    present(_context: ScreenContext): import("../../../Screen/screen.js").ScreenPresentation;
+    handleInput(input: string, context: ScreenContext): boolean;
+    activate(index: number, context: ScreenContext): boolean;
+    select(index: number, context: ScreenContext): boolean;
+    reset(): void;
+}

package/dist/src/Entity/project/Screen/project-picker.js

@@ -0,0 +1,90 @@
+import { defineContext } from '../../../Routing/context.js';
+import { BaseScreen, presentation, } from '../../../Screen/screen.js';
+import { projectPickerRows, } from '../Component/project-picker/index.js';
+export const projectPickerInputContext = defineContext('project-picker-input', 'input');
+export class ProjectPickerScreen extends BaseScreen {
+    frameId = 'project-picker';
+    topTab() {
+        return { level: 'root', tab: 'projects' };
+    }
+    static route = {
+        id: 'project.picker',
+        path: '/projects/pick',
+        parent: 'projects',
+        fallback: { routeId: 'project.dashboard' },
+        context: (_params, state, base) => state
+            ? base.set(projectPickerInputContext, state)
+            : base,
+    };
+    id = ProjectPickerScreen.route.id;
+    candidates = [];
+    repo = '';
+    selectedIndex = 0;
+    enter(context) {
+        const input = context.contexts?.has(projectPickerInputContext)
+            ? context.contexts.get(projectPickerInputContext)
+            : undefined;
+        if (input) {
+            this.candidates = [...input.candidates];
+            this.repo = input.repo;
+            this.selectedIndex = 0;
+        }
+        context.requestDraw();
+    }
+    get rows() {
+        return this.candidates;
+    }
+    render() {
+        return projectPickerRows(this.candidates, this.repo, this.selectedIndex);
+    }
+    renderNonInteractive() {
+        return [
+            ...this.render(),
+            '',
+            'Run gaia ui project:<name> to choose directly.',
+        ];
+    }
+    present(_context) {
+        return presentation(this.render(), {
+            selectable: this.candidates.length,
+            selectedIndex: this.selectedIndex,
+            selectedRow: this.candidates.length ? 2 + this.selectedIndex : -1,
+            title: 'Which project?',
+            meta: `${this.candidates.length} project(s) claim ${this.repo}  ·  Enter open · Esc dashboard`,
+            status: ' ↑↓ select · Enter open · Esc dashboard · q quit ',
+        });
+    }
+    handleInput(input, context) {
+        if (input === 'j' || input === '\x1b[B')
+            this.selectedIndex = Math.min(this.selectedIndex + 1, this.candidates.length - 1);
+        else if (input === 'k' || input === '\x1b[A')
+            this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
+        else
+            return false;
+        context.requestDraw();
+        return true;
+    }
+    activate(index, context) {
+        const picked = this.candidates[index];
+        if (!picked || !context.navigate)
+            return false;
+        context.navigate('project.dashboard', {
+            projectId: picked.id,
+            projectName: picked.name,
+            projectSlug: picked.name,
+        });
+        return true;
+    }
+    select(index, context) {
+        if (index < 0 || index >= this.candidates.length)
+            return false;
+        this.selectedIndex = index;
+        context.requestDraw();
+        return true;
+    }
+    reset() {
+        this.candidates = [];
+        this.repo = '';
+        this.selectedIndex = 0;
+    }
+}

package/dist/src/Entity/project/Screen/projects-screen.d.ts

@@ -0,0 +1,40 @@
+import { AsyncScreen } from '../../../Screen/async-screen.js';
+import { type ScreenContext } from '../../../Screen/screen.js';
+import { type ProjectRow } from '../Data/projects.js';
+export declare class ProjectsScreen extends AsyncScreen<ProjectRow[]> {
+    readonly frameId = "projects";
+    topTab(): {
+        readonly level: "root";
+        readonly tab: "projects";
+    };
+    reload(context: ScreenContext): void;
+    static readonly route: {
+        id: string;
+        path: string;
+        tab: {
+            id: string;
+            label: string;
+            scope: string;
+            order: number;
+        };
+    };
+    readonly id: string;
+    private readonly cursor;
+    /** Kept as a settable PUBLIC member: the kernel reads it and
+     *  `tests/Screen/project-screens.test.ts` writes it (GAIA-294 D2). */
+    get selectedIndex(): number;
+    set selectedIndex(value: number);
+    saveState(): {
+        selectedIndex: number;
+    };
+    restoreState(token: unknown): void;
+    get rows(): readonly ProjectRow[];
+    protected load(context: ScreenContext): Promise<ProjectRow[]>;
+    protected renderLoading(): string[];
+    protected renderReady(rows: ProjectRow[]): string[];
+    present(context: ScreenContext): import("../../../Screen/screen.js").ScreenPresentation;
+    activate(index: number, context: ScreenContext): boolean;
+    select(index: number, context: ScreenContext): boolean;
+    handleInput(input: string, context: ScreenContext): boolean;
+    reset(): void;
+}

package/dist/src/Entity/project/Screen/projects-screen.js

@@ -0,0 +1,103 @@
+import { ListCursor } from '../../../lib/cursor.js';
+import { AsyncScreen } from '../../../Screen/async-screen.js';
+import { presentation } from '../../../Screen/screen.js';
+import { projectRows } from '../Component/project-list/index.js';
+import { loadProjectRows } from '../Data/projects.js';
+export class ProjectsScreen extends AsyncScreen {
+    frameId = 'projects';
+    topTab() {
+        return { level: 'root', tab: 'projects' };
+    }
+    reload(context) {
+        this.retry(context);
+    }
+    static route = {
+        id: 'projects',
+        path: '/projects',
+        tab: { id: 'projects', label: 'Projects', scope: 'root', order: 20 },
+    };
+    id = ProjectsScreen.route.id;
+    cursor = new ListCursor();
+    /** Kept as a settable PUBLIC member: the kernel reads it and
+     *  `tests/Screen/project-screens.test.ts` writes it (GAIA-294 D2). */
+    get selectedIndex() {
+        return this.cursor.index;
+    }
+    set selectedIndex(value) {
+        this.cursor.index = value;
+    }
+    saveState() {
+        return { selectedIndex: this.selectedIndex };
+    }
+    restoreState(token) {
+        if (token &&
+            typeof token === 'object' &&
+            typeof token.selectedIndex === 'number') {
+            this.selectedIndex = token.selectedIndex;
+        }
+    }
+    get rows() {
+        return this.readyValue ?? [];
+    }
+    load(context) {
+        if (!context.services)
+            throw new Error('Projects requires services');
+        return loadProjectRows({
+            client: context.services.client,
+            nowSeconds: context.nowSeconds ?? (() => Math.floor(Date.now() / 1000)),
+        });
+    }
+    renderLoading() {
+        return ['Loading projects…'];
+    }
+    renderReady(rows) {
+        return projectRows(rows);
+    }
+    present(context) {
+        const rows = this.rows;
+        return presentation(this.render(context), {
+            selectable: rows.length,
+            selectedIndex: this.selectedIndex,
+            selectedRow: rows.length ? this.selectedIndex : -1,
+            title: 'GAIA projects',
+            meta: `${rows.length} registered project(s)  ·  ${context.services?.baseUrl ?? ''}`,
+            status: ' ↑↓ select · Enter open · n new · Tab tabs · q quit ',
+        });
+    }
+    activate(index, context) {
+        const row = this.readyValue?.[index];
+        if (!row || !context.navigate)
+            return false;
+        context.navigate('project.dashboard', {
+            projectId: row.projectId,
+            projectName: row.projectName,
+            projectSlug: row.projectSlug,
+        });
+        return true;
+    }
+    select(index, context) {
+        if (index < 0 || index >= this.rows.length)
+            return false;
+        this.selectedIndex = index;
+        context.requestDraw();
+        return true;
+    }
+    handleInput(input, context) {
+        if (super.handleInput(input, context))
+            return true;
+        const rows = this.readyValue;
+        if (!rows)
+            return false;
+        if (this.cursor.handle(input, rows.length)) {
+            context.requestDraw();
+            return true;
+        }
+        if (input === '\r' || input === '\n')
+            return this.activate(this.selectedIndex, context);
+        return false;
+    }
+    reset() {
+        this.cursor.reset();
+        super.reset();
+    }
+}

package/dist/src/Entity/run/Component/run-table/index.d.ts

@@ -1,10 +1,8 @@
-import type { RunRow } from '../../Data/runs.js';
-/**
- * A fixed-column flat table of a project's runs: header + one line per run.
- * Columns RUN · TICKET · STATE · PHASE · AGENT · STARTED, mirroring
- * `ticketTableRows` (1 logical entry = 1 physical row). STATE is the derived
- * liveness status and STARTED is the relative start age.
- */
+import { type RunRow } from '../../Data/runs.js';
+/** A fixed-column flat table of a project's runs: header + one line per run.
+ *  Columns RUN · TICKET · STATE · PHASE · AGENT · STARTED, declared beside the row
+ *  mapper in `Data/runs.ts` (GAIA-294). STATE is the derived liveness status and
+ *  STARTED the relative start age, which is what `nowSeconds` is for. */
 export declare function runTableRows(runs: RunRow[], nowSeconds: number, { emptyMessage }?: {
     emptyMessage?: string | undefined;
 }): string[];

package/dist/src/Entity/run/Component/run-table/index.js

@@ -1,20 +1,11 @@
-import { pad } from '../../../../lib/format.js';
-import { deriveRunStatus, runStartedAge } from '../../Data/status.js';
-/**
- * A fixed-column flat table of a project's runs: header + one line per run.
- * Columns RUN · TICKET · STATE · PHASE · AGENT · STARTED, mirroring
- * `ticketTableRows` (1 logical entry = 1 physical row). STATE is the derived
- * liveness status and STARTED is the relative start age.
- */
+import { renderTable } from '../../../../lib/table.js';
+import { RUN_COLUMNS } from '../../Data/runs.js';
+/** A fixed-column flat table of a project's runs: header + one line per run.
+ *  Columns RUN · TICKET · STATE · PHASE · AGENT · STARTED, declared beside the row
+ *  mapper in `Data/runs.ts` (GAIA-294). STATE is the derived liveness status and
+ *  STARTED the relative start age, which is what `nowSeconds` is for. */
 export function runTableRows(runs, nowSeconds, { emptyMessage } = {}) {
-    const header = `${pad('RUN', 8)} ${pad('TICKET', 10)} ${pad('STATE', 8)} ${pad('PHASE', 10)} ${pad('AGENT', 8)} STARTED`;
-    if (runs.length === 0)
-        return [header, emptyMessage ?? 'No runs for this project.'];
-    return [
-        header,
-        ...runs.map((r) => {
-            const run = `#${r.drupalId ?? r.id.slice(0, 6)}`;
-            return `${pad(run, 8)} ${pad(r.ticketIdentifier, 10)} ${pad(deriveRunStatus(r, nowSeconds), 8)} ${pad(r.phase, 10)} ${pad(r.agent, 8)} ${runStartedAge(r, nowSeconds)}`;
-        }),
-    ];
+    return renderTable(RUN_COLUMNS, runs, nowSeconds, {
+        emptyMessage: emptyMessage ?? 'No runs for this project.',
+    });
 }

package/dist/src/Entity/run/Data/query.d.ts

@@ -0,0 +1,22 @@
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+/** The active filter criteria for the project run list. */
+export interface RunCriteria {
+    /** false: open only (the default) · true: closed only · null: all. */
+    closed: boolean | null;
+}
+/** The shipped default: closed runs hidden (GAIA-282 D1). */
+export declare const DEFAULT_RUN_CRITERIA: RunCriteria;
+/** "Active" means the view is narrowed relative to showing every row —
+ *  true at the shipped default, by the same decision as the ticket list. */
+export declare function hasActiveCriteria(criteria: RunCriteria): boolean;
+/** Human-readable active-criteria summary, or '' when none. */
+export declare function describeCriteria(criteria: RunCriteria): string;
+/**
+ * Build the JSON:API query for a project's runs under the given criteria.
+ * Scope is the ticket→project relationship (a project may span conductors).
+ * '1'/'0', never the boolean — spec fact 7's measured backend behavior.
+ */
+export declare function buildRunQueryParams(projectId: string, criteria: RunCriteria, page?: {
+    size: number;
+    index: number;
+}): DrupalJsonApiParams;

package/dist/src/Entity/run/Data/query.js

@@ -0,0 +1,41 @@
+// The run list's criteria — the same shape the ticket list established
+// (GAIA-282 D4, AC-6): criteria type, hasActive, describe, param builder.
+// Runs offer only the closed cycle; search/state are not part of GAIA-282.
+import { DrupalJsonApiParams } from 'drupal-jsonapi-params';
+import { LIST_PAGE_SIZE } from '../../cycle.js';
+import { RUN_LIST_FIELDS, RUN_TICKET_INCLUDE_FIELDS } from './runs.js';
+/** The shipped default: closed runs hidden (GAIA-282 D1). */
+export const DEFAULT_RUN_CRITERIA = { closed: false };
+/** "Active" means the view is narrowed relative to showing every row —
+ *  true at the shipped default, by the same decision as the ticket list. */
+export function hasActiveCriteria(criteria) {
+    return criteria.closed !== null;
+}
+/** Human-readable active-criteria summary, or '' when none. */
+export function describeCriteria(criteria) {
+    if (criteria.closed === null)
+        return '';
+    return criteria.closed ? 'closed:only' : 'closed:hidden';
+}
+/**
+ * Build the JSON:API query for a project's runs under the given criteria.
+ * Scope is the ticket→project relationship (a project may span conductors).
+ * '1'/'0', never the boolean — spec fact 7's measured backend behavior.
+ */
+export function buildRunQueryParams(projectId, criteria, page = { size: LIST_PAGE_SIZE, index: 0 }) {
+    const params = new DrupalJsonApiParams();
+    params.addFilter('ticket_id.project_id.id', projectId);
+    if (criteria.closed !== null)
+        params.addFilter('closed', criteria.closed ? '1' : '0');
+    params.addInclude(['ticket_id']);
+    // Unlike the ticket list, this fieldset governs the INCLUDES only — the
+    // primary type here is `gaia_run` (GAIA-292 D3).
+    params.addFields('gaia_ticket--gaia_ticket', RUN_TICKET_INCLUDE_FIELDS);
+    params.addFields('gaia_run--gaia_run', RUN_LIST_FIELDS);
+    params.addSort('started_at', 'DESC');
+    params.addPageLimit(page.size);
+    // Page one carries no offset, so its query is the shortest it can be.
+    if (page.index > 0)
+        params.addPageOffset(page.index * page.size);
+    return params;
+}

package/dist/src/Entity/run/Data/runs.d.ts

@@ -1,4 +1,6 @@
 import type { DropshClient, JsonApiResource } from '../../../types.js';
+import { type Page } from '../../collection.js';
+import { type RunCriteria } from './query.js';
 /** One flat-table row derived from a `gaia_run` dropsh resource. */
 export interface RunRow {
     id: string;
@@ -18,19 +20,98 @@ export interface RunRow {
     startedAt: string | null;
     heartbeat: string | null;
     claimExpiresAt: string | null;
+    /** Boolean closed flag; an absent attribute reads as open (spec D5). */
+    closed: boolean;
 }
+/** In the fieldset, or the sideloaded ticket stops resolving (spec fact 5). */
+export declare const RUN_LIST_RELATIONSHIPS: readonly ["ticket_id"];
+/**
+ * The run list's columns — RUN · TICKET · STATE · PHASE · AGENT · STARTED, each
+ * carrying its own fieldset entry (GAIA-294 AC 4).
+ *
+ * `Ctx` is `nowSeconds`: STATE is the derived liveness status and STARTED the
+ * relative start age, and both need a clock the row does not carry.
+ */
+export declare const RUN_COLUMNS: readonly [{
+    readonly key: "run";
+    readonly label: "RUN";
+    readonly width: 8;
+    readonly fields: readonly ["drupal_internal__id"];
+    readonly get: (r: RunRow) => string;
+}, {
+    readonly key: "ticket";
+    readonly label: "TICKET";
+    readonly width: 10;
+    readonly fields: readonly ["ticket_id"];
+    readonly get: (r: RunRow) => string;
+}, {
+    readonly key: "state";
+    readonly label: "STATE";
+    readonly width: 8;
+    readonly fields: readonly ["state", "heartbeat", "claim_expires_at"];
+    readonly get: (r: RunRow, nowSeconds: number) => string;
+}, {
+    readonly key: "phase";
+    readonly label: "PHASE";
+    readonly width: 10;
+    readonly fields: readonly ["state_at_start"];
+    readonly get: (r: RunRow) => string;
+}, {
+    readonly key: "agent";
+    readonly label: "AGENT";
+    readonly width: 8;
+    readonly fields: readonly ["agent"];
+    readonly get: (r: RunRow) => string;
+}, {
+    readonly key: "started";
+    readonly label: "STARTED";
+    readonly width: 0;
+    readonly fields: readonly ["started_at", "created"];
+    readonly get: (r: RunRow, nowSeconds: number) => string;
+}];
+/**
+ * The attributes a run row needs (GAIA-292 D2), in the order the query string
+ * states them. `created` is a column field as `started_at`'s documented fallback
+ * for a run that never started, and `heartbeat` + `claim_expires_at` ride the STATE
+ * column because `deriveRunStatus` reads them.
+ *
+ * Membership is owned by the columns and proved exhaustive below; only the ORDER
+ * is declared, because `tests/Entity/run/Data/query.test.ts` pins the emitted
+ * `fields[gaia_run--gaia_run]=…` sequence and column order would hoist
+ * `heartbeat`/`claim_expires_at` to third and fourth (GAIA-294, behaviour-neutral
+ * to the bytes on the wire).
+ */
+export declare const RUN_LIST_ATTRIBUTES: readonly ["drupal_internal__id", "state", "state_at_start", "agent", "started_at", "created", "heartbeat", "claim_expires_at", "closed"];
+/** What `addFields('gaia_run--gaia_run', …)` takes. */
+export declare const RUN_LIST_FIELDS: string[];
+/**
+ * The sideloaded ticket renders ONE column: its identifier.
+ *
+ * Measured (GAIA-292 spec fact 4): without this, a 37-row run page shipped
+ * 191.4 KB of `included` — 12 whole ticket resources with their descriptions —
+ * out of 254.7 KB total, and took 4732 ms.
+ */
+export declare const RUN_TICKET_INCLUDE_FIELDS: string[];
 /**
  * Map a RAW JSON:API `data[]` entry (from `client.get`) to a run row, resolving
  * the ticket identifier from the sideloaded includes indexed by id. Mirrors
  * `mapTicketData` — the only I/O is upstream in {@link loadProjectRuns}.
+ *
+ * Every attribute and relationship is read through an accessor keyed on the
+ * fieldset, so reading one the list does not request is a compile error (AC-5).
  */
 export declare function mapRunData(item: JsonApiResource, ticketsById: Map<string, JsonApiResource>): RunRow;
+/** One page of run rows plus whether another exists — the shared {@link Page},
+ *  whose four members and their meaning are documented there (GAIA-294). */
+export type RunPage = Page<RunRow>;
 /**
- * List the `gaia_run` entities of a project, most-recently-started first.
- * Filtered by `ticket_id.project_id.id`, includes `ticket_id`, sorts
- * `started_at` DESC, pages 50 (deeper history via offset is a later follow-up).
+ * List the `gaia_run` entities of a project under the given criteria,
+ * most-recently-started first — ONE page of them. The query (scope, include,
+ * fieldsets, sort, closed filter) is built by {@link buildRunQueryParams}; the
+ * page (size + index) is the caller's, and `hasNext` comes from the document's
+ * `links.next`.
  */
-export declare function loadProjectRuns(client: DropshClient, projectId: string): Promise<RunRow[]>;
+export declare function loadProjectRuns(client: DropshClient, projectId: string, criteria: RunCriteria, page?: number): Promise<RunPage>;
 /**
  * Newest-STARTED first, and TOTAL (GAIA-255 D5).
  *