@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/counters.js

@@ -0,0 +1,244 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * ID counters — the one file under `.devsteps/index/` that is a source of truth.
+ *
+ * Every other index is derived from the item files by the item store (STORY-426).
+ * The counters cannot be: an ID handed out for a purged item must never be reused,
+ * so the high-water mark per type prefix is persisted here and committed. What can
+ * be derived is a lower bound — the highest ID on disk — and `add` never allocates
+ * below it, so a counter that fell behind after a branch merge heals itself.
+ */
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateCounters } from '../schemas/counters.schema.js';
+import { ItemType } from '../schemas/index.js';
+import { writeFileAtomic } from '../utils/atomic-write.js';
+import { getTypePrefix, parseItemId, TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { acquireCounterLock, assertCounterLockHeld, counterLockStatus, releaseCounterLock, } from './counter-lock.js';
+import { CounterLockError } from './counter-lock-types.js';
+import { archivedTypeDirectory, claimItemFolder, listItemFolders, typeDirectory, } from './item-paths.js';
+export function getCountersPath(devstepsDir) {
+    return join(devstepsDir, 'index', 'counters.json');
+}
+/** Load ID generation counters; an absent file is an empty set of counters. */
+export function loadCounters(devstepsDir) {
+    const countersPath = getCountersPath(devstepsDir);
+    if (!existsSync(countersPath))
+        return {};
+    return validateCounters(JSON.parse(readFileSync(countersPath, 'utf-8')));
+}
+/** lstat also sees dangling links; never derive allocations from an unsafe counter path. */
+function assertCounterFileSafe(devstepsDir) {
+    const path = getCountersPath(devstepsDir);
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!stat || stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1)
+        throw new Error(`Unsafe counter file: ${path}`);
+}
+/** The only raw replacement is private and guarded through the actual atomic write. */
+function mergeCountersHeld(devstepsDir, proposed, context) {
+    const guard = () => {
+        assertCounterLockHeld(context, devstepsDir);
+        assertCounterFileSafe(devstepsDir);
+    };
+    guard();
+    const current = loadCounters(devstepsDir);
+    const merged = Object.fromEntries(Object.entries(current));
+    let changed = !existsSync(getCountersPath(devstepsDir));
+    for (const [prefix, number] of Object.entries(validateCounters(proposed))) {
+        const previous = Object.hasOwn(current, prefix) ? current[prefix] : undefined;
+        if (number > (previous ?? -1))
+            changed = true;
+        Object.defineProperty(merged, prefix, {
+            value: Math.max(previous ?? 0, number),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    if (changed)
+        writeFileAtomic(getCountersPath(devstepsDir), JSON.stringify(merged, null, 2), {
+            beforeWrite: guard,
+            beforeRename: guard,
+        });
+    guard();
+    return { counters: merged, changed, warnings: [] };
+}
+/** Serialize fresh max-merge and atomic replacement across every managed writer. */
+export function updateCounters(devstepsDir, counters) {
+    const proposed = validateCounters(counters);
+    const context = acquireCounterLock(devstepsDir);
+    let result;
+    let failure;
+    try {
+        result = mergeCountersHeld(devstepsDir, proposed, context);
+    }
+    catch (error) {
+        failure = error;
+    }
+    try {
+        const warnings = releaseCounterLock(context, devstepsDir);
+        if (result)
+            result.warnings.push(...warnings);
+    }
+    catch (error) {
+        if (error instanceof CounterLockError)
+            error.countersPersisted = result !== undefined;
+        if (failure === undefined)
+            failure = error;
+        else
+            failure = new AggregateError([failure, error], 'Counter persistence and ownership release both failed');
+    }
+    if (failure !== undefined)
+        throw failure;
+    if (!result)
+        throw new Error('Counter update returned no result');
+    return result;
+}
+/** Initialization participates in the same monotonic protocol, including existing stores. */
+export function initializeCounters(devstepsDir, initial = {}) {
+    return updateCounters(devstepsDir, initial);
+}
+export class ItemReservationError extends Error {
+    code = 'ITEM_RESERVATION_FAILED';
+    reservation;
+    constructor(cause, reservation) {
+        super(`Item reservation failed during ${reservation.phase}: ${cause instanceof Error ? cause.message : String(cause)}. Actual claimed IDs remain reserved; inspect them before retrying.`, { cause });
+        this.name = 'ItemReservationError';
+        this.reservation = reservation;
+    }
+}
+function assertReservationRequests(requests) {
+    if (!Array.isArray(requests) || requests.length < 1 || requests.length > 50)
+        throw new Error('Reservation requires 1 to 50 requests');
+    const seen = new Set();
+    for (const request of requests) {
+        if (!request ||
+            typeof request.key !== 'string' ||
+            !/^[a-z][A-Za-z0-9_-]{0,63}$/.test(request.key) ||
+            seen.has(request.key))
+            throw new Error('Reservation keys must be unique valid local keys');
+        ItemType.parse(request.type);
+        seen.add(request.key);
+    }
+}
+function claimReservationRequests(devstepsDir, requests, context, claims, maxima, onKey) {
+    for (const request of requests) {
+        onKey(request.key);
+        assertCounterLockHeld(context, devstepsDir);
+        assertCounterFileSafe(devstepsDir);
+        const prefix = getTypePrefix(request.type);
+        const from = Math.max(loadCounters(devstepsDir)[prefix] ?? 0, highestIdOnDisk(devstepsDir, request.type), maxima[prefix] ?? 0);
+        assertCounterLockHeld(context, devstepsDir);
+        const claim = claimItemFolder(devstepsDir, request.type, from);
+        claims.set(request.key, claim);
+        maxima[prefix] = Math.max(maxima[prefix] ?? 0, claim.number);
+    }
+}
+/** Fresh floors → actual claims → confirmed counter reservation, in one synchronous lease. */
+export function reserveItemFolders(devstepsDir, requests) {
+    assertReservationRequests(requests);
+    const claims = new Map();
+    const maxima = {};
+    let context;
+    let phase = 'claim';
+    let failedKey;
+    let countersPersisted = false;
+    let countersRaised = false;
+    let failure;
+    let lock;
+    const warnings = [];
+    const persist = () => {
+        if (!context)
+            throw new Error('Reservation has no counter ownership');
+        const result = mergeCountersHeld(devstepsDir, maxima, context);
+        countersPersisted = true;
+        countersRaised = result.changed;
+    };
+    try {
+        context = acquireCounterLock(devstepsDir);
+        claimReservationRequests(devstepsDir, requests, context, claims, maxima, (key) => {
+            failedKey = key;
+        });
+        phase = 'counters';
+        failedKey = undefined;
+        persist();
+    }
+    catch (error) {
+        failure = error;
+        if (error instanceof CounterLockError)
+            lock = error.lock;
+        if (context && claims.size > 0 && phase === 'claim') {
+            try {
+                persist();
+            }
+            catch (persistError) {
+                if (persistError instanceof CounterLockError)
+                    lock = persistError.lock;
+                failure = new AggregateError([error, persistError], 'Claim failed and claimed maxima could not be confirmed persisted');
+            }
+        }
+    }
+    if (context) {
+        try {
+            warnings.push(...releaseCounterLock(context, devstepsDir));
+        }
+        catch (error) {
+            if (error instanceof CounterLockError)
+                lock = error.lock;
+            if (failure === undefined) {
+                phase = 'release';
+                failure = error;
+            }
+            else
+                failure = new AggregateError([failure, error], 'Reservation and ownership release both failed');
+        }
+    }
+    const keyToId = Object.fromEntries([...claims].map(([key, claim]) => [key, claim.itemId]));
+    if (failure !== undefined && warnings.length > 0) {
+        lock ??= counterLockStatus(devstepsDir);
+        lock.issues = [...lock.issues, ...warnings].slice(0, 4);
+    }
+    if (failure !== undefined)
+        throw new ItemReservationError(failure, {
+            phase,
+            keyToId,
+            reservedKeys: [...claims.keys()],
+            ...(failedKey !== undefined ? { failedKey } : {}),
+            countersPersisted,
+            ...(lock !== undefined ? { lock } : {}),
+        });
+    return { claims, keyToId, countersRaised, warnings };
+}
+/** Highest ID number of one type on disk — live items and archived ones. */
+export function highestIdOnDisk(devstepsDir, type) {
+    let highest = 0;
+    for (const dir of [typeDirectory(devstepsDir, type), archivedTypeDirectory(devstepsDir, type)]) {
+        for (const id of listItemFolders(dir, type)) {
+            const number = parseItemId(id)?.number ?? 0;
+            if (number > highest)
+                highest = number;
+        }
+    }
+    return highest;
+}
+/** The counters file as the items on disk imply it — per type prefix, types without items left out. */
+export function deriveCounters(devstepsDir) {
+    const counters = {};
+    for (const type of Object.keys(TYPE_TO_DIRECTORY)) {
+        const highest = highestIdOnDisk(devstepsDir, type);
+        if (highest > 0)
+            counters[getTypePrefix(type)] = highest;
+    }
+    return counters;
+}
+//# sourceMappingURL=counters.js.map

package/dist/core/counters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"counters.js","sourceRoot":"","sources":["../../src/core/counters.ts"],"names":[],"mappings":"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"}

package/dist/core/dashboard-insights.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Dashboard insights projection: open work items over time, epic progress and recent activity.
+ *
+ * The open series is honest about its approximation. An item counts as open at the end of day D
+ * when it was created by then and was not closed by then; the close date is the `updated` of a
+ * closed item (done, obsolete, cancelled), because items carry no completion stamp. A closed item
+ * whose `updated` predates its `created` was never open. Only work types count: doc, decision and
+ * question items do not close in that sense. Days are UTC days, and the window ends today.
+ *
+ * Archived work items take part in the series and the epic table: they were real work, and
+ * leaving them out would lower the past curve and the closed counts. Archiving takes an item out
+ * of the project, so an archived item counts as closed at its `updated` whatever its status.
+ * Recent activity shows active items only, as the search does (DEC-012).
+ *
+ * @see STORY-365 TASK-848
+ */
+import { ItemMetadata, type ItemStatus, type ItemType } from '../schemas/index.js';
+import { type Bounded, type DashboardItem, type DashboardItems, type DashboardModelOptions } from './dashboard-model.js';
+/** Daily points of the open series: twelve weeks. */
+export declare const OPEN_SERIES_DAYS = 84;
+/** Rows of the recent-activity list. */
+export declare const DASHBOARD_ACTIVITY_LIMIT = 20;
+/** Rows of the epic table. */
+export declare const DASHBOARD_EPIC_LIMIT = 200;
+/** The types the open series and the epic table count. */
+export declare const DASHBOARD_WORK_TYPES: readonly ItemType[];
+export interface OpenSeriesPoint {
+    /** UTC day, `YYYY-MM-DD`; `open` is the count at its end. */
+    date: string;
+    open: number;
+}
+export interface OpenSummary {
+    /** Open at the start of the window. */
+    from: number;
+    /** Open at the end of the window; always `from + opened - closed`. */
+    to: number;
+    opened: number;
+    closed: number;
+    weeks: number;
+}
+export interface WeeklyOpenRow {
+    week_start: string;
+    opened: number;
+    closed: number;
+    open_end: number;
+}
+export interface EpicProgressRow {
+    id: string;
+    title: string;
+    status: ItemStatus;
+    /** Direct children (work types that `implements` the epic) not closed. */
+    open: number;
+    /** Direct children with status done; obsolete and cancelled children count in neither. */
+    done: number;
+    /** `open + done`, the denominator of the progress bar. */
+    total: number;
+}
+export interface DashboardInsights {
+    generated_at: string;
+    /** `OPEN_SERIES_DAYS` daily points, oldest first. */
+    open_series: OpenSeriesPoint[];
+    open_summary: OpenSummary;
+    weekly: WeeklyOpenRow[];
+    /** Most open children first, then by ID. */
+    epics: Bounded<EpicProgressRow>;
+    /** Latest updates of any type, active items only. */
+    activity: Bounded<DashboardItem>;
+    unreadable: string[];
+}
+/** Archived work items, every one marked closed; IDs that do not parse go to `unreadable`. */
+export interface ArchivedWorkItems {
+    items: ItemMetadata[];
+    unreadable: string[];
+}
+/** Start of the UTC day that holds `ms`. */
+export declare function utcDayStart(ms: number): number;
+interface OpenProjection {
+    open_series: OpenSeriesPoint[];
+    open_summary: OpenSummary;
+    weekly: WeeklyOpenRow[];
+}
+/** The open series, its summary and its weekly table over `days` UTC days ending today. */
+export declare function projectOpenSeries(items: readonly ItemMetadata[], nowMs: number, days?: number): OpenProjection;
+/**
+ * Per-epic counts of direct children; one pass over the items. Rows come from the active epics,
+ * children from the active items plus `archivedChildren`.
+ */
+export declare function projectEpicProgress(items: readonly ItemMetadata[], archivedChildren?: readonly ItemMetadata[]): EpicProgressRow[];
+/**
+ * Read the archived work items. The archive is outside the item store and small, so it is read
+ * from disk on each call. A closed status keeps its meaning; any other counts as closed.
+ */
+export declare function readArchivedWorkItems(devstepsDir: string): ArchivedWorkItems;
+/** Project Insights from item metadata; pure, so tests need no disk. */
+export declare function projectDashboardInsights(source: DashboardItems, opts?: DashboardModelOptions, archived?: ArchivedWorkItems): DashboardInsights;
+export declare function buildDashboardInsights(devstepsDir: string, opts?: DashboardModelOptions): DashboardInsights;
+export {};
+//# sourceMappingURL=dashboard-insights.d.ts.map

package/dist/core/dashboard-insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-insights.d.ts","sourceRoot":"","sources":["../../src/core/dashboard-insights.ts"],"names":[],"mappings":"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"}

package/dist/core/dashboard-insights.js

@@ -0,0 +1,175 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Dashboard insights projection: open work items over time, epic progress and recent activity.
+ *
+ * The open series is honest about its approximation. An item counts as open at the end of day D
+ * when it was created by then and was not closed by then; the close date is the `updated` of a
+ * closed item (done, obsolete, cancelled), because items carry no completion stamp. A closed item
+ * whose `updated` predates its `created` was never open. Only work types count: doc, decision and
+ * question items do not close in that sense. Days are UTC days, and the window ends today.
+ *
+ * Archived work items take part in the series and the epic table: they were real work, and
+ * leaving them out would lower the past curve and the closed counts. Archiving takes an item out
+ * of the project, so an archived item counts as closed at its `updated` whatever its status.
+ * Recent activity shows active items only, as the search does (DEC-012).
+ *
+ * @see STORY-365 TASK-848
+ */
+import { ItemMetadata } from '../schemas/index.js';
+import { readTextFile } from '../utils/text-file.js';
+import { boundedRows, DAY_MS, isClosedStatus, newestFirst, readDashboardItems, } from './dashboard-model.js';
+import { archivedItemPaths, archivedTypeDirectory, listItemFolders } from './item-paths.js';
+/** Daily points of the open series: twelve weeks. */
+export const OPEN_SERIES_DAYS = 84;
+/** Rows of the recent-activity list. */
+export const DASHBOARD_ACTIVITY_LIMIT = 20;
+/** Rows of the epic table. */
+export const DASHBOARD_EPIC_LIMIT = 200;
+/** The types the open series and the epic table count. */
+export const DASHBOARD_WORK_TYPES = [
+    'epic',
+    'story',
+    'task',
+    'requirement',
+    'feature',
+    'bug',
+    'spike',
+    'test',
+];
+const isWorkType = (item) => DASHBOARD_WORK_TYPES.includes(item.type);
+const ARCHIVED_STATUS = 'obsolete';
+const dayLabel = (ms) => new Date(ms).toISOString().slice(0, 10);
+/** Start of the UTC day that holds `ms`. */
+export function utcDayStart(ms) {
+    return Math.floor(ms / DAY_MS) * DAY_MS;
+}
+/** The open series, its summary and its weekly table over `days` UTC days ending today. */
+export function projectOpenSeries(items, nowMs, days = OPEN_SERIES_DAYS) {
+    const windowEnd = utcDayStart(nowMs) + DAY_MS;
+    const windowStart = windowEnd - days * DAY_MS;
+    const opened = new Array(days).fill(0);
+    const closed = new Array(days).fill(0);
+    const dayOf = (ms) => Math.floor((ms - windowStart) / DAY_MS);
+    let from = 0;
+    for (const item of items) {
+        if (!isWorkType(item))
+            continue;
+        const createdMs = Date.parse(item.created);
+        const closedMs = isClosedStatus(item.status) ? Date.parse(item.updated) : Infinity;
+        if (closedMs < createdMs || createdMs >= windowEnd)
+            continue;
+        if (createdMs < windowStart) {
+            if (closedMs >= windowStart)
+                from += 1;
+        }
+        else {
+            opened[dayOf(createdMs)] += 1;
+        }
+        if (closedMs >= windowStart && closedMs < windowEnd)
+            closed[dayOf(closedMs)] += 1;
+    }
+    const series = [];
+    let open = from;
+    for (let day = 0; day < days; day++) {
+        open += opened[day] - closed[day];
+        series.push({ date: dayLabel(windowStart + day * DAY_MS), open });
+    }
+    const weekly = [];
+    for (let start = 0; start < days; start += 7) {
+        const end = Math.min(start + 7, days);
+        const sum = (counts) => counts.slice(start, end).reduce((a, b) => a + b, 0);
+        weekly.push({
+            week_start: series[start].date,
+            opened: sum(opened),
+            closed: sum(closed),
+            open_end: series[end - 1].open,
+        });
+    }
+    const total = (counts) => counts.reduce((a, b) => a + b, 0);
+    return {
+        open_series: series,
+        open_summary: {
+            from,
+            to: open,
+            opened: total(opened),
+            closed: total(closed),
+            weeks: Math.ceil(days / 7),
+        },
+        weekly,
+    };
+}
+/**
+ * Per-epic counts of direct children; one pass over the items. Rows come from the active epics,
+ * children from the active items plus `archivedChildren`.
+ */
+export function projectEpicProgress(items, archivedChildren = []) {
+    const rows = new Map();
+    for (const item of items) {
+        if (item.type === 'epic') {
+            rows.set(item.id, {
+                id: item.id,
+                title: item.title,
+                status: item.status,
+                open: 0,
+                done: 0,
+                total: 0,
+            });
+        }
+    }
+    for (const item of [...items, ...archivedChildren]) {
+        if (!isWorkType(item))
+            continue;
+        for (const parent of new Set(item.linked_items.implements)) {
+            const row = rows.get(parent);
+            if (!row)
+                continue;
+            if (item.status === 'done')
+                row.done += 1;
+            else if (!isClosedStatus(item.status))
+                row.open += 1;
+            row.total = row.open + row.done;
+        }
+    }
+    return [...rows.values()].sort((a, b) => b.open - a.open || a.id.localeCompare(b.id, 'en', { numeric: true }));
+}
+/**
+ * Read the archived work items. The archive is outside the item store and small, so it is read
+ * from disk on each call. A closed status keeps its meaning; any other counts as closed.
+ */
+export function readArchivedWorkItems(devstepsDir) {
+    const items = [];
+    const unreadable = [];
+    for (const type of DASHBOARD_WORK_TYPES) {
+        for (const id of listItemFolders(archivedTypeDirectory(devstepsDir, type), type)) {
+            try {
+                const metadata = ItemMetadata.parse(JSON.parse(readTextFile(archivedItemPaths(devstepsDir, id).metadata)));
+                const closed = isClosedStatus(metadata.status);
+                items.push(closed ? metadata : { ...metadata, status: ARCHIVED_STATUS });
+            }
+            catch {
+                unreadable.push(id);
+            }
+        }
+    }
+    return { items, unreadable };
+}
+/** Project Insights from item metadata; pure, so tests need no disk. */
+export function projectDashboardInsights(source, opts = {}, archived = { items: [], unreadable: [] }) {
+    const now = opts.now ?? new Date();
+    const nowMs = now.getTime();
+    const epics = projectEpicProgress(source.items, archived.items);
+    const latest = [...source.items].sort(newestFirst);
+    return {
+        generated_at: now.toISOString(),
+        ...projectOpenSeries([...source.items, ...archived.items], nowMs),
+        epics: { total: epics.length, items: epics.slice(0, DASHBOARD_EPIC_LIMIT) },
+        activity: boundedRows(latest, DASHBOARD_ACTIVITY_LIMIT, nowMs),
+        unreadable: [...source.unreadable, ...archived.unreadable],
+    };
+}
+export function buildDashboardInsights(devstepsDir, opts = {}) {
+    return projectDashboardInsights(readDashboardItems(devstepsDir), opts, readArchivedWorkItems(devstepsDir));
+}
+//# sourceMappingURL=dashboard-insights.js.map

package/dist/core/dashboard-insights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-insights.js","sourceRoot":"","sources":["../../src/core/dashboard-insights.ts"],"names":[],"mappings":"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"}

package/dist/core/dashboard-model.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Dashboard overview projection: what the dashboard's Overview tab, its trace search and its
+ * agent handoff read, computed in one pass over the item store.
+ *
+ * `listItems` carries neither `created` nor `affected_paths`, and widening it would raise the
+ * cost of every MCP `list` answer, so the dashboard reads `readAllItemMetadata` itself. The board
+ * lanes follow `getBoard` exactly: tag membership, store order and `WIP_LIMIT`; a test holds the
+ * two together. Every list is bounded: `total` is the true count and `items` holds at most the
+ * limit, so a project of 10K items never reaches the webview whole.
+ *
+ * @see STORY-365 TASK-846 STORY-422
+ */
+import type { EisenhowerQuadrant, ItemMetadata, ItemStatus, ItemType } from '../schemas/index.js';
+/** Rows per live list (in progress, blocked, stale, delivered, lanes). */
+export declare const DASHBOARD_LIST_LIMIT = 50;
+/** Rows per Next-up quadrant. */
+export declare const DASHBOARD_NEXT_UP_LIMIT = 100;
+/** Hits the trace search returns. */
+export declare const DASHBOARD_TRACE_HIT_LIMIT = 30;
+/** Affected paths a row carries; the rest is counted in `affected_paths_total`. */
+export declare const DASHBOARD_PATH_LIMIT = 2;
+export declare const DAY_MS: number;
+/** A count that is always true, and the first items of what it counts. */
+export interface Bounded<T> {
+    total: number;
+    items: T[];
+}
+export interface DashboardItem {
+    id: string;
+    type: ItemType;
+    title: string;
+    status: ItemStatus;
+    eisenhower: EisenhowerQuadrant;
+    updated: string;
+    days_since_update: number;
+    /** The first `DASHBOARD_PATH_LIMIT` affected paths. */
+    affected_paths: string[];
+    affected_paths_total: number;
+}
+export type QuadrantKey = 'Q1' | 'Q2' | 'Q3' | 'Q4';
+export declare const QUADRANT_OF: Record<EisenhowerQuadrant, QuadrantKey>;
+export interface DashboardOverview {
+    generated_at: string;
+    pulse: {
+        in_progress: number;
+        blocked: number;
+        stale: number;
+        delivered_7d: number;
+        wip: {
+            now: number;
+            limit: number;
+            violated: boolean;
+        };
+    };
+    in_progress: Bounded<DashboardItem>;
+    blocked: Bounded<DashboardItem>;
+    /** In-progress items untouched for longer than `STALE_AFTER_DAYS`, the oldest first. */
+    stale: Bounded<DashboardItem>;
+    delivered_7d: Bounded<DashboardItem>;
+    /** The focus board in `getBoard` order. */
+    lanes: {
+        now: Bounded<DashboardItem>;
+        next: Bounded<DashboardItem>;
+        later_count: number;
+    };
+    /** Open stories (draft, planned, review) by Eisenhower quadrant, newest update first. */
+    next_up: Record<QuadrantKey, Bounded<DashboardItem>>;
+    /** IDs whose metadata could not be read; they are counted nowhere else. */
+    unreadable: string[];
+}
+export interface DashboardModelOptions {
+    now?: Date;
+    listLimit?: number;
+    nextUpLimit?: number;
+}
+/** What every dashboard projection starts from: the metadata of every readable item. */
+export interface DashboardItems {
+    items: ItemMetadata[];
+    unreadable: string[];
+}
+/** Read the store once for the dashboard projections. */
+export declare function readDashboardItems(devstepsDir: string): DashboardItems;
+export declare function isClosedStatus(status: string): boolean;
+export declare function toDashboardItem(metadata: ItemMetadata, nowMs: number): DashboardItem;
+export declare const newestFirst: (a: ItemMetadata, b: ItemMetadata) => number;
+/** The first `limit` items as dashboard rows, with the true total. */
+export declare function boundedRows(items: readonly ItemMetadata[], limit: number, nowMs: number): Bounded<DashboardItem>;
+/** Project the Overview from item metadata; pure, so tests need no disk. */
+export declare function projectDashboardOverview(source: DashboardItems, opts?: DashboardModelOptions): DashboardOverview;
+export declare function buildDashboardOverview(devstepsDir: string, opts?: DashboardModelOptions): DashboardOverview;
+/**
+ * Trace-search hits: the exact ID first, then ID-prefix matches in ID order, then items whose
+ * ID and title together hold every query word ("STORY-365 dashboard"), newest update first. Every active item takes part, whatever its
+ * status; archived items are outside the store and outside the search (DEC-012).
+ */
+export declare function searchDashboardItems(items: readonly ItemMetadata[], query: string, limit?: number, nowMs?: number): DashboardItem[];
+export declare function findDashboardItems(devstepsDir: string, query: string, limit?: number): DashboardItem[];
+/**
+ * IDs of the focus:now lane in board order. Work-the-board reads them at click time, so the
+ * prompt never trusts a list the webview sent.
+ */
+export declare function nowLaneIds(devstepsDir: string): string[];
+//# sourceMappingURL=dashboard-model.d.ts.map