@cleocode/contracts 2026.5.90 → 2026.5.93

package/src/doctor.ts

@@ -0,0 +1,130 @@
+/**
+ * Doctor domain contracts — types for `cleo doctor` worktree-orphan audit/prune.
+ *
+ * These types describe orphan `.cleo/` directories left behind under
+ * `<projectRoot>/.claude/worktrees/` by the T9550/T9580 SSoT bug (fixed in
+ * v2026.5.83) and the schema for the audit JSONL line written per prune.
+ *
+ * Consumed by:
+ *   - `packages/core/src/doctor/worktree-orphans.ts` (scan + prune primitives)
+ *   - `packages/cleo/src/cli/commands/doctor.ts` (CLI flags)
+ *
+ * @task T9790
+ * @epic T9790
+ */
+
+/**
+ * One orphan `.cleo/` directory discovered under
+ * `<projectRoot>/.claude/worktrees/`.
+ *
+ * Worktrees are nested 1-3 levels deep — examples:
+ *   - `<projectRoot>/.claude/worktrees/agent-X/.cleo/`            (depth 1)
+ *   - `<projectRoot>/.claude/worktrees/agent-X/T9220/.cleo/`     (depth 2)
+ *
+ * Each entry carries full provenance so the operator can decide whether
+ * the orphan represents lost work before pruning.
+ */
+export interface OrphanEntry {
+  /**
+   * The worktree root that contains the orphan — the first directory under
+   * `.claude/worktrees/` (e.g. `<projectRoot>/.claude/worktrees/agent-X`).
+   * Used as the boundary that `pruneWorktreeOrphans` validates against.
+   */
+  worktreePath: string;
+
+  /**
+   * Absolute path to the orphan `.cleo/` directory itself. Always lives
+   * under `worktreePath` (the security check rejects anything that doesn't).
+   */
+  orphanPath: string;
+
+  /**
+   * List of `tasks.db`, `brain.db`, `nexus.db`, or `config.json` paths
+   * found inside the orphan. Empty array means the orphan exists but is
+   * structurally empty (still pruned — it shouldn't be there at all).
+   */
+  dbFiles: string[];
+
+  /** Total byte size of the orphan tree (sum of regular file sizes). */
+  sizeBytes: number;
+
+  /** ISO-8601 timestamp of the most recent file modification under the orphan. */
+  lastModifiedAt: string;
+
+  /**
+   * Seconds since `lastModifiedAt` (relative to scan time). Surfaces "stale
+   * vs recent" without forcing the caller to compute date math.
+   */
+  ageSeconds: number;
+
+  /**
+   * `true` when the orphan contains more than just stray DB files — e.g. a
+   * full duplicate of `adrs/`, `agent-outputs/`, `rcasd/`, etc. These need
+   * heightened operator review before pruning.
+   */
+  isFullDuplicate: boolean;
+}
+
+/**
+ * Result of one prune operation. Reports the archive location, the per-entry
+ * outcome, and any entries rejected by the security gate.
+ */
+export interface PruneResult {
+  /**
+   * Absolute path to the `.tar.gz` archive written before any deletion.
+   * `null` only when `dryRun: true` AND no archive was produced.
+   */
+  archivePath: string | null;
+
+  /** Whether this was a dry run (no archive, no rm, no audit-log line). */
+  dryRun: boolean;
+
+  /** Entries that were successfully pruned (or would be in dry-run mode). */
+  pruned: OrphanEntry[];
+
+  /**
+   * Entries that failed validation and were skipped. The `reason` is a
+   * stable machine-readable code (e.g. `path-outside-worktrees-root`,
+   * `path-not-found`, `rm-failed`).
+   */
+  rejected: Array<{ entry: OrphanEntry; reason: string }>;
+
+  /** Total bytes archived (sum of `pruned[].sizeBytes`). */
+  totalSizeBytes: number;
+
+  /** ISO-8601 timestamp the prune completed. */
+  prunedAt: string;
+}
+
+/**
+ * One line appended to `.cleo/audit/worktree-prune.jsonl` per prune
+ * operation. Extends the existing audit-log schema (timestamp +
+ * worktreePath + action + agent) with the orphan-specific fields needed
+ * to reconstruct what was removed.
+ *
+ * Existing fields preserved for schema continuity:
+ *   - `timestamp`, `worktreePath`, `action`, `agent`
+ *
+ * New fields for orphan prune:
+ *   - `orphanPath`, `sizeBytes`, `dbFileCount`, `archivePath`, `dryRun`
+ */
+export interface PruneAuditEntry {
+  /** ISO-8601 timestamp. */
+  timestamp: string;
+  /** Worktree root that contained the orphan. */
+  worktreePath: string;
+  /** Absolute path to the orphan `.cleo/` directory removed. */
+  orphanPath: string;
+  /** Action code — fixed to `'prune-worktree-orphan'` for this flow. */
+  action: 'prune-worktree-orphan';
+  /** Always `'cleo'` — written by `cleo doctor`. */
+  agent: 'cleo';
+  /** Byte size of the pruned tree. */
+  sizeBytes: number;
+  /** Number of DB files found in the orphan (informational). */
+  dbFileCount: number;
+  /** Absolute path to the archive. `null` only on dry-run lines. */
+  archivePath: string | null;
+  /** Whether this entry represents a dry-run plan (no actual removal). */
+  dryRun: boolean;
+}

package/src/index.ts

@@ -277,6 +277,22 @@ export type {
   StoreDocParams,
   StoreDocResult,
 } from './docs-accessor.js';
+// === Canonical Doc-Kind Taxonomy Registry (T9788) ===
+export type {
+  BuiltinDocKind,
+  DocKindConfigFile,
+  DocKindExtensionConfig,
+  DocKindMetadata,
+  SlugValidationResult,
+} from './docs-taxonomy.js';
+export {
+  BUILTIN_DOC_KIND_VALUES,
+  BUILTIN_DOC_KINDS,
+  DocKindConfigError,
+  DocKindRegistry,
+} from './docs-taxonomy.js';
+// === Doctor: Worktree-Orphan Audit + Prune Types (T9790) ===
+export type { OrphanEntry, PruneAuditEntry, PruneResult } from './doctor.js';
 export type {
   EngineErrorPayload,
   EngineFailure,
@@ -499,6 +515,8 @@ export type {
 } from './llm/provider-profile.js';
 // === Phase 4 Unified Architecture (T9281 / ADR-072) — Resolved credential ===
 export type { ResolvedCredential } from './llm/resolved-credential.js';
+// === Logger contract (T9766 — centralized from @cleocode/core) ===
+export type { LoggerConfig } from './logger.js';
 // === ContextEngine contract (canonical home — T9304) ===
 export type { CompressedContext, ContextEngine } from './memory/context-engine.js';
 export type {
@@ -507,8 +525,14 @@ export type {
   BridgeObservation,
   BridgePattern,
   DispatchTrace,
+  // T9766 — BRAIN public-API records (centralized from @cleocode/core)
+  LearningRecord,
   MemoryBridgeConfig,
   MemoryBridgeContent,
+  MemoryDecisionRecord,
+  MemoryGraphStats,
+  MemorySearchHit,
+  PatternRecord,
   SessionSummary,
 } from './memory.js';
 export type {
@@ -985,6 +1009,9 @@ export type {
   SessionGcResult,
   SessionHandoffShowParams,
   SessionHandoffShowResult,
+  SessionLintParams,
+  SessionLintResult,
+  SessionLintViolation,
   SessionListParams,
   SessionListResult,
   SessionOps,
@@ -1097,6 +1124,8 @@ export type {
   ComplianceMetrics,
   ValidateArchiveStatsParams,
   ValidateArchiveStatsResult,
+  ValidateCanonDocsParams,
+  ValidateCanonDocsResult,
   ValidateCanonParams,
   ValidateCanonResult,
   ValidateChainParams,
@@ -1239,6 +1268,14 @@ export type {
 export type { AdapterPathProvider } from './provider-paths.js';
 // === Release Channel ===
 export type { ChannelValidationResult, ReleaseChannel } from './release/channel.js';
+// === Release Evidence Atoms (T9764) ===
+export type { GhPrViewPayload, ParsedPrEvidenceAtom } from './release/evidence-atoms.js';
+export {
+  ghPrViewSchema,
+  PR_REQUIRED_WORKFLOWS,
+  PR_REQUIRED_WORKFLOWS_ENV_VAR,
+  parsedPrEvidenceAtomSchema,
+} from './release/evidence-atoms.js';
 // === Release GitHub PR ===
 export type {
   BranchProtectionResult,

package/src/logger.ts

@@ -0,0 +1,42 @@
+/**
+ * Logger configuration contract for the CLEO ecosystem.
+ *
+ * Lives in `@cleocode/contracts` so CLI bootstrap, harness adapters, and other
+ * consumer packages can wire pino without reaching into `@cleocode/core` for a
+ * type definition. The implementation (`initLogger`, `getLogger`, etc.) remains
+ * in `@cleocode/core/logger`.
+ *
+ * @task T9766
+ * @epic T9752
+ * @saga T9758
+ */
+
+/**
+ * Configuration for the centralized pino logger.
+ *
+ * @remarks
+ * Consumed by `@cleocode/core`'s `initLogger` factory. The CLI bootstrap reads
+ * the corresponding `logging` section of `CleoConfig` and forwards it verbatim.
+ *
+ * @example
+ * ```typescript
+ * import type { LoggerConfig } from '@cleocode/contracts';
+ *
+ * const config: LoggerConfig = {
+ *   level: 'info',
+ *   filePath: 'logs/cleo.log',
+ *   maxFileSize: 10 * 1024 * 1024,
+ *   maxFiles: 5,
+ * };
+ * ```
+ */
+export interface LoggerConfig {
+  /** Pino log level (`trace` | `debug` | `info` | `warn` | `error` | `fatal`). */
+  level: string;
+  /** Path to the primary log file, relative to the `.cleo` directory. */
+  filePath: string;
+  /** Maximum bytes per log file before pino-roll rotates to a new file. */
+  maxFileSize: number;
+  /** Maximum number of rotated log files to retain before pino-roll deletes oldest. */
+  maxFiles: number;
+}

package/src/memory.ts

@@ -1,8 +1,28 @@
 /**
- * Memory bridge types for CLEO provider adapters.
- * Defines the shape of .cleo/memory-bridge.md content for cross-provider memory sharing.
+ * Memory bridge types for CLEO provider adapters and BRAIN public-API records.
+ *
+ * Two sets of types live in this file:
+ *
+ * 1. **Memory bridge types** (`MemoryBridgeContent`, `BridgeLearning`, …) — define
+ *    the shape of `.cleo/memory-bridge.md` content for cross-provider memory
+ *    sharing. Original home; added under T5240.
+ * 2. **BRAIN public-API records** (`MemorySearchHit`, `MemoryGraphStats`,
+ *    `MemoryDecisionRecord`, `PatternRecord`, `LearningRecord`) — typed result
+ *    shapes returned by `@cleocode/core`'s memory public API
+ *    (`findMemoryEntries`, `getDecisions`, `getPatterns`, `getLearnings`,
+ *    `getMemoryGraph`). Centralized here under T9766 so Studio + CLI consumers
+ *    can depend on them without reaching into `@cleocode/core`.
+ *
+ * @remarks
+ * `MemoryDecisionRecord` deliberately differs in name from the session-ops
+ * `DecisionRecord` exported by `./operations/session.ts` to avoid a barrel-level
+ * name collision. The two shapes are NOT interchangeable: session-ops captures
+ * an audit-log entry (`sessionId`, `taskId`, `alternatives`, `timestamp`),
+ * whereas `MemoryDecisionRecord` captures a BRAIN graph node
+ * (`outcome`, `memoryTier`, `verified`, `createdAt`).
  *
  * @task T5240
+ * @task T9766
  */
 
 // ============================================================================
@@ -180,3 +200,135 @@ export interface BridgeObservation {
   /** Truncated summary of the observation content. */
   summary: string;
 }
+
+// ============================================================================
+// BRAIN public-API records (T9766 — centralized from @cleocode/core)
+// ============================================================================
+
+/**
+ * A single cross-table memory search hit returned by `findMemoryEntries`.
+ *
+ * @remarks
+ * Spans all four BRAIN tables (observations, decisions, patterns, learnings) and
+ * is what the `memory.find` dispatch operation surfaces to the CLI and Studio.
+ *
+ * @task T9766
+ */
+export interface MemorySearchHit {
+  /** Entry identifier. */
+  id: string;
+  /** Source brain table. */
+  table: 'observations' | 'decisions' | 'patterns' | 'learnings';
+  /** Display title. */
+  title: string;
+  /** Short preview string (first ~160 chars of narrative/rationale/context). */
+  preview: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** Quality score in [0..1] or null if not computed. */
+  quality: number | null;
+  /** Memory tier (`'short'` | `'medium'` | `'long'`). */
+  tier: string | null;
+  /** Whether the entry has been owner-verified (1 = true, 0 = false). */
+  verified: number;
+  /** Number of times this entry has been retrieved. */
+  citations: number;
+}
+
+/**
+ * Aggregate statistics for the BRAIN memory graph returned by `getMemoryGraph`.
+ *
+ * @remarks
+ * Used by the `memory.graph` dispatch op and Studio's `/api/memory/graph` route.
+ *
+ * @task T9766
+ */
+export interface MemoryGraphStats {
+  /** Total node count. */
+  nodeCount: number;
+  /** Total edge count. */
+  edgeCount: number;
+  /** Edge type distribution. */
+  edgeTypeDistribution: Record<string, number>;
+  /** Average edges per node. */
+  averageEdgesPerNode: number;
+}
+
+/**
+ * A single decision record returned by `getDecisions`.
+ *
+ * @remarks
+ * **Intentionally named `MemoryDecisionRecord`** to avoid a barrel-level
+ * collision with the session-ops `DecisionRecord` exported by
+ * `./operations/session.ts`. The session-ops shape is an audit-log entry
+ * (`sessionId`, `taskId`, `alternatives`, `timestamp`); this shape is a BRAIN
+ * graph node (`outcome`, `memoryTier`, `verified`, `createdAt`).
+ *
+ * `@cleocode/core` continues to re-export this type under the legacy name
+ * `DecisionRecord` from its main barrel for back-compat — see
+ * `packages/core/src/memory/public-api.ts`.
+ *
+ * @task T9766
+ */
+export interface MemoryDecisionRecord {
+  /** Decision identifier (e.g. `D-arch-001`). */
+  id: string;
+  /** Decision statement. */
+  decision: string;
+  /** Justification / rationale. */
+  rationale: string | null;
+  /** Outcome: `proposed` | `accepted` | `rejected` | `superseded`. */
+  outcome: string | null;
+  /** ISO creation timestamp. */
+  createdAt: string;
+  /** Memory tier. */
+  memoryTier: string | null;
+  /** Owner-verified flag. */
+  verified: number;
+}
+
+/**
+ * A single pattern record returned by `getPatterns`.
+ *
+ * @task T9766
+ */
+export interface PatternRecord {
+  /** Pattern identifier. */
+  id: string;
+  /** Pattern description. */
+  pattern: string;
+  /** Contextual description where the pattern applies. */
+  context: string | null;
+  /** Pattern type tag. */
+  patternType: string | null;
+  /** Impact level (`'low'` | `'medium'` | `'high'`). */
+  impact: string | null;
+  /** Extraction timestamp. */
+  extractedAt: string;
+  /** Memory tier. */
+  memoryTier: string | null;
+  /** Retrieval count. */
+  citationCount: number;
+}
+
+/**
+ * A single learning record returned by `getLearnings`.
+ *
+ * @task T9766
+ */
+export interface LearningRecord {
+  /** Learning identifier. */
+  id: string;
+  /** Core insight. */
+  insight: string;
+  /** Source context where the learning was extracted from. */
+  source: string | null;
+  /** Learning type tag. */
+  learningType: string | null;
+  /** Creation timestamp. */
+  createdAt: string;
+  /** Memory tier. */
+  memoryTier: string | null;
+  /** Retrieval count. */
+  citationCount: number;
+}

package/src/operations/docs.ts

@@ -29,6 +29,7 @@
  */
 
 import type { AttachmentKind } from '../attachment.js';
+import { BUILTIN_DOC_KIND_VALUES, type BuiltinDocKind } from '../docs-taxonomy.js';
 
 // ============================================================================
 // Shared Attachment Types (API wire format)
@@ -54,28 +55,32 @@ export type { AttachmentKind } from '../attachment.js';
 /**
  * Allowed values for the `--type` taxonomy on `cleo docs add`.
  *
- * The set is closed at the CLI surface; new values require a coordinated
- * update to (1) {@link DOCS_TYPE_VALUES}, (2) the dispatch-layer guard, and
- * (3) the citty CLI flag description. The DB column itself is open (no CHECK)
- * so older clients reading a forward-compatible value gracefully degrade.
+ * As of T9788 this is derived from the canonical {@link BUILTIN_DOC_KIND_VALUES}
+ * in `docs-taxonomy.ts` — adding a kind there automatically widens this set
+ * without a duplicate edit here.
+ *
+ * Project-level extensions registered through `.cleo/docs-config.json` are
+ * NOT included in this constant (they are runtime-only, since the
+ * compile-time union must stay closed). Use {@link DocKindRegistry.list}
+ * to enumerate built-ins plus extensions at runtime.
  *
  * @task T9637 (T-DOCS-SLUG-2)
+ * @task T9788 (E-DOCS-TAXONOMY-V2 — registry consolidation)
  */
-export const DOCS_TYPE_VALUES = [
-  'spec',
-  'adr',
-  'research',
-  'handoff',
-  'note',
-  'llm-readme',
-] as const;
+export const DOCS_TYPE_VALUES: ReadonlyArray<BuiltinDocKind> =
+  BUILTIN_DOC_KIND_VALUES as ReadonlyArray<BuiltinDocKind>;
 
 /**
  * Closed-set type alias for {@link DOCS_TYPE_VALUES}.
  *
+ * As of T9788 this aliases {@link BuiltinDocKind} from the canonical
+ * registry — the union widens automatically when a new built-in kind
+ * is added to {@link BUILTIN_DOC_KINDS}.
+ *
  * @task T9637
+ * @task T9788
  */
-export type DocsType = (typeof DOCS_TYPE_VALUES)[number];
+export type DocsType = BuiltinDocKind;
 
 /**
  * Flattened wire-format attachment row returned by docs query operations.
@@ -169,16 +174,38 @@ export interface AttachmentRecord {
 // docs.list — list attachments for an owner
 // --------------------------------------------------------------------------
 
+/**
+ * Sort key for `docs.list` results.
+ *
+ * - `newest` — descending by `createdAt` (default — most recent first).
+ * - `sha`    — ascending by `sha256` (stable lexicographic).
+ * - `slug`   — ascending by `slug`; entries without a slug sort last.
+ *
+ * @task T9792
+ */
+export type DocsListOrderBy = 'newest' | 'sha' | 'slug';
+
+/**
+ * Default maximum number of rows returned by `docs.list` when the caller
+ * does not pass an explicit `limit`. Mirrored on the CLI flag default so the
+ * dispatch and CLI surfaces agree on the browsing window.
+ *
+ * @task T9792
+ */
+export const DOCS_LIST_DEFAULT_LIMIT = 50;
+
 /**
  * Parameters for `docs.list`.
  *
- * Exactly one of `task`, `session`, `observation`, or `project` must be
- * provided. `project=true` lists ALL attachments in the project DB
- * regardless of owner. `type` is an optional filter applicable to every
- * mode and matches the {@link DocsType} taxonomy exactly.
+ * Scope is auto-promoted to whole-project when no owner-scope flag is set
+ * (T9792). Pre-T9792 callers MUST still pass `project: true` explicitly to
+ * stay forward-compatible — the auto-promote happens at the CLI layer.
+ * `type` is an optional filter applicable to every mode and matches the
+ * {@link DocsType} taxonomy exactly.
  *
  * @task T9637 (T-DOCS-SLUG-2 — `type` filter)
  * @task T9638 (T-DOCS-SLUG-3 — `project` scope)
+ * @task T9792 (E-DOCS-LIST-UX-FIX — auto-promote project scope + limit + orderBy)
  */
 export interface DocsListParams {
   /** Task identifier to list attachments for. */
@@ -199,6 +226,20 @@ export interface DocsListParams {
    * @task T9637
    */
   type?: DocsType;
+  /**
+   * Maximum number of rows to return. Defaults to
+   * {@link DOCS_LIST_DEFAULT_LIMIT} when omitted. Values `<= 0` are treated
+   * as "no limit" so agents can opt-in to the full result set explicitly.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Sort key for the returned rows. Defaults to `newest` when omitted.
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
 }
 
 /**
@@ -218,8 +259,41 @@ export interface DocsListResult {
   project?: boolean;
   /** Type taxonomy filter, echoed back from the request when provided. */
   type?: DocsType;
-  /** Count of attachments for this owner. */
+  /** Count of attachments for this owner (after limit + filters). */
   count: number;
+  /**
+   * Total number of attachments matching the scope + filters BEFORE the
+   * `limit` window was applied. Only emitted when `limit` truncated the
+   * result set so consumers can distinguish "fewer than limit" from
+   * "limit truncated".
+   *
+   * @task T9792
+   */
+  totalCount?: number;
+  /**
+   * Effective limit applied to this response. Mirrored from the request
+   * (or {@link DOCS_LIST_DEFAULT_LIMIT} when the request did not set one)
+   * so consumers can paginate without re-deriving the default.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Effective sort key applied to this response. Mirrored from the request
+   * (or `"newest"` when the request did not set one).
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
+  /**
+   * Optional human-readable hint surfaced when a default behaviour kicked
+   * in (e.g. project scope auto-promoted because no scope was passed). The
+   * CLI surfaces this through `meta.hint` so JSON consumers can detect that
+   * a narrower invocation may have been intended.
+   *
+   * @task T9792
+   */
+  hint?: string;
   /** Attachment metadata array. */
   attachments: DocsAttachmentRow[];
   /** Current attachment backend in use. */

package/src/operations/session.ts

@@ -587,6 +587,76 @@ export interface SessionRecordAssumptionResult {
   timestamp: string;
 }
 
+// session.lint — agent-accountability harness (T9797)
+
+/**
+ * Parameters for `session.lint`.
+ *
+ * Scans a Claude Code-style session transcript (`*.jsonl`) for raw
+ * markdown writes that bypass the docs SSoT. Flags any tool call whose
+ * `file_path` lands under a `rawMdPaths` entry whose owning DocKind has
+ * `rawMdAllowed: false` in `.cleo/canon.yml`.
+ *
+ * @task T9797
+ */
+export interface SessionLintParams {
+  /**
+   * Absolute path to the `.jsonl` transcript to scan. Required.
+   */
+  transcript: string;
+}
+
+/**
+ * One violation surfaced by `session.lint`.
+ *
+ * Mirrors `CanonLintViolation` from
+ * `packages/core/src/session/canon-lint.ts` (the SDK-level engine).
+ *
+ * @task T9797
+ */
+export interface SessionLintViolation {
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** Anthropic `tool_use.id` (e.g. `toolu_01ABC...`). May be empty. */
+  toolUseId: string;
+  /** Tool name — `Write`, `Edit`, or `MultiEdit`. */
+  tool: string;
+  /** Repo-relative path the agent attempted to write. */
+  path: string;
+  /** Owning DocKind id (e.g. `adr`, `note`). */
+  docKind: string;
+  /** Matching `rawMdPaths` entry (e.g. `.cleo/adrs/`). */
+  matchedPath: string;
+  /** Categorical reason — always `'raw-md-canonical'` today. */
+  kind: 'raw-md-canonical';
+  /** First 200 chars of the violating content. */
+  evidence: string;
+  /** Suggested fix command. */
+  fix: string;
+}
+
+/**
+ * Result of `session.lint`.
+ *
+ * @task T9797
+ */
+export interface SessionLintResult {
+  /** Absolute transcript path that was scanned. */
+  transcriptPath: string;
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** True when no violations were flagged. */
+  passed: boolean;
+  /** Number of `Write`/`Edit`/`MultiEdit` tool calls inspected. */
+  scanned: number;
+  /** Violations in transcript order. Empty when `passed === true`. */
+  violations: SessionLintViolation[];
+  /** Non-fatal warnings (e.g. JSON parse failures on isolated lines). */
+  warnings: string[];
+  /** `'enforced'` when canon.yml present, `'no-canon'` when missing. */
+  mode: 'enforced' | 'no-canon';
+}
+
 // ---------------------------------------------------------------------------
 // Typed operation record (Wave D adapter — T975)
 // ---------------------------------------------------------------------------
@@ -619,4 +689,5 @@ export type SessionOps = {
     SessionRecordAssumptionParams,
     SessionRecordAssumptionResult,
   ];
+  readonly lint: readonly [SessionLintParams, SessionLintResult];
 };