@cleocode/core 2026.6.12 → 2026.6.14

package/dist/deriver/queue-manager.d.ts

@@ -22,6 +22,18 @@ import type { DatabaseSync } from 'node:sqlite';
 export declare const STALE_CLAIM_MINUTES = 30;
 /** Max retry count before item is moved to 'failed' permanently. */
 export declare const MAX_RETRY_COUNT = 5;
+/**
+ * Base exponential-backoff delay in seconds for a re-queued item (T10405).
+ *
+ * A failed/recovered item's next claim is gated until
+ * `now + BACKOFF_BASE_SECONDS * 2^(retryCount - 1)`, capped at
+ * {@link BACKOFF_MAX_SECONDS}. With base 30s the schedule is
+ * 30s → 60s → 120s → 240s (then capped), so a transiently-failing item
+ * backs off geometrically instead of hot-looping the worker.
+ */
+export declare const BACKOFF_BASE_SECONDS = 30;
+/** Maximum exponential-backoff delay in seconds (cap for {@link computeBackoffSeconds}). */
+export declare const BACKOFF_MAX_SECONDS: number;
 /** Options for {@link claimNextItem}. */
 export interface ClaimOptions {
     /**
@@ -52,6 +64,20 @@ export interface StaleRecoveryResult {
     /** Number of items permanently failed due to max retries. */
     failed: number;
 }
+/**
+ * Compute the exponential-backoff delay (seconds) for a re-queued item (T10405).
+ *
+ * Returns `BACKOFF_BASE_SECONDS * 2^(attempt - 1)` capped at
+ * {@link BACKOFF_MAX_SECONDS}. `attempt` is the *new* retry count (1-based:
+ * the first failure backs off by the base delay). An `attempt` of 0 or less is
+ * clamped to 1 so the first retry always waits at least the base delay.
+ *
+ * @param attempt - The new (post-increment) retry count for the item.
+ * @returns Backoff delay in seconds, in `[BACKOFF_BASE_SECONDS, BACKOFF_MAX_SECONDS]`.
+ *
+ * @task T10405
+ */
+export declare function computeBackoffSeconds(attempt: number): number;
 /**
  * Claim the next pending item from the deriver queue.
  *
@@ -78,8 +104,10 @@ export declare function completeItem(itemId: string, options?: CompleteOptions):
  * Mark a claimed item as failed (with optional error message).
  *
  * If `retryCount` is below {@link MAX_RETRY_COUNT}, the item is re-queued
- * to `pending` with `retryCount + 1` (for retry next batch).
- * Otherwise the item is permanently moved to `failed`.
+ * to `pending` with `retryCount + 1` and an exponential-backoff
+ * `next_attempt_at` (T10405) so it is not re-claimed until the backoff window
+ * elapses. Otherwise the item is permanently moved to `failed` (DLQ semantics)
+ * and its backoff gate is cleared.
  *
  * @param itemId   - The deriver_queue.id to fail.
  * @param errorMsg - Human-readable error for the error_msg column.

package/dist/deriver/queue-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue-manager.d.ts","sourceRoot":"","sources":["../../src/deriver/queue-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,eAAe,IAAI,CAAC;AASjC,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,EAAE,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1B;AAED,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,EAAE,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAqCD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,YAAiB,GAAG,WAAW,GAAG,IAAI,CA2D5E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAYhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAsB9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,eAAoB,GAAG,mBAAmB,CA0CpF"}
+{"version":3,"file":"queue-manager.d.ts","sourceRoot":"","sources":["../../src/deriver/queue-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,oEAAoE;AACpE,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,QAAU,CAAC;AAS3C,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,EAAE,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1B;AAED,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,EAAE,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI7D;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,YAAiB,GAAG,WAAW,GAAG,IAAI,CA+D5E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAYhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CAyB9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,eAAoB,GAAG,mBAAmB,CA4CpF"}

package/dist/deriver/queue-manager.js

@@ -25,6 +25,18 @@ import { getBrainNativeDb } from '../store/memory-sqlite.js';
 export const STALE_CLAIM_MINUTES = 30;
 /** Max retry count before item is moved to 'failed' permanently. */
 export const MAX_RETRY_COUNT = 5;
+/**
+ * Base exponential-backoff delay in seconds for a re-queued item (T10405).
+ *
+ * A failed/recovered item's next claim is gated until
+ * `now + BACKOFF_BASE_SECONDS * 2^(retryCount - 1)`, capped at
+ * {@link BACKOFF_MAX_SECONDS}. With base 30s the schedule is
+ * 30s → 60s → 120s → 240s (then capped), so a transiently-failing item
+ * backs off geometrically instead of hot-looping the worker.
+ */
+export const BACKOFF_BASE_SECONDS = 30;
+/** Maximum exponential-backoff delay in seconds (cap for {@link computeBackoffSeconds}). */
+export const BACKOFF_MAX_SECONDS = 30 * 60;
 /** SQLite busy error string (returned when BEGIN IMMEDIATE cannot acquire lock). */
 const SQLITE_BUSY_STR = 'database is locked';
 // ============================================================================
@@ -38,6 +50,28 @@ function defaultWorkerId() {
 function minutesAgo(n) {
     return new Date(Date.now() - n * 60_000).toISOString();
 }
+/**
+ * Compute the exponential-backoff delay (seconds) for a re-queued item (T10405).
+ *
+ * Returns `BACKOFF_BASE_SECONDS * 2^(attempt - 1)` capped at
+ * {@link BACKOFF_MAX_SECONDS}. `attempt` is the *new* retry count (1-based:
+ * the first failure backs off by the base delay). An `attempt` of 0 or less is
+ * clamped to 1 so the first retry always waits at least the base delay.
+ *
+ * @param attempt - The new (post-increment) retry count for the item.
+ * @returns Backoff delay in seconds, in `[BACKOFF_BASE_SECONDS, BACKOFF_MAX_SECONDS]`.
+ *
+ * @task T10405
+ */
+export function computeBackoffSeconds(attempt) {
+    const safeAttempt = attempt < 1 ? 1 : attempt;
+    const delay = BACKOFF_BASE_SECONDS * 2 ** (safeAttempt - 1);
+    return Math.min(delay, BACKOFF_MAX_SECONDS);
+}
+/** Return ISO 8601 timestamp for N seconds in the future. */
+function secondsFromNow(n) {
+    return new Date(Date.now() + n * 1000).toISOString();
+}
 // ============================================================================
 // Public API
 // ============================================================================
@@ -70,18 +104,22 @@ export function claimNextItem(options = {}) {
         throw err;
     }
     try {
+        // T10405: gate on the exponential-backoff window — a re-queued item with a
+        // future `next_attempt_at` is skipped until its backoff elapses. Fresh items
+        // (next_attempt_at IS NULL) are always eligible.
+        const now = new Date().toISOString();
         const row = nativeDb
             .prepare(`SELECT id, item_type, item_id, priority, retry_count
          FROM deriver_queue
          WHERE status = 'pending'
+           AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
          ORDER BY priority DESC, created_at ASC
          LIMIT 1`)
-            .get();
+            .get(now);
         if (!row) {
             nativeDb.exec('ROLLBACK');
             return null;
         }
-        const now = new Date().toISOString();
         nativeDb
             .prepare(`UPDATE deriver_queue
          SET status = 'in_progress', claimed_at = ?, claimed_by = ?
@@ -129,8 +167,10 @@ export function completeItem(itemId, options = {}) {
  * Mark a claimed item as failed (with optional error message).
  *
  * If `retryCount` is below {@link MAX_RETRY_COUNT}, the item is re-queued
- * to `pending` with `retryCount + 1` (for retry next batch).
- * Otherwise the item is permanently moved to `failed`.
+ * to `pending` with `retryCount + 1` and an exponential-backoff
+ * `next_attempt_at` (T10405) so it is not re-claimed until the backoff window
+ * elapses. Otherwise the item is permanently moved to `failed` (DLQ semantics)
+ * and its backoff gate is cleared.
  *
  * @param itemId   - The deriver_queue.id to fail.
  * @param errorMsg - Human-readable error for the error_msg column.
@@ -147,13 +187,16 @@ export function failItem(itemId, errorMsg, options = {}) {
     if (!row)
         return;
     const nextRetry = (row.retry_count ?? 0) + 1;
-    const nextStatus = nextRetry >= MAX_RETRY_COUNT ? 'failed' : 'pending';
+    const permanentFail = nextRetry >= MAX_RETRY_COUNT;
+    const nextStatus = permanentFail ? 'failed' : 'pending';
+    // Re-queued items back off geometrically; permanently-failed items clear the gate.
+    const nextAttemptAt = permanentFail ? null : secondsFromNow(computeBackoffSeconds(nextRetry));
     nativeDb
         .prepare(`UPDATE deriver_queue
        SET status = ?, retry_count = ?, error_msg = ?,
-           claimed_at = NULL, claimed_by = NULL
+           claimed_at = NULL, claimed_by = NULL, next_attempt_at = ?
        WHERE id = ? AND status = 'in_progress'`)
-        .run(nextStatus, nextRetry, errorMsg, itemId);
+        .run(nextStatus, nextRetry, errorMsg, nextAttemptAt, itemId);
 }
 /**
  * Re-queue stale in_progress items whose `claimed_at` is older than
@@ -192,12 +235,14 @@ export function recoverStaleItems(options = {}) {
             result.failed++;
         }
         else {
+            // T10405: re-queued stale items also back off geometrically.
+            const nextAttemptAt = secondsFromNow(computeBackoffSeconds(nextRetry));
             nativeDb
                 .prepare(`UPDATE deriver_queue
            SET status = 'pending', retry_count = ?, error_msg = 'recovered from stale claim',
-               claimed_at = NULL, claimed_by = NULL
+               claimed_at = NULL, claimed_by = NULL, next_attempt_at = ?
            WHERE id = ?`)
-                .run(nextRetry, row.id);
+                .run(nextRetry, nextAttemptAt, row.id);
             result.requeued++;
         }
     }

package/dist/deriver/queue-manager.js.map

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

package/dist/dispatch/config-domain-handler.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ConfigDomainHandler — routes the config-as-domain operations to the
+ * `ConfigManifest` cascade resolver.
+ *
+ * This is the CORE-side routing surface for the four config-as-domain ops added
+ * in T11917 (`config.get`, `config.list`, `config.validate`, `config.unset`),
+ * plus the pre-existing `config.show` read. Every method delegates to the pure
+ * JSON cascade resolver in `../config/registry.js` (`resolveCleoConfig`,
+ * `getConfigValue`, `validateConfig`, `unsetConfigValue`) — the SSoT
+ * implementation of the {@link ConfigManifestEntry} contract from
+ * `@cleocode/contracts/config`.
+ *
+ * The handler lives in CORE (not the CLI `cleo/` dispatch layer) so the routing
+ * logic — and the cascade resolver it calls — is reusable by every consumer
+ * (CLI dispatch, the SDK gateway, REST clients) without crossing the
+ * package boundary back into `cleo/`. The thin `admin` DomainHandler in
+ * `packages/cleo/src/dispatch/domains/admin.ts` delegates its `config.*` ops to
+ * this class and wraps the {@link EngineResult} into the LAFS envelope.
+ *
+ * Pure JSON file IO only — does NOT open SQLite (ADR-068 DB Open Guard
+ * preserved; the cascade resolver it calls is also SQLite-free).
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/config-domain-handler
+ *
+ * @task T11917 — config-as-domain (M5/AC3)
+ * @epic T11769 — EP-API-STANDARD-FOUNDATION
+ * @saga T9855 — ConfigManifest SSoT
+ * @adr 076
+ */
+import { type EngineResult } from '@cleocode/contracts';
+import { type ResolveScope, type ValidateScope } from '../config/registry.js';
+/** Result of `config.get`. */
+export interface ConfigGetResult {
+    /** The dot-notation key that was resolved. */
+    key: string;
+    /** Cascade slice the value was resolved against. */
+    scope: ResolveScope;
+    /** Resolved value, or `null` when the key is absent. */
+    value: unknown;
+    /** `true` IFF the key resolved to a defined value in the cascade. */
+    found: boolean;
+}
+/** Result of `config.list`. */
+export interface ConfigListResult {
+    /** Cascade slice the config was resolved against. */
+    scope: ResolveScope;
+    /** Full resolved config object for the slice. */
+    config: Record<string, unknown>;
+    /** Flattened dot-notation keys present in the resolved config. */
+    keys: string[];
+}
+/** Result of `config.validate`. */
+export interface ConfigValidateResult {
+    /** Scope that was validated. */
+    scope: ValidateScope;
+    /** `true` IFF every gate passed. */
+    ok: boolean;
+    /** Human-readable schema issues. Empty when `ok === true`. */
+    issues: string[];
+}
+/** Result of `config.unset`. */
+export interface ConfigUnsetResult {
+    /** Config key that was targeted. */
+    key: string;
+    /** Scope the key was removed from. */
+    scope: 'project' | 'global';
+    /** `true` IFF a value was actually deleted. */
+    removed: boolean;
+}
+/**
+ * Routes the config-as-domain operations to the ConfigManifest cascade
+ * resolver. Stateless — construct once and reuse, or instantiate per call.
+ *
+ * @task T11917
+ */
+export declare class ConfigDomainHandler {
+    /**
+     * `config.get` — resolve a single config value by dot-notation key through
+     * the cascade resolver ({@link getConfigValue}).
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param key - Dot-notation config key (required).
+     * @param scopeRaw - Cascade slice (`global` | `project` | `merged`). Defaults
+     *   to `merged`.
+     */
+    get(projectRoot: string, key: string | undefined, scopeRaw?: string): Promise<EngineResult<ConfigGetResult>>;
+    /**
+     * `config.list` — resolve the full config cascade for a slice and surface its
+     * flattened dot-notation keys ({@link resolveCleoConfig} +
+     * {@link flattenConfigKeys}).
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param scopeRaw - Cascade slice. Defaults to `merged`.
+     */
+    list(projectRoot: string, scopeRaw?: string): Promise<EngineResult<ConfigListResult>>;
+    /**
+     * `config.validate` — schema-validate a scoped config file against its
+     * manifest entry's schema ({@link validateConfig}). A rejected file resolves
+     * to `{ ok: false, issues: [...] }` — it does NOT throw.
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param scopeRaw - `global` | `project`. Defaults to `project`. `merged` is
+     *   rejected — validation runs against a single file's manifest entry.
+     */
+    validate(projectRoot: string, scopeRaw?: string): Promise<EngineResult<ConfigValidateResult>>;
+    /**
+     * `config.unset` — remove a key from a scoped config file and persist the
+     * result ({@link unsetConfigValue}). Idempotent: removing an absent key is a
+     * success with `removed: false`.
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param key - Dot-notation config key to remove (required).
+     * @param global - When `true`, target the global config file.
+     */
+    unset(projectRoot: string, key: string | undefined, global?: boolean): Promise<EngineResult<ConfigUnsetResult>>;
+}
+/**
+ * Shared singleton {@link ConfigDomainHandler}. The handler is stateless, so a
+ * single instance is reused across the process.
+ *
+ * @task T11917
+ */
+export declare const configDomainHandler: ConfigDomainHandler;
+//# sourceMappingURL=config-domain-handler.d.ts.map

package/dist/dispatch/config-domain-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-domain-handler.d.ts","sourceRoot":"","sources":["../../src/dispatch/config-domain-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,KAAK,YAAY,EAA8B,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAGL,KAAK,YAAY,EAGjB,KAAK,aAAa,EAEnB,MAAM,uBAAuB,CAAC;AAE/B,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,+BAA+B;AAC/B,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,KAAK,EAAE,YAAY,CAAC;IACpB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,mCAAmC;AACnC,MAAM,WAAW,oBAAoB;IACnC,gCAAgC;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,oCAAoC;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,8DAA8D;IAC9D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AA2BD;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B;;;;;;;;OAQG;IACG,GAAG,CACP,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;IAmBzC;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;IAgB3F;;;;;;;;OAQG;IACG,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAmB9C;;;;;;;;OAQG;IACG,KAAK,CACT,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,CAAC,EAAE,OAAO,GACf,OAAO,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;CAW5C;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,qBAA4B,CAAC"}

package/dist/dispatch/config-domain-handler.js

@@ -0,0 +1,160 @@
+/**
+ * ConfigDomainHandler — routes the config-as-domain operations to the
+ * `ConfigManifest` cascade resolver.
+ *
+ * This is the CORE-side routing surface for the four config-as-domain ops added
+ * in T11917 (`config.get`, `config.list`, `config.validate`, `config.unset`),
+ * plus the pre-existing `config.show` read. Every method delegates to the pure
+ * JSON cascade resolver in `../config/registry.js` (`resolveCleoConfig`,
+ * `getConfigValue`, `validateConfig`, `unsetConfigValue`) — the SSoT
+ * implementation of the {@link ConfigManifestEntry} contract from
+ * `@cleocode/contracts/config`.
+ *
+ * The handler lives in CORE (not the CLI `cleo/` dispatch layer) so the routing
+ * logic — and the cascade resolver it calls — is reusable by every consumer
+ * (CLI dispatch, the SDK gateway, REST clients) without crossing the
+ * package boundary back into `cleo/`. The thin `admin` DomainHandler in
+ * `packages/cleo/src/dispatch/domains/admin.ts` delegates its `config.*` ops to
+ * this class and wraps the {@link EngineResult} into the LAFS envelope.
+ *
+ * Pure JSON file IO only — does NOT open SQLite (ADR-068 DB Open Guard
+ * preserved; the cascade resolver it calls is also SQLite-free).
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/config-domain-handler
+ *
+ * @task T11917 — config-as-domain (M5/AC3)
+ * @epic T11769 — EP-API-STANDARD-FOUNDATION
+ * @saga T9855 — ConfigManifest SSoT
+ * @adr 076
+ */
+import { engineError, engineSuccess } from '@cleocode/contracts';
+import { flattenConfigKeys, getConfigValue, resolveCleoConfig, unsetConfigValue, validateConfig, } from '../config/registry.js';
+/** Cascade slice selector accepted by `config.get` / `config.list`. */
+const RESOLVE_SCOPES = ['global', 'project', 'merged'];
+/** Scope selector accepted by `config.validate`. */
+const VALIDATE_SCOPES = ['global', 'project'];
+/**
+ * Narrow an untrusted scope string to a {@link ResolveScope}, defaulting to
+ * `'merged'`. Returns `null` when the string is non-empty but invalid so the
+ * caller can reject with `E_INVALID_INPUT`.
+ */
+function coerceResolveScope(scope) {
+    if (scope === undefined)
+        return 'merged';
+    return RESOLVE_SCOPES.includes(scope) ? scope : null;
+}
+/**
+ * Narrow an untrusted scope string to a {@link ValidateScope}, defaulting to
+ * `'project'`. Returns `null` when the string is non-empty but invalid.
+ */
+function coerceValidateScope(scope) {
+    if (scope === undefined)
+        return 'project';
+    return VALIDATE_SCOPES.includes(scope) ? scope : null;
+}
+/**
+ * Routes the config-as-domain operations to the ConfigManifest cascade
+ * resolver. Stateless — construct once and reuse, or instantiate per call.
+ *
+ * @task T11917
+ */
+export class ConfigDomainHandler {
+    /**
+     * `config.get` — resolve a single config value by dot-notation key through
+     * the cascade resolver ({@link getConfigValue}).
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param key - Dot-notation config key (required).
+     * @param scopeRaw - Cascade slice (`global` | `project` | `merged`). Defaults
+     *   to `merged`.
+     */
+    async get(projectRoot, key, scopeRaw) {
+        if (!key) {
+            return engineError('E_INVALID_INPUT', 'key is required', { fix: 'cleo config get <key>' });
+        }
+        const scope = coerceResolveScope(scopeRaw);
+        if (scope === null) {
+            return engineError('E_INVALID_INPUT', `scope must be one of: ${RESOLVE_SCOPES.join(', ')}`);
+        }
+        try {
+            const value = await getConfigValue(key, { scope, projectRoot });
+            return engineSuccess({ key, scope, value: value ?? null, found: value !== undefined });
+        }
+        catch (err) {
+            return engineError('E_CONFIG_RESOLVE_FAILED', err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * `config.list` — resolve the full config cascade for a slice and surface its
+     * flattened dot-notation keys ({@link resolveCleoConfig} +
+     * {@link flattenConfigKeys}).
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param scopeRaw - Cascade slice. Defaults to `merged`.
+     */
+    async list(projectRoot, scopeRaw) {
+        const scope = coerceResolveScope(scopeRaw);
+        if (scope === null) {
+            return engineError('E_INVALID_INPUT', `scope must be one of: ${RESOLVE_SCOPES.join(', ')}`);
+        }
+        try {
+            const config = await resolveCleoConfig({ scope, projectRoot });
+            return engineSuccess({ scope, config, keys: flattenConfigKeys(config) });
+        }
+        catch (err) {
+            return engineError('E_CONFIG_RESOLVE_FAILED', err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * `config.validate` — schema-validate a scoped config file against its
+     * manifest entry's schema ({@link validateConfig}). A rejected file resolves
+     * to `{ ok: false, issues: [...] }` — it does NOT throw.
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param scopeRaw - `global` | `project`. Defaults to `project`. `merged` is
+     *   rejected — validation runs against a single file's manifest entry.
+     */
+    async validate(projectRoot, scopeRaw) {
+        const scope = coerceValidateScope(scopeRaw);
+        if (scope === null) {
+            return engineError('E_INVALID_INPUT', `scope must be one of: ${VALIDATE_SCOPES.join(', ')} (merged is not validatable)`);
+        }
+        try {
+            const result = await validateConfig(scope, projectRoot);
+            return engineSuccess({ scope, ok: result.ok, issues: result.issues });
+        }
+        catch (err) {
+            return engineError('E_CONFIG_VALIDATE_FAILED', err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * `config.unset` — remove a key from a scoped config file and persist the
+     * result ({@link unsetConfigValue}). Idempotent: removing an absent key is a
+     * success with `removed: false`.
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @param key - Dot-notation config key to remove (required).
+     * @param global - When `true`, target the global config file.
+     */
+    async unset(projectRoot, key, global) {
+        if (!key) {
+            return engineError('E_INVALID_INPUT', 'key is required', { fix: 'cleo config unset <key>' });
+        }
+        try {
+            const result = await unsetConfigValue(key, { projectRoot, global });
+            return engineSuccess({ key: result.key, scope: result.scope, removed: result.removed });
+        }
+        catch (err) {
+            return engineError('E_CONFIG_UNSET_FAILED', err instanceof Error ? err.message : String(err));
+        }
+    }
+}
+/**
+ * Shared singleton {@link ConfigDomainHandler}. The handler is stateless, so a
+ * single instance is reused across the process.
+ *
+ * @task T11917
+ */
+export const configDomainHandler = new ConfigDomainHandler();
+//# sourceMappingURL=config-domain-handler.js.map

package/dist/dispatch/config-domain-handler.js.map

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

package/dist/dispatch/contracts/derive-output-contract.d.ts

@@ -0,0 +1,86 @@
+/**
+ * deriveOutputContract — generic per-operation OUTPUT contract producer.
+ *
+ * Closes the COVERAGE half of DHQ-057 / T11692 (the symptom-fix half — the
+ * `--field` remediation loop — is ST-4). The hand-authored {@link OUTPUT_CONTRACTS}
+ * registry covers only the 7 highest-traffic `tasks.*` operations. Every other
+ * operation in the 411-row {@link OPERATIONS} registry has NO machine-readable
+ * description of its result `data` shape, so an agent asking `cleo <op>
+ * --describe` (or hitting `E_FIELD_NOT_FOUND` on a bad `--field` pointer) gets
+ * nothing back for ~404 ops.
+ *
+ * Rather than hand-write 404 more contracts (unmaintainable, drifts instantly),
+ * this module DERIVES an {@link OperationOutputContract} for an operation from
+ * three shape registries that ALREADY exist:
+ *
+ * | Source registry        | Home                     | Derives                                                  |
+ * |------------------------|--------------------------|----------------------------------------------------------|
+ * | {@link OPERATION_RESULT_SCHEMAS} | `@cleocode/contracts`  | precise top-level data keys for the 5 workgraph reads     |
+ * | {@link PROJECTION_PLANS}         | `./mvi-projection.js`  | the data PATH (`tasks.show→task`, `docs.list→attachments`) for projected reads |
+ * | {@link MUTATE_PROJECTION_PLANS}  | `./mutate-projection.js` | the shared `{count, created, updated, deleted}` shape — but ONLY for the 6 ops that actually project it |
+ *
+ * Resolution precedence inside {@link deriveOutputContract} (most-precise first):
+ *
+ *   1. workgraph result schema  → precise key-derived contract
+ *   2. read op with projection plan → path-rooted contract
+ *   3. mutate op WITH a {@link MUTATE_PROJECTION_PLANS} entry → shared
+ *      minimal-mutate contract. An unplanned `gateway==='mutate'` op is NOT
+ *      rewritten by the dispatch middleware (it returns its raw domain payload),
+ *      so it must NOT advertise `/data/created/0` — it falls through to (4).
+ *   4. any other registered op (unplanned mutate or plain query) → a GENERIC
+ *      object contract (data is an object; no specific `--field` pointers, but a
+ *      `shapeNote` telling the agent to `--full`/`--describe`).
+ *
+ * A `null` return means the operation is NOT in {@link OPERATIONS} at all
+ * (genuinely unknown). Per T10400 §6.3 R6.7 a `null` output contract is
+ * "unverified shape", NEVER an error — callers MUST treat it as absent, not
+ * throw.
+ *
+ * ## Boundary
+ *
+ * This producer lives in `core/src/dispatch` (NOT `contracts`) because it reads
+ * `PROJECTION_PLANS` / `MUTATE_PROJECTION_PLANS`, which are core-resident, and
+ * because it is a bodied runtime helper (the contracts-purity Gate 10 forbids
+ * net-new bodied functions in `contracts`). It is import-time side-effect-free:
+ * it builds nothing at module load, only on call.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/dispatch/contracts/derive-output-contract
+ *
+ * @epic T11679
+ * @task T11762 ST-3 — DHQ-057: generic per-op output schema coverage backfill
+ */
+import { type OperationOutputContract } from '@cleocode/contracts';
+/**
+ * Derive an {@link OperationOutputContract} for an operation from the existing
+ * shape registries, or `null` when the operation is genuinely unknown.
+ *
+ * Used as the SECOND tier of {@link getOutputContract}'s resolution order
+ * (hand-authored {@link OUTPUT_CONTRACTS} → `deriveOutputContract` → `null`).
+ * The hand-authored 7 stay authoritative; this lifts coverage to near-100% for
+ * the remaining ~404 ops without hand-authoring sprawl.
+ *
+ * Resolution precedence (most-precise first): workgraph result schema →
+ * projection-plan read → planned mutate op → generic registered op (unplanned
+ * mutate or plain query) → `null`.
+ *
+ * A `null` return MUST be treated as "no contract / unverified shape", NOT an
+ * error (T10400 §6.3 R6.7).
+ *
+ * @param operation - Canonical `<domain>.<verb>` operation identifier.
+ * @returns A derived contract, or `null` when the operation is not registered.
+ *
+ * @example
+ * ```ts
+ * deriveOutputContract('tasks.tree');        // precise workgraph keys
+ * deriveOutputContract('tasks.show');        // projection-plan path (`task`)
+ * deriveOutputContract('tasks.add');         // shared minimal-mutate envelope (planned)
+ * deriveOutputContract('memory.observe');    // generic object (UNPLANNED mutate)
+ * deriveOutputContract('session.start');     // generic object contract
+ * deriveOutputContract('does.not-exist');    // null
+ * ```
+ *
+ * @task T11762 ST-3
+ */
+export declare function deriveOutputContract(operation: string): OperationOutputContract | null;
+//# sourceMappingURL=derive-output-contract.d.ts.map

package/dist/dispatch/contracts/derive-output-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-output-contract.d.ts","sourceRoot":"","sources":["../../../src/dispatch/contracts/derive-output-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AA+P7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CA8BtF"}