@cleocode/core 2026.9.20 → 2026.9.22

package/dist/nexus/assessment-projection.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Bounded status projection of the published graph assessment (T12560).
+ *
+ * `cleo nexus status` used to emit `assessment.files` whole: one row per
+ * assessed file at ~635 B each, so the envelope grew with the repository —
+ * 3.9 MB on this one, and 391 MB for one reporter. The status call is the one
+ * every agent is told to make FIRST, so its size must not depend on how many
+ * files exist.
+ *
+ * The projection keeps the counts (`fileCount`, `filesByStatus`) and one page
+ * of rows (`filesPage`, 20 by default). The complete list is returned under
+ * `files` only when every row is explicitly requested; otherwise it is named
+ * in `_withheld` with its UTF-8 JSON size, following the MVI projection rule
+ * that a partial copy is never placed under the real field name.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @task T12560
+ * @module nexus/assessment-projection
+ */
+import { type GraphIndexAssessment, type GraphIndexAssessmentProjection, type GraphIndexFileStatus } from '@cleocode/contracts';
+/** Rows in the default page of `assessment.filesPage`. */
+export declare const DEFAULT_ASSESSMENT_FILE_PAGE_SIZE = 20;
+/** Every file processing outcome, in report order. */
+export declare const GRAPH_INDEX_FILE_STATUSES: readonly GraphIndexFileStatus[];
+/** Which file rows a status projection returns. */
+export interface AssessmentFilesRequest {
+    /** Return every row under `files`; paging options narrow it back to a page. */
+    all?: boolean;
+    /** Page size; `0` requests every remaining row. Defaults to {@link DEFAULT_ASSESSMENT_FILE_PAGE_SIZE}. */
+    limit?: number;
+    /** Rows to skip before the page. Defaults to 0. */
+    offset?: number;
+    /** Page only rows with this status. */
+    status?: GraphIndexFileStatus;
+}
+/** Raw CLI flag values accepted by {@link parseAssessmentFilesRequest}. */
+export interface AssessmentFilesFlags {
+    /** `--files`. */
+    files?: boolean;
+    /** `--limit`. */
+    limit?: string;
+    /** `--offset`. */
+    offset?: string;
+    /** `--file-status`. */
+    fileStatus?: string;
+}
+/**
+ * Validate `cleo nexus status` file-paging flags.
+ * @param flags - Raw flag values as the CLI received them.
+ * @returns The validated request.
+ * @throws CleoError with `INVALID_INPUT` for a malformed count or unknown status.
+ * @example
+ * ```ts
+ * parseAssessmentFilesRequest({ limit: '50', offset: '100', fileStatus: 'failed' });
+ * ```
+ */
+export declare function parseAssessmentFilesRequest(flags: AssessmentFilesFlags): AssessmentFilesRequest;
+/**
+ * Project an assessment for `cleo nexus status`: counts plus one page of file rows.
+ *
+ * `files` is returned whole only for `{ all: true }` (or `limit: 0`) with no
+ * offset or status filter. Every other request returns `filesPage` and names
+ * `files` in `_withheld` with the full list's UTF-8 JSON size, so a consumer
+ * never mistakes a page for the complete list.
+ * @param assessment - The published assessment summary.
+ * @param request - Which rows to return; the default is the first 20.
+ * @returns The bounded projection.
+ * @example
+ * ```ts
+ * const status = projectAssessmentFiles(assessment);
+ * status.filesByStatus.failed; // gaps, without loading the list into the envelope
+ * ```
+ */
+export declare function projectAssessmentFiles(assessment: GraphIndexAssessment, request?: AssessmentFilesRequest): GraphIndexAssessmentProjection;
+//# sourceMappingURL=assessment-projection.d.ts.map

package/dist/nexus/assessment-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment-projection.d.ts","sourceRoot":"","sources":["../../src/nexus/assessment-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,8BAA8B,EAGnC,KAAK,oBAAoB,EAE1B,MAAM,qBAAqB,CAAC;AAG7B,0DAA0D;AAC1D,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,EAAE,SAAS,oBAAoB,EAMpE,CAAC;AAEF,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,0GAA0G;IAC1G,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,iBAAiB;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,oBAAoB,GAAG,sBAAsB,CAmB/F;AA+CD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,sBAA2B,GACnC,8BAA8B,CAYhC"}

package/dist/nexus/assessment-projection.js

@@ -0,0 +1,143 @@
+/**
+ * Bounded status projection of the published graph assessment (T12560).
+ *
+ * `cleo nexus status` used to emit `assessment.files` whole: one row per
+ * assessed file at ~635 B each, so the envelope grew with the repository —
+ * 3.9 MB on this one, and 391 MB for one reporter. The status call is the one
+ * every agent is told to make FIRST, so its size must not depend on how many
+ * files exist.
+ *
+ * The projection keeps the counts (`fileCount`, `filesByStatus`) and one page
+ * of rows (`filesPage`, 20 by default). The complete list is returned under
+ * `files` only when every row is explicitly requested; otherwise it is named
+ * in `_withheld` with its UTF-8 JSON size, following the MVI projection rule
+ * that a partial copy is never placed under the real field name.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @task T12560
+ * @module nexus/assessment-projection
+ */
+import { ExitCode, } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+/** Rows in the default page of `assessment.filesPage`. */
+export const DEFAULT_ASSESSMENT_FILE_PAGE_SIZE = 20;
+/** Every file processing outcome, in report order. */
+export const GRAPH_INDEX_FILE_STATUSES = [
+    'analyzed',
+    'excluded',
+    'unsupported',
+    'oversized',
+    'failed',
+];
+/**
+ * Parse one non-negative integer flag, rejecting partial parses such as `10x`.
+ * @internal
+ */
+function parseCount(flag, value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value.trim()))
+        throw new CleoError(ExitCode.INVALID_INPUT, `--${flag} must be a non-negative integer`, {
+            fix: `cleo nexus status --${flag} <n>`,
+            details: { field: flag, actual: value },
+        });
+    return Number(value.trim());
+}
+/**
+ * Validate `cleo nexus status` file-paging flags.
+ * @param flags - Raw flag values as the CLI received them.
+ * @returns The validated request.
+ * @throws CleoError with `INVALID_INPUT` for a malformed count or unknown status.
+ * @example
+ * ```ts
+ * parseAssessmentFilesRequest({ limit: '50', offset: '100', fileStatus: 'failed' });
+ * ```
+ */
+export function parseAssessmentFilesRequest(flags) {
+    const status = flags.fileStatus?.trim();
+    if (status !== undefined && !GRAPH_INDEX_FILE_STATUSES.some((known) => known === status))
+        throw new CleoError(ExitCode.INVALID_INPUT, `--file-status must be one of ${GRAPH_INDEX_FILE_STATUSES.join(', ')}`, {
+            fix: 'cleo nexus status --file-status failed',
+            details: { field: 'file-status', actual: status },
+        });
+    return {
+        ...(flags.files ? { all: true } : {}),
+        ...(flags.limit === undefined ? {} : { limit: parseCount('limit', flags.limit) }),
+        ...(flags.offset === undefined ? {} : { offset: parseCount('offset', flags.offset) }),
+        ...(status === undefined
+            ? {}
+            : { status: GRAPH_INDEX_FILE_STATUSES.find((known) => known === status) }),
+    };
+}
+/**
+ * UTF-8 size of `JSON.stringify(rows)`, summed row by row so a list of
+ * hundreds of MB is never serialized as one string.
+ * @internal
+ */
+function jsonArrayBytes(rows) {
+    let bytes = 2 + Math.max(rows.length - 1, 0);
+    for (const row of rows)
+        bytes += Buffer.byteLength(JSON.stringify(row), 'utf8');
+    return bytes;
+}
+/** @internal */
+function countByStatus(rows) {
+    const counts = {
+        analyzed: 0,
+        excluded: 0,
+        unsupported: 0,
+        oversized: 0,
+        failed: 0,
+    };
+    for (const row of rows)
+        counts[row.status] += 1;
+    return counts;
+}
+/** @internal */
+function pageFiles(rows, request) {
+    const matching = request.status ? rows.filter((row) => row.status === request.status) : rows;
+    const offset = request.offset ?? 0;
+    const size = request.limit ?? (request.all ? 0 : DEFAULT_ASSESSMENT_FILE_PAGE_SIZE);
+    const end = size === 0 ? matching.length : Math.min(offset + size, matching.length);
+    const page = matching.slice(offset, end);
+    return {
+        offset,
+        limit: size === 0 ? null : size,
+        ...(request.status ? { status: request.status } : {}),
+        total: matching.length,
+        returned: page.length,
+        nextOffset: end < matching.length ? end : null,
+        rows: page,
+    };
+}
+/**
+ * Project an assessment for `cleo nexus status`: counts plus one page of file rows.
+ *
+ * `files` is returned whole only for `{ all: true }` (or `limit: 0`) with no
+ * offset or status filter. Every other request returns `filesPage` and names
+ * `files` in `_withheld` with the full list's UTF-8 JSON size, so a consumer
+ * never mistakes a page for the complete list.
+ * @param assessment - The published assessment summary.
+ * @param request - Which rows to return; the default is the first 20.
+ * @returns The bounded projection.
+ * @example
+ * ```ts
+ * const status = projectAssessmentFiles(assessment);
+ * status.filesByStatus.failed; // gaps, without loading the list into the envelope
+ * ```
+ */
+export function projectAssessmentFiles(assessment, request = {}) {
+    const { files, ...rest } = assessment;
+    const summary = { fileCount: files.length, filesByStatus: countByStatus(files) };
+    const complete = (request.all === true || request.limit === 0) && !request.offset && !request.status;
+    if (complete)
+        return { ...rest, ...summary, files };
+    return {
+        _withheld: { files: jsonArrayBytes(files) },
+        ...rest,
+        ...summary,
+        filesPage: pageFiles(files, request),
+    };
+}
+//# sourceMappingURL=assessment-projection.js.map

package/dist/nexus/assessment-projection.js.map

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

package/dist/nexus/assessment-store.d.ts

@@ -78,9 +78,21 @@ export declare function assessmentSummary(assessment: GraphIndexAssessment): Gra
  *   the stored list of that same generation.
  * - An assessment with neither removes any stale list.
  *
+ * Root paths are stored relative to the recorded project root (T12474); read
+ * them back through `readKnowledgeIndexAssessment`, which resolves them
+ * against the live project root.
+ *
  * @param tx - Graph database handle or open transaction.
- * @param assessment - Assessment to persist.
- * @returns The summary as written.
+ * @param assessment - Assessment to persist, with absolute in-memory paths.
+ * @returns The summary written, in its in-memory (absolute-path) form.
  */
 export declare function writeAssessment(tx: Pick<NodeSQLiteDatabase, 'run'>, assessment: GraphIndexAssessment): GraphIndexAssessment;
+/**
+ * Whether the stored assessment still holds absolute root paths — the form
+ * written before T12474. Extracts only the two root fields.
+ *
+ * @param db - Graph database handle.
+ * @returns `true` when a legacy absolute record should be rewritten portably.
+ */
+export declare function storedAssessmentHasAbsoluteRoots(db: Pick<NodeSQLiteDatabase, 'values'>): boolean;
 //# sourceMappingURL=assessment-store.d.ts.map

package/dist/nexus/assessment-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assessment-store.d.ts","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,mDAAmD;AACnD,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAKvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAC/C,UAAU,CAEZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,oBAAoB,CAIxF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACnC,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,CAWtB"}
+{"version":3,"file":"assessment-store.d.ts","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mDAAmD;AACnD,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAKvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAC/C,UAAU,CAEZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,oBAAoB,CAIxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACnC,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,CAWtB;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAMhG"}

package/dist/nexus/assessment-store.js

@@ -25,8 +25,10 @@
  * @task T12348
  * @module nexus/assessment-store
  */
+import { isAbsolute } from 'node:path';
 import { gunzipSync, gzipSync } from 'node:zlib';
 import { sql } from 'drizzle-orm';
+import { encodeStoredAssessment } from './stored-roots.js';
 /** `_nexus_meta` key of the assessment summary. */
 export const ASSESSMENT_KEY = 'graph_assessment';
 /** `_nexus_meta` key of the separately stored reference list. */
@@ -93,13 +95,17 @@ export function assessmentSummary(assessment) {
  *   the stored list of that same generation.
  * - An assessment with neither removes any stale list.
  *
+ * Root paths are stored relative to the recorded project root (T12474); read
+ * them back through `readKnowledgeIndexAssessment`, which resolves them
+ * against the live project root.
+ *
  * @param tx - Graph database handle or open transaction.
- * @param assessment - Assessment to persist.
- * @returns The summary as written.
+ * @param assessment - Assessment to persist, with absolute in-memory paths.
+ * @returns The summary written, in its in-memory (absolute-path) form.
  */
 export function writeAssessment(tx, assessment) {
     const summary = assessmentSummary(assessment);
-    tx.run(sql `INSERT INTO main._nexus_meta (key, value) VALUES (${ASSESSMENT_KEY}, ${JSON.stringify(summary)})
+    tx.run(sql `INSERT INTO main._nexus_meta (key, value) VALUES (${ASSESSMENT_KEY}, ${JSON.stringify(encodeStoredAssessment(summary))})
     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = strftime('%s', 'now')`);
     if (assessment.references !== undefined) {
         tx.run(sql `INSERT INTO main._nexus_meta (key, value) VALUES (${ASSESSMENT_REFERENCES_KEY}, ${encodeStoredReferences(assessment.references)})
@@ -110,4 +116,16 @@ export function writeAssessment(tx, assessment) {
     }
     return summary;
 }
+/**
+ * Whether the stored assessment still holds absolute root paths — the form
+ * written before T12474. Extracts only the two root fields.
+ *
+ * @param db - Graph database handle.
+ * @returns `true` when a legacy absolute record should be rewritten portably.
+ */
+export function storedAssessmentHasAbsoluteRoots(db) {
+    const row = db.values(sql `SELECT json_extract(value, '$.sourceRoot'), json_extract(value, '$.sourceRoots.projectRoot')
+      FROM main._nexus_meta WHERE key = ${ASSESSMENT_KEY}`)[0];
+    return (row ?? []).some((path) => typeof path === 'string' && isAbsolute(path));
+}
 //# sourceMappingURL=assessment-store.js.map

package/dist/nexus/assessment-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"assessment-store.js","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAGlC,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,2FAA2F;AAC3F,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAgD;IAEhD,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAgC;IAChE,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC3D,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC;IAC9C,OAAO,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAmC,EACnC,UAAgC;IAEhC,MAAM,OAAO,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC9C,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,cAAc,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;8FACb,CAAC,CAAC;IAC9F,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACxC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,yBAAyB,KAAK,sBAAsB,CAAC,UAAU,CAAC,UAAU,CAAC;gGAC9C,CAAC,CAAC;IAChG,CAAC;SAAM,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAChD,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,4CAA4C,yBAAyB,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"assessment-store.js","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,2FAA2F;AAC3F,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAgD;IAEhD,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAgC;IAChE,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC3D,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC;IAC9C,OAAO,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAmC,EACnC,UAAgC;IAEhC,MAAM,OAAO,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC9C,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,cAAc,KAAK,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;8FACrC,CAAC,CAAC;IAC9F,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACxC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,yBAAyB,KAAK,sBAAsB,CAAC,UAAU,CAAC,UAAU,CAAC;gGAC9C,CAAC,CAAC;IAChG,CAAC;SAAM,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAChD,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,4CAA4C,yBAAyB,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAAC,EAAsC;IACrF,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,CACnB,GAAG,CAAA;0CACmC,cAAc,EAAE,CACvD,CAAC,CAAC,CAAC,CAAC;IACL,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAClF,CAAC"}

package/dist/nexus/checkout-nonce.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-checkout nonce — the only evidence that proves a project MOVED
+ * (T12470 · ADR-094).
+ *
+ * `.cleo/project-id` is committed, so a clone, a fork or a hostile copy of the
+ * file declares a registered project's id. Git state is no better: a clone has
+ * the same root commit and remote, a bare `git init` can add any remote, and a
+ * root commit can be faked with `refs/replace`. What a clone can NOT have is
+ * local, untracked state. This module keeps a random nonce in the checkout's
+ * `.cleo/project-info.json` — never tracked (ADR-013 §9) — and the registry
+ * records it on each confirmed location. A real `mv`, or a restore of `.cleo/`
+ * from a backup, carries the nonce with it; a clone has none, or its own.
+ *
+ * @task T12470
+ * @module nexus/checkout-nonce
+ */
+/** `project-info.json` field that carries the nonce. */
+export declare const CHECKOUT_NONCE_FIELD = "checkoutNonce";
+/**
+ * Read the checkout's nonce.
+ *
+ * @param projectRoot - Checkout root (the directory containing `.cleo/`).
+ * @returns The nonce, or `null` when the checkout has none.
+ *
+ * @example
+ * ```ts
+ * const nonce = readCheckoutNonce(root);
+ * ```
+ */
+export declare function readCheckoutNonce(projectRoot: string): string | null;
+/**
+ * Return the checkout's nonce, minting one into `project-info.json` when the
+ * file exists and has none. Called only when a location is CONFIRMED, so a
+ * candidate never gains a nonce the registry would accept.
+ *
+ * Never creates `project-info.json`: a checkout without one (a fresh clone
+ * before `cleo init`) has no nonce, and its moves are confirmed explicitly.
+ *
+ * @param projectRoot - Checkout root.
+ * @returns The nonce, or `null` when there is no `project-info.json` to hold it.
+ *
+ * @example
+ * ```ts
+ * const nonce = ensureCheckoutNonce(root);
+ * ```
+ */
+export declare function ensureCheckoutNonce(projectRoot: string): string | null;
+//# sourceMappingURL=checkout-nonce.d.ts.map

package/dist/nexus/checkout-nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-nonce.d.ts","sourceRoot":"","sources":["../../src/nexus/checkout-nonce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,wDAAwD;AACxD,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAmBpD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWtE"}

package/dist/nexus/checkout-nonce.js

@@ -0,0 +1,84 @@
+/**
+ * Per-checkout nonce — the only evidence that proves a project MOVED
+ * (T12470 · ADR-094).
+ *
+ * `.cleo/project-id` is committed, so a clone, a fork or a hostile copy of the
+ * file declares a registered project's id. Git state is no better: a clone has
+ * the same root commit and remote, a bare `git init` can add any remote, and a
+ * root commit can be faked with `refs/replace`. What a clone can NOT have is
+ * local, untracked state. This module keeps a random nonce in the checkout's
+ * `.cleo/project-info.json` — never tracked (ADR-013 §9) — and the registry
+ * records it on each confirmed location. A real `mv`, or a restore of `.cleo/`
+ * from a backup, carries the nonce with it; a clone has none, or its own.
+ *
+ * @task T12470
+ * @module nexus/checkout-nonce
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** `project-info.json` field that carries the nonce. */
+export const CHECKOUT_NONCE_FIELD = 'checkoutNonce';
+/** Accepted nonce shape: 32 lowercase hex characters (128 random bits). */
+const NONCE_PATTERN = /^[0-9a-f]{32}$/;
+/** Parse `<root>/.cleo/project-info.json`; `null` when absent or unparseable. */
+function readInfo(projectRoot) {
+    const path = join(projectRoot, '.cleo', 'project-info.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the checkout's nonce.
+ *
+ * @param projectRoot - Checkout root (the directory containing `.cleo/`).
+ * @returns The nonce, or `null` when the checkout has none.
+ *
+ * @example
+ * ```ts
+ * const nonce = readCheckoutNonce(root);
+ * ```
+ */
+export function readCheckoutNonce(projectRoot) {
+    const value = readInfo(projectRoot)?.[CHECKOUT_NONCE_FIELD];
+    return typeof value === 'string' && NONCE_PATTERN.test(value) ? value : null;
+}
+/**
+ * Return the checkout's nonce, minting one into `project-info.json` when the
+ * file exists and has none. Called only when a location is CONFIRMED, so a
+ * candidate never gains a nonce the registry would accept.
+ *
+ * Never creates `project-info.json`: a checkout without one (a fresh clone
+ * before `cleo init`) has no nonce, and its moves are confirmed explicitly.
+ *
+ * @param projectRoot - Checkout root.
+ * @returns The nonce, or `null` when there is no `project-info.json` to hold it.
+ *
+ * @example
+ * ```ts
+ * const nonce = ensureCheckoutNonce(root);
+ * ```
+ */
+export function ensureCheckoutNonce(projectRoot) {
+    const existing = readCheckoutNonce(projectRoot);
+    if (existing)
+        return existing;
+    const info = readInfo(projectRoot);
+    if (!info)
+        return null;
+    const nonce = randomBytes(16).toString('hex');
+    const path = join(projectRoot, '.cleo', 'project-info.json');
+    const temp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
+    writeFileSync(temp, `${JSON.stringify({ ...info, [CHECKOUT_NONCE_FIELD]: nonce }, null, 2)}\n`);
+    renameSync(temp, path);
+    return nonce;
+}
+//# sourceMappingURL=checkout-nonce.js.map

package/dist/nexus/checkout-nonce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-nonce.js","sourceRoot":"","sources":["../../src/nexus/checkout-nonce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,wDAAwD;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAAG,eAAe,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAEvC,iFAAiF;AACjF,SAAS,QAAQ,CAAC,WAAmB;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAChE,OAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAC5E,CAAC,CAAE,MAAkC;YACrC,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC;IAC5D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAChD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;IAC7D,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,oBAAoB,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAChG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/nexus/devices.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Devices (`nexus_devices`) — every machine that runs CLEO against this
+ * global store, keyed by the stable `<cleoHome>/device-id` (T9321) that
+ * `nexus_project_locations.device_id` already carries (T12469). Resolving a
+ * location's device id against this table answers "which machine, which OS,
+ * which CLEO version, and when did it last check in".
+ *
+ * The CLI calls {@link recordDeviceHeartbeat} on start. It is throttled to at
+ * most one write per {@link DEVICE_HEARTBEAT_INTERVAL_MS} per device: one
+ * primary-key read decides, and only a stale or absent row costs a single
+ * primary-key upsert. The upsert repeats the staleness test in its `WHERE`, so
+ * concurrent CLI starts cannot both write inside one interval.
+ *
+ * @task T12510
+ * @epic T12496
+ */
+import type { NexusDeviceRecord } from '@cleocode/contracts';
+import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+/** Minimum interval between two heartbeat writes for one device. */
+export declare const DEVICE_HEARTBEAT_INTERVAL_MS = 60000;
+/** Registry handle subset the device functions need. */
+export type DeviceStoreHandle = Pick<NodeSQLiteDatabase, 'select' | 'insert'>;
+/** Descriptive facts about the device sending a heartbeat. */
+export interface DeviceFacts {
+    /** Stable device id. Defaults to {@link currentDeviceId}. */
+    deviceId?: string;
+    /** Hostname. Defaults to `os.hostname()`. */
+    hostname?: string;
+    /** OS. Defaults to `process.platform`. */
+    os?: string;
+    /** Architecture. Defaults to `process.arch`. */
+    arch?: string;
+    /** CLEO version. Defaults to the installed package version. */
+    cleoVersion?: string;
+}
+/** What {@link recordDeviceHeartbeat} did. */
+export type DeviceHeartbeatOutcome = 'written' | 'throttled';
+/**
+ * Upsert this device's `nexus_devices` row unless it was written within the
+ * last {@link DEVICE_HEARTBEAT_INTERVAL_MS}.
+ *
+ * Cost: one primary-key read; when stale, one primary-key upsert. Descriptive
+ * facts (hostname, version) are resolved only when a write happens.
+ *
+ * @param db - Global registry handle (`getNexusRegistryDb`).
+ * @param now - Heartbeat instant. Defaults to the current time.
+ * @param facts - Overrides for the recorded device facts (tests).
+ * @returns `written` when the row was inserted or refreshed, else `throttled`.
+ * @example
+ * ```ts
+ * await recordDeviceHeartbeat(await getNexusRegistryDb(getCleoHome()));
+ * ```
+ */
+export declare function recordDeviceHeartbeat(db: DeviceStoreHandle, now?: Date, facts?: DeviceFacts): Promise<DeviceHeartbeatOutcome>;
+/**
+ * List every known device, most recent heartbeat first.
+ *
+ * @param db - Global registry handle (`getNexusRegistryDb`).
+ * @returns Device records; `current` marks this device.
+ * @example
+ * ```ts
+ * const all = listNexusDevices(await getNexusRegistryDb(getCleoHome()));
+ * ```
+ */
+export declare function listNexusDevices(db: DeviceStoreHandle): NexusDeviceRecord[];
+/** Filename in `<cleoHome>` whose mtime records the last heartbeat attempt. */
+export declare const DEVICE_HEARTBEAT_STAMP = "device-heartbeat.stamp";
+/** What {@link heartbeatThisDevice} did. */
+export type DeviceStartupHeartbeatOutcome = DeviceHeartbeatOutcome | 'disabled' | 'shutting-down' | 'no-store';
+/**
+ * CLI-start heartbeat: record this device in the global store at most once
+ * per {@link DEVICE_HEARTBEAT_INTERVAL_MS}.
+ *
+ * A stamp file's mtime is checked first, so a start inside the interval costs
+ * one `stat` and never opens the database. Past the interval it opens the
+ * global registry (only if it already exists — a heartbeat never creates the
+ * store) and calls {@link recordDeviceHeartbeat}, whose own primary-key check
+ * and guarded upsert keep concurrent starts to a single write.
+ *
+ * Callers MUST treat every error as non-fatal; the CLI swallows it.
+ *
+ * @param options - `cleoHome` and `now` overrides (tests).
+ * @returns What happened.
+ * @example
+ * ```ts
+ * try { await heartbeatThisDevice(); } catch { // never fail the command }
+ * ```
+ */
+export declare function heartbeatThisDevice(options?: {
+    cleoHome?: string;
+    now?: Date;
+}): Promise<DeviceStartupHeartbeatOutcome>;
+//# sourceMappingURL=devices.d.ts.map

package/dist/nexus/devices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.d.ts","sourceRoot":"","sources":["../../src/nexus/devices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAKlE,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,kBAAkB,EAAE,QAAQ,GAAG,QAAQ,CAAC,CAAC;AAE9E,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8CAA8C;AAC9C,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,iBAAiB,EACrB,GAAG,GAAE,IAAiB,EACtB,KAAK,GAAE,WAAgB,GACtB,OAAO,CAAC,sBAAsB,CAAC,CA8BjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CAQ3E;AAED,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,4CAA4C;AAC5C,MAAM,MAAM,6BAA6B,GACrC,sBAAsB,GACtB,UAAU,GACV,eAAe,GACf,UAAU,CAAC;AAEf;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAC9C,OAAO,CAAC,6BAA6B,CAAC,CAiBxC"}