@cleocode/contracts 2026.5.60 → 2026.5.62

package/src/engine-result.ts

@@ -0,0 +1,220 @@
+/**
+ * Canonical EngineResult type — the single discriminated-union shape used by
+ * all SDK return paths, dispatch engines, and CLI domain handlers.
+ *
+ * Defined here in @cleocode/contracts so it is available to every consumer
+ * without creating a dependency on @cleocode/core. @cleocode/core re-exports
+ * these types and helpers transparently.
+ *
+ * @epic T1685 — T-CSL-RESET Wave 1: EngineResult canonicalization
+ */
+
+import type { LAFSPage } from '@cleocode/lafs';
+
+// ---------------------------------------------------------------------------
+// RFC 9457 Problem Details — canonical definition (moved from core/errors.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * RFC 9457 Problem Details object.
+ * Structured error representation for API responses.
+ *
+ * @see https://www.rfc-editor.org/rfc/rfc9457
+ */
+export interface ProblemDetails {
+  /** URI reference identifying the problem type. */
+  type: string;
+  /** Short human-readable summary of the problem type. */
+  title: string;
+  /** HTTP status code. */
+  status: number;
+  /** Human-readable explanation specific to this occurrence. */
+  detail: string;
+  /** URI reference identifying the specific problem instance. */
+  instance?: string;
+  /** Extension members carrying additional problem information. */
+  extensions?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// EngineResult — discriminated union
+// ---------------------------------------------------------------------------
+
+/**
+ * Successful engine result branch — carries `data` and optional `page`.
+ *
+ * @task T1685 — canonical home moved to contracts
+ */
+export interface EngineSuccess<T = unknown> {
+  readonly success: true;
+  readonly data: T;
+  readonly page?: LAFSPage;
+}
+
+/**
+ * Structured engine error payload — carries machine-readable code + human
+ * message plus optional exitCode, details, fix hint, alternative actions,
+ * and RFC 9457 problem details.
+ *
+ * @task T1707 — problemDetails field
+ * @task T1685 — canonical home moved to contracts
+ */
+export interface EngineErrorPayload {
+  code: string;
+  message: string;
+  exitCode?: number;
+  details?: unknown;
+  fix?: string;
+  alternatives?: Array<{ action: string; command: string }>;
+  /**
+   * RFC 9457 problem details for structured error reporting.
+   *
+   * @see ProblemDetails
+   */
+  problemDetails?: ProblemDetails;
+}
+
+/**
+ * Failed engine result branch — carries structured `error`.
+ *
+ * @task T1685 — canonical home moved to contracts
+ */
+export interface EngineFailure {
+  readonly success: false;
+  readonly error: EngineErrorPayload;
+}
+
+/**
+ * Canonical EngineResult — discriminated union of success and failure.
+ *
+ * Use `result.success` to narrow:
+ * - `true`  → `result.data: T` is present; `result.error` does not exist
+ * - `false` → `result.error: EngineErrorPayload` is present; `result.data` does not exist
+ *
+ * @task T1685 — canonical home moved to contracts
+ */
+export type EngineResult<T = unknown> = EngineSuccess<T> | EngineFailure;
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a successful EngineResult.
+ *
+ * @param data - the operation's payload
+ * @param page - optional pagination metadata
+ *
+ * @example
+ * ```ts
+ * import { engineSuccess } from '@cleocode/contracts';
+ * return engineSuccess({ items: [], total: 0 });
+ * return engineSuccess(items, { mode: 'offset', limit: 10, offset: 0, total: 100, hasMore: true });
+ * ```
+ */
+export function engineSuccess<T>(data: T, page?: LAFSPage): EngineResult<T> {
+  return page ? { success: true, data, page } : { success: true, data };
+}
+
+/**
+ * Construct a failed EngineResult with structured error.
+ *
+ * @param code - stable machine-readable error code (e.g. `'E_NOT_FOUND'`)
+ * @param message - human-readable error description
+ * @param options - optional `exitCode`, `details`, `fix`, `alternatives`, `problemDetails`
+ *
+ * @example
+ * ```ts
+ * import { engineError } from '@cleocode/contracts';
+ * return engineError('E_NOT_FOUND', `Task ${id} not found`, { fix: `cleo show ${id}` });
+ * ```
+ */
+export function engineError<T = unknown>(
+  code: string,
+  message: string,
+  options?: {
+    exitCode?: number;
+    details?: unknown;
+    fix?: string;
+    alternatives?: Array<{ action: string; command: string }>;
+    problemDetails?: ProblemDetails;
+  },
+): EngineResult<T> {
+  return {
+    success: false,
+    error: {
+      code,
+      message,
+      ...(options?.exitCode !== undefined ? { exitCode: options.exitCode } : {}),
+      ...(options?.details !== undefined ? { details: options.details } : {}),
+      ...(options?.fix !== undefined ? { fix: options.fix } : {}),
+      ...(options?.alternatives ? { alternatives: options.alternatives } : {}),
+      ...(options?.problemDetails !== undefined ? { problemDetails: options.problemDetails } : {}),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// unwrap() — throw-style ergonomic helper for SDK consumers
+// ---------------------------------------------------------------------------
+
+/**
+ * Error thrown by {@link unwrap} when an {@link EngineResult} carries a
+ * failure. Preserves the full {@link EngineErrorPayload} shape so callers
+ * can inspect `code`, `message`, `exitCode`, `details`, `fix`,
+ * `alternatives`, and `problemDetails` after catching.
+ *
+ * @task T1725
+ */
+export class EngineResultError extends Error {
+  /** Machine-readable error code (e.g. `'E_NOT_FOUND'`). */
+  readonly code: string;
+  /** Numeric process exit code, if present. */
+  readonly exitCode?: number;
+  /** Structured field-level details, if present. */
+  readonly details?: unknown;
+  /** Human-readable fix hint, if present. */
+  readonly fix?: string;
+  /** Alternative actions the caller may take, if present. */
+  readonly alternatives?: Array<{ action: string; command: string }>;
+  /** RFC 9457 problem details, if present. */
+  readonly problemDetails?: ProblemDetails;
+
+  constructor(payload: EngineErrorPayload) {
+    super(payload.message);
+    this.name = 'EngineResultError';
+    this.code = payload.code;
+    if (payload.exitCode !== undefined) this.exitCode = payload.exitCode;
+    if (payload.details !== undefined) this.details = payload.details;
+    if (payload.fix !== undefined) this.fix = payload.fix;
+    if (payload.alternatives !== undefined) this.alternatives = payload.alternatives;
+    if (payload.problemDetails !== undefined) this.problemDetails = payload.problemDetails;
+  }
+}
+
+/**
+ * Unwrap an {@link EngineResult}, returning the payload data on success or
+ * throwing an {@link EngineResultError} on failure.
+ *
+ * Intended for public SDK consumers who prefer a throw-style API over the
+ * internal discriminated-union pattern. Internal dispatch code SHOULD
+ * continue using the `if (result.success)` pattern directly.
+ *
+ * @param result - an {@link EngineResult} to unwrap
+ * @returns the `data` value when `result.success` is `true`
+ * @throws {@link EngineResultError} when `result.success` is `false`
+ *
+ * @example
+ * ```ts
+ * import { unwrap } from '@cleocode/contracts';
+ * const task = unwrap(await engine.getTask(id));
+ * ```
+ *
+ * @task T1725
+ */
+export function unwrap<T>(result: EngineResult<T>): T {
+  if (result.success) {
+    return result.data;
+  }
+  throw new EngineResultError(result.error);
+}

package/src/errors.ts

@@ -199,6 +199,40 @@ export class DecisionValidatorFailedError extends Error {
   }
 }
 
+/**
+ * Thrown when a Lead session attempts to end without delegating any work.
+ *
+ * Hard gate enforcement for T9230 (ADR-070): a Lead session with
+ * `delegate_task_count=0` and `tasks_completed > 0` is a bypass attempt.
+ * Leads MUST fan out work to Workers via `delegate_task`.
+ *
+ * @codeName E_LEAD_BYPASS_DETECTED
+ * @task T9230
+ * @adr ADR-070
+ */
+export class LeadBypassDetectedError extends Error {
+  /** Stable LAFS error code string for envelope emission. */
+  readonly code = 'E_LEAD_BYPASS_DETECTED';
+  /** Numeric exit code aligned with {@link ExitCode.LEAD_BYPASS_DETECTED} (107). */
+  readonly exitCode = 107;
+
+  /**
+   * @param tasksCompleted - Number of tasks completed in the session.
+   * @param sessionId - The session ID being ended.
+   */
+  constructor(
+    public readonly tasksCompleted: number,
+    public readonly sessionId: string,
+  ) {
+    super(
+      `E_LEAD_BYPASS_DETECTED: Lead session ${sessionId} completed ${tasksCompleted} task(s) ` +
+        `without any delegate_task call. Leads MUST fan out work to Workers (T9230 / ADR-070). ` +
+        `Set CLEO_OWNER_OVERRIDE=1 with reason to override (audited).`,
+    );
+    this.name = 'LeadBypassDetectedError';
+  }
+}
+
 /**
  * Normalize any thrown value into a standardized error object.
  *

package/src/exit-codes.ts

@@ -216,6 +216,14 @@ export enum ExitCode {
    * @task T1828
    */
   DECISION_VALIDATOR_FAILED = 106,
+
+  /**
+   * Lead session attempted to end without delegating any work — `delegate_task_count=0`
+   * with `tasks_completed > 0`. Leads MUST fan out to Workers (T9230 / ADR-070).
+   * @codeName E_LEAD_BYPASS_DETECTED
+   * @task T9230
+   */
+  LEAD_BYPASS_DETECTED = 107,
 }
 
 /** Check if an exit code represents an error (1-99). */

package/src/graph.ts

@@ -204,6 +204,118 @@ export function confidenceLabelFromNumeric(confidence: number): GraphEdgeConfide
   return 'AMBIGUOUS';
 }
 
+// ---------------------------------------------------------------------------
+// ConfidenceProvenance — structured provenance for confidence scores
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured provenance for an EXTRACTED confidence assignment.
+ *
+ * Used when confidence was derived from direct AST evidence (same-file
+ * lookup, import-scoped resolution) or an explicit source annotation.
+ *
+ * @since T9145
+ */
+export interface ExtractedProvenance {
+  /** Discriminant. */
+  readonly kind: 'extracted';
+  /**
+   * AST / static-analysis source that produced this confidence value.
+   * Examples: `"ast"`, `"import-scope"`, `"same-file"`, `"defines"`.
+   */
+  readonly source: string;
+}
+
+/**
+ * Structured provenance for an INFERRED confidence assignment.
+ *
+ * Used when confidence was derived from resolution heuristics (cross-file
+ * type lookup, heritage-map inference, name matching).
+ *
+ * @since T9145
+ */
+export interface InferredProvenance {
+  /** Discriminant. */
+  readonly kind: 'inferred';
+  /**
+   * Heuristic or rule that produced this confidence value.
+   * Examples: `"heritage-map"`, `"name-match"`, `"global-tier"`.
+   */
+  readonly heuristic: string;
+}
+
+/**
+ * Structured provenance for an AMBIGUOUS confidence assignment.
+ *
+ * Used when confidence is low because multiple candidates were found,
+ * the parent is external / unresolvable, or resolution fell to a global stub.
+ *
+ * @since T9145
+ */
+export interface AmbiguousProvenance {
+  /** Discriminant. */
+  readonly kind: 'ambiguous';
+  /**
+   * Candidate node IDs that competed for this resolution slot.
+   * May be empty when the ambiguity is due to an unresolvable external type.
+   */
+  readonly candidates: ReadonlyArray<string>;
+}
+
+/**
+ * Discriminated union of structured confidence provenance variants.
+ *
+ * Replaces the bare numeric `confidence` field on {@link GraphRelation} as
+ * part of the Beta gradient deprecation (phase 0: addition, phase 1:
+ * co-existence, removal at v2026.9).
+ *
+ * **Backfill mapping** for existing records created without structured
+ * provenance:
+ * - `confidence === 1.0` → `{ kind: 'extracted', source: 'ast' }`
+ * - `confidence >= 0.90` → `{ kind: 'extracted', source: 'legacy' }`
+ * - `confidence >= 0.80` → `{ kind: 'inferred', heuristic: 'legacy' }`
+ * - `confidence < 0.80`  → `{ kind: 'ambiguous', candidates: [] }`
+ *
+ * @since T9145
+ * @deprecated Numeric `confidence` on {@link GraphRelation} will be removed in v2026.9.
+ *   Use `confidenceProvenance` instead. Migration: `confidenceFromProvenance()` maps back.
+ */
+export type ConfidenceProvenance = ExtractedProvenance | InferredProvenance | AmbiguousProvenance;
+
+/**
+ * Backfill a {@link ConfidenceProvenance} from a legacy numeric confidence value.
+ *
+ * @param confidence - Numeric confidence in range [0.0, 1.0]
+ * @returns A structured provenance record consistent with the numeric value
+ * @since T9145
+ */
+export function provenanceFromNumeric(confidence: number): ConfidenceProvenance {
+  if (confidence === 1.0) return { kind: 'extracted', source: 'ast' };
+  if (confidence >= 0.9) return { kind: 'extracted', source: 'legacy' };
+  if (confidence >= 0.8) return { kind: 'inferred', heuristic: 'legacy' };
+  return { kind: 'ambiguous', candidates: [] };
+}
+
+/**
+ * Recover a numeric confidence value from a {@link ConfidenceProvenance} record.
+ *
+ * Inverse of {@link provenanceFromNumeric} for backward-compat bridging.
+ *
+ * @param provenance - Structured provenance record
+ * @returns Best-effort numeric confidence in range [0.0, 1.0]
+ * @since T9145
+ */
+export function confidenceFromProvenance(provenance: ConfidenceProvenance): number {
+  switch (provenance.kind) {
+    case 'extracted':
+      return provenance.source === 'ast' ? 1.0 : 0.95;
+    case 'inferred':
+      return 0.85;
+    case 'ambiguous':
+      return 0.5;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Relation interface
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -265,6 +265,20 @@ export type {
   StoreDocParams,
   StoreDocResult,
 } from './docs-accessor.js';
+export type {
+  EngineErrorPayload,
+  EngineFailure,
+  EngineResult,
+  EngineSuccess,
+  ProblemDetails,
+} from './engine-result.js';
+// === EngineResult — canonical discriminated-union SDK type (T1685) ===
+export {
+  EngineResultError,
+  engineError,
+  engineSuccess,
+  unwrap,
+} from './engine-result.js';
 // === Error Utilities ===
 export {
   ClassifierUnregisteredAgentError,
@@ -275,6 +289,7 @@ export {
   getErrorMessage,
   isErrorResult,
   isErrorType,
+  LeadBypassDetectedError,
   LifecycleScopeDeniedError,
   normalizeError,
   ThinAgentViolationError,
@@ -352,20 +367,28 @@ export {
   AGENT_TYPES,
   BRAIN_OBSERVATION_TYPES,
 } from './facade.js';
-// === Graph Intelligence Types (T512, T529, T1862) ===
+// === Graph Intelligence Types (T512, T529, T1862, T9145) ===
 export type {
+  AmbiguousProvenance,
   CommunityNode,
+  ConfidenceProvenance,
+  ExtractedProvenance,
   GraphEdgeConfidenceLabel,
   GraphNode,
   GraphNodeKind,
   GraphRelation,
   GraphRelationType,
   ImpactResult,
+  InferredProvenance,
   KnowledgeGraph,
   ProcessNode,
   SymbolIndex,
 } from './graph.js';
-export { confidenceLabelFromNumeric } from './graph.js';
+export {
+  confidenceFromProvenance,
+  confidenceLabelFromNumeric,
+  provenanceFromNumeric,
+} from './graph.js';
 export type { AdapterHookProvider } from './hooks.js';
 export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
 export type {
@@ -752,6 +775,23 @@ export type {
   NexusWhyResult,
   NexusWikiParams,
 } from './operations/nexus.js';
+// === Nexus Scope Contracts (T9145 + T9146) ===
+export type {
+  MetaWithNexusScope,
+  NexusBindingSource,
+  NexusEffect,
+  NexusOperationDescriptor,
+  NexusScope,
+  NexusScopeMeta,
+  NexusStore,
+  ScopeBinding,
+  SuggestedNextOp,
+} from './operations/nexus-scope.js';
+export {
+  getNexusDescriptor,
+  listOpsByScope,
+  NEXUS_SCOPE_MAP,
+} from './operations/nexus-scope-map.js';
 // === NEXUS User Profile Types (T1076 PSYCHE Wave 1) ===
 // Re-exported at top level so @cleocode/core/nexus and CLI dispatch can
 // import without the `ops.` namespace hop.
@@ -812,6 +852,10 @@ export type {
 // Session operation param/result types — re-exported at top level for typed-dispatch consumers
 // (T975 Wave D · ADR-051 migration)
 export type {
+  BriefingExcludeProvenance,
+  BriefingFieldContract,
+  BriefingFieldRule,
+  ContractViolation,
   DecisionRecord,
   SessionBriefingShowParams,
   SessionBriefingShowResult,
@@ -894,6 +938,8 @@ export type {
   TasksRelatesAddParams,
   TasksRelatesAddResult,
   TasksRelatesParams,
+  TasksRelatesRemoveParams,
+  TasksRelatesRemoveResult,
   TasksRelatesResult,
   TasksReorderDispatchResult,
   TasksReorderQueryParams,
@@ -1199,6 +1245,7 @@ export type {
   VerificationFailure,
   VerificationGate,
 } from './task.js';
+export { isTestFixtureOrigin, TASK_ORIGIN_CANONICAL } from './task.js';
 // === Task Evidence Types (T801) ===
 export type {
   CommandOutputEvidence,