@cleocode/contracts 2026.6.7 → 2026.6.8

package/src/db-recovery.ts

@@ -142,3 +142,68 @@ export interface BackupRecoverResult {
    */
   dryRun: boolean;
 }
+
+/**
+ * Per-role outcome of a `cleo doctor repair` pass (T11829 · DHQ-060).
+ *
+ * `doctor repair` first PROBES each role's live DB via `PRAGMA quick_check`
+ * (the same probe the recovery pipeline runs on snapshot candidates) and only
+ * invokes the {@link recoverMalformedDb} → quarantine → restore-from-snapshot →
+ * verify pipeline for roles that are actually malformed. This record captures
+ * what was observed and done for one role.
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairRoleResult {
+  /** Canonical role inspected. */
+  role: DbRole;
+  /** Absolute path to the role's live DB file (resolved from `DB_INVENTORY`). */
+  dbPath: string;
+  /** `true` when the live DB file exists on disk. */
+  present: boolean;
+  /**
+   * `true` when the live DB passed `PRAGMA quick_check` (or was absent) — i.e.
+   * NO repair was needed. `false` when corruption was detected.
+   */
+  healthy: boolean;
+  /**
+   * `'skipped'` — healthy or absent, nothing done;
+   * `'would-repair'` — `--dry-run`, corruption detected, repair NOT performed;
+   * `'repaired'` — corruption detected and snapshot restore succeeded;
+   * `'failed'` — corruption detected but recovery could not complete.
+   */
+  action: 'skipped' | 'would-repair' | 'repaired' | 'failed';
+  /** Absolute path to the snapshot restored (or that would be), when applicable. */
+  restoredFrom: string | null;
+  /** Absolute path to the quarantined corrupt DB, when a repair was performed. */
+  quarantinedTo: string | null;
+  /** Approximate data-loss window in hours, when a snapshot timestamp was parsed. */
+  dataLossWindowHours: number | null;
+  /** Human-readable detail (probe outcome, error reason, or restore summary). */
+  detail: string;
+}
+
+/**
+ * Aggregate result of a `cleo doctor repair` invocation across one or more roles
+ * (T11829 · DHQ-060).
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairResult {
+  /** `true` when the run was a `--dry-run` (no files mutated). */
+  dryRun: boolean;
+  /** Per-role outcomes. */
+  roles: DoctorRepairRoleResult[];
+  /** Count of roles found malformed (`!healthy`). */
+  malformedCount: number;
+  /** Count of roles actually repaired this run. */
+  repairedCount: number;
+  /** Count of roles where a needed repair FAILED. */
+  failedCount: number;
+}

package/src/dispatch/operations-registry.ts

@@ -7117,7 +7117,7 @@ export const OPERATIONS: OperationDef[] = [
     domain: 'docs',
     operation: 'add',
     description:
-      'docs.add (mutate) — attach a local file or URL to a CLEO owner entity (task, session, observation)',
+      'docs.add (mutate) — attach a local file, URL, or inline content to a CLEO owner entity (task, session, observation)',
     tier: 1,
     idempotent: false,
     sessionRequired: false,
@@ -7141,6 +7141,12 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Remote URL to attach',
       },
+      {
+        name: 'content',
+        type: 'string' as const,
+        required: false,
+        description: 'Inline document body (T10965); mutually exclusive with file/url',
+      },
       {
         name: 'desc',
         type: 'string' as const,

package/src/docs/provenance.ts

@@ -74,6 +74,7 @@ export const PROVENANCE_NODE_KINDS = [
  * - `related-task`    — child task is related (non-parent) to parent
  * - `linked-decision` — node references a BRAIN decision
  * - `derived-from`    — node was derived from a prior artifact
+ * - `shares-topic`    — two docs co-occur on a canonical topic slug (T11826)
  *
  * @task T10166
  */
@@ -83,7 +84,8 @@ export type ProvenanceEdgeRelation =
   | 'superseded-by'
   | 'related-task'
   | 'linked-decision'
-  | 'derived-from';
+  | 'derived-from'
+  | 'shares-topic';
 
 /**
  * Frozen const array backing {@link ProvenanceEdgeRelation} — used by the
@@ -98,6 +100,7 @@ export const PROVENANCE_EDGE_RELATIONS = [
   'related-task',
   'linked-decision',
   'derived-from',
+  'shares-topic',
 ] as const satisfies ReadonlyArray<ProvenanceEdgeRelation>;
 
 /**

package/src/docs/read.ts

@@ -0,0 +1,131 @@
+/**
+ * `docs.read` core-SDK contract — the envelope-typed surface an external
+ * consumer (the Obsidian plugin, `cleo docs view`) calls to render a single
+ * CLEO doc directly from `cleo.db`, the SOLE doc authority (saga T11778).
+ *
+ * The response carries the doc **body** plus its full provenance **frontmatter**
+ * (slug, version anchors, supersession pointers, related tasks, topics). Binary
+ * or non-UTF-8 bodies are surfaced as base64 (T11825 AC2) so a consumer can
+ * render images/PDFs/files stored as blobs without a second round-trip.
+ *
+ * Part of the T10400 core-SDK API standard — this is a typed contract, not an
+ * ad-hoc shape (T11825 AC3).
+ *
+ * @task T11825 (Epic T11781 / Saga T11778)
+ * @adr ADR-078 — Docs SSoT as provenance graph
+ */
+
+import { z } from 'zod';
+
+/**
+ * Provenance frontmatter for a doc, sourced from the `attachments` columns that
+ * back the docs SSoT. Mirrors what a published doc's YAML frontmatter would
+ * carry, but read live from the DB rather than a file.
+ *
+ * @task T11825
+ */
+export interface DocFrontmatter {
+  /** Stable human-readable slug (`attachments.slug`). */
+  readonly slug: string;
+  /** Doc-kind taxonomy tag (e.g. `adr`, `spec`), or null for untyped blobs. */
+  readonly kind: string | null;
+  /** Display title (falls back to slug). */
+  readonly title: string | null;
+  /** One-sentence human summary, distinct from the body. */
+  readonly summary: string | null;
+  /** Document workflow state (`draft | active | superseded | …`). */
+  readonly lifecycleStatus: string;
+  /** Sequential doc-version counter for this slug (`attachments.doc_version`). */
+  readonly docVersion: number;
+  /** CLEO release version that wrote this row (`attachments.owner_version`). */
+  readonly ownerVersion: string | null;
+  /** Slug of the doc this one supersedes, or null. */
+  readonly supersedes: string | null;
+  /** Slug of the doc that supersedes this one, or null. */
+  readonly supersededBy: string | null;
+  /** Canonical topic slugs this doc carries (`attachments.topics`). */
+  readonly topics: readonly string[];
+  /** `T####` task ids this doc relates to (`attachments.related_tasks`). */
+  readonly relatedTasks: readonly string[];
+  /** SHA-256 content address of the body. */
+  readonly sha256: string;
+  /** ISO-8601 creation instant. */
+  readonly createdAt: string;
+}
+
+/**
+ * The body payload of a doc read.
+ *
+ * Exactly one of {@link text} / {@link base64} is populated: UTF-8-decodable
+ * content is surfaced as `text` with `encoding: 'utf-8'`; binary content is
+ * surfaced as `base64` with `encoding: 'base64'`.
+ *
+ * @task T11825
+ */
+export interface DocBody {
+  /** How {@link DocReadResponse.body} content is encoded. */
+  readonly encoding: 'utf-8' | 'base64';
+  /** UTF-8 body text, present when `encoding === 'utf-8'`. */
+  readonly text?: string;
+  /** Base64-encoded body bytes, present when `encoding === 'base64'`. */
+  readonly base64?: string;
+  /** Decoded byte length of the body. */
+  readonly sizeBytes: number;
+  /** IANA MIME type, when known. */
+  readonly mimeType: string | null;
+}
+
+/**
+ * The full `docs.read` response envelope payload.
+ *
+ * @task T11825
+ */
+export interface DocReadResponse {
+  /** Provenance frontmatter. */
+  readonly frontmatter: DocFrontmatter;
+  /** Rendered body (text or base64). */
+  readonly body: DocBody;
+}
+
+/** Zod schema for {@link DocFrontmatter}. */
+export const docFrontmatterSchema = z.object({
+  slug: z.string(),
+  kind: z.string().nullable(),
+  title: z.string().nullable(),
+  summary: z.string().nullable(),
+  lifecycleStatus: z.string(),
+  docVersion: z.number().int(),
+  ownerVersion: z.string().nullable(),
+  supersedes: z.string().nullable(),
+  supersededBy: z.string().nullable(),
+  topics: z.array(z.string()).readonly(),
+  relatedTasks: z.array(z.string()).readonly(),
+  sha256: z.string(),
+  createdAt: z.string(),
+});
+
+/** Zod schema for {@link DocBody}. */
+export const docBodySchema = z.object({
+  encoding: z.enum(['utf-8', 'base64']),
+  text: z.string().optional(),
+  base64: z.string().optional(),
+  sizeBytes: z.number().int().nonnegative(),
+  mimeType: z.string().nullable(),
+});
+
+/** Zod schema for {@link DocReadResponse}. */
+export const docReadResponseSchema = z.object({
+  frontmatter: docFrontmatterSchema,
+  body: docBodySchema,
+});
+
+/**
+ * Type guard for {@link DocReadResponse}.
+ *
+ * @param value - Unknown value to validate.
+ * @returns True when `value` conforms to the `docs.read` response schema.
+ * @task T11825
+ */
+export function isDocReadResponse(value: unknown): value is DocReadResponse {
+  return docReadResponseSchema.safeParse(value).success;
+}

package/src/index.ts

@@ -346,6 +346,8 @@ export type {
   BackupRecoverResult,
   DbRecoveredRowCounts,
   DbRecoveryResult,
+  DoctorRepairResult,
+  DoctorRepairRoleResult,
 } from './db-recovery.js';
 // === Dependency Registry Contracts ===
 export type {
@@ -398,6 +400,14 @@ export {
   provenanceSessionNodeSchema,
   provenanceTaskNodeSchema,
 } from './docs/provenance.js';
+// === docs.read core-SDK Contract (T11825) ===
+export type { DocBody, DocFrontmatter, DocReadResponse } from './docs/read.js';
+export {
+  docBodySchema,
+  docFrontmatterSchema,
+  docReadResponseSchema,
+  isDocReadResponse,
+} from './docs/read.js';
 // === DocsAccessor Contracts (T9063) ===
 export type {
   DocExportFormat,

package/src/operations/docs.ts

@@ -383,15 +383,25 @@ export interface DocsGenerateResult {
 /**
  * Parameters for `docs.add`.
  *
- * Exactly one of `file` or `url` must be provided.
+ * Exactly one of `file`, `url`, or `content` must be provided.
  */
 export interface DocsAddParams {
   /** Owner entity ID (task, session, observation, etc.) — required. */
   ownerId: string;
-  /** Local file path to attach (mutually exclusive with `url`). */
+  /** Local file path to attach (mutually exclusive with `url` and `content`). */
   file?: string;
-  /** URL to attach as reference (mutually exclusive with `file`). */
+  /** URL to attach as reference (mutually exclusive with `file` and `content`). */
   url?: string;
+  /**
+   * Inline document body authored directly on the command line or piped via
+   * stdin (`--content -`). Mutually exclusive with `file` and `url`. Stored
+   * as a `text/markdown` blob exactly as a file-sourced add would be —
+   * including the manifest.db mirror, slug reservation, memory observation,
+   * and audit trail — so a doc can be created without a pre-existing file.
+   *
+   * @task T10965
+   */
+  content?: string;
   /** Optional human-readable description. */
   desc?: string;
   /** Optional comma-separated labels for categorization. */