@cleocode/contracts 2026.5.56 → 2026.5.58

package/dist/sub-accessors.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Sub-accessor interfaces for UmbrellaDataAccessor role-specific databases.
+ *
+ * Each interface provides typed access to a specific CLEO database role.
+ * These are returned by UmbrellaDataAccessor.getSubAccessor(role).
+ *
+ * Implementors:
+ *   - BrainAccessor        → brain.db (memory observations, semantic graph)
+ *   - ConduitAccessor      → conduit.db (project-scoped messaging)
+ *   - NexusAccessor        → nexus.db (code intelligence graph)
+ *   - SignaldockAccessor   → signaldock.db (global agent identity)
+ *   - TelemetryAccessor    → (future — telemetry collection)
+ *
+ * See DocsAccessor in docs-accessor.ts for the docs/llmtxt sub-accessor.
+ *
+ * @task T9188
+ * @epic T9048
+ * @see ADR-068 (DB Charter — per-DB write ownership)
+ * @see ADR-069 (Coordination Layers — Storage Layer contract)
+ */
+/**
+ * Parameters for {@link BrainAccessor.observe}.
+ */
+export interface BrainObserveParams {
+    /** Free-text observation content. */
+    text: string;
+    /** Human-readable title. */
+    title?: string;
+    /** Memory type / entry type. */
+    type?: string;
+    /** Source session ID linking this observation to a session. */
+    sourceSessionId?: string;
+    /** Agent identifier that produced this observation. */
+    agent?: string;
+}
+/**
+ * A memory hit returned by {@link BrainAccessor.find}.
+ */
+export interface BrainMemoryHit {
+    /** Unique entry ID. */
+    readonly id: string;
+    /** Entry text. */
+    readonly text: string;
+    /** Entry title. */
+    readonly title: string | null;
+    /** Similarity or relevance score (0–1). */
+    readonly score: number;
+    /** Entry type. */
+    readonly type: string | null;
+}
+/**
+ * BrainAccessor — typed interface for brain.db (memory / observation store).
+ *
+ * Consumers depend on BrainAccessor, NOT on brain-retrieval internals.
+ *
+ * @task T9188
+ * @epic T9048
+ */
+export interface BrainAccessor {
+    /**
+     * Store a new observation in brain.db.
+     *
+     * @param text - Observation text (required, non-empty).
+     * @param params - Additional observation metadata.
+     * @returns ID of the stored observation.
+     */
+    observe(text: string, params?: Omit<BrainObserveParams, 'text'>): Promise<string>;
+    /**
+     * Find memory entries matching the given query.
+     *
+     * @param query - Free-text search query.
+     * @param limit - Maximum results (default: 10).
+     * @returns Ranked memory hits.
+     */
+    find(query: string, limit?: number): Promise<BrainMemoryHit[]>;
+    /**
+     * Release resources held by this accessor.
+     */
+    close(): Promise<void>;
+}
+/**
+ * ConduitAccessor — typed interface for conduit.db (project-scoped messaging).
+ *
+ * Minimal surface for T9188; full messaging API lives in conduit-sqlite.ts.
+ *
+ * @task T9188
+ * @epic T9048
+ */
+export interface ConduitAccessor {
+    /**
+     * Publish a message to a conduit topic.
+     *
+     * @param topic - Topic identifier.
+     * @param payload - Message payload (JSON-serializable).
+     */
+    publish(topic: string, payload: unknown): Promise<void>;
+    /**
+     * Check whether conduit.db is open and accessible.
+     *
+     * @returns True if the database is healthy.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Release resources held by this accessor.
+     */
+    close(): Promise<void>;
+}
+/**
+ * NexusAccessor — typed interface for nexus.db (code intelligence).
+ *
+ * Minimal surface for T9188; full nexus API lives in nexus-sqlite.ts.
+ *
+ * @task T9188
+ * @epic T9048
+ */
+export interface NexusAccessor {
+    /**
+     * Check whether nexus.db is open and accessible.
+     *
+     * @returns True if the database is healthy.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Release resources held by this accessor.
+     */
+    close(): Promise<void>;
+}
+/**
+ * SignaldockAccessor — typed interface for signaldock.db (global agent identity).
+ *
+ * Minimal surface for T9188; full signaldock API lives in signaldock-sqlite.ts.
+ *
+ * @task T9188
+ * @epic T9048
+ */
+export interface SignaldockAccessor {
+    /**
+     * Check whether signaldock.db is open and accessible.
+     *
+     * @returns True if the database is healthy.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Release resources held by this accessor.
+     */
+    close(): Promise<void>;
+}
+/**
+ * TelemetryAccessor — typed interface for telemetry collection (future DB).
+ *
+ * Placeholder for T9188 contract completeness. Full implementation deferred.
+ *
+ * @task T9188
+ * @epic T9048
+ */
+export interface TelemetryAccessor {
+    /**
+     * Record a telemetry event.
+     *
+     * @param event - Event name.
+     * @param data - Event payload (JSON-serializable).
+     */
+    record(event: string, data?: Record<string, unknown>): Promise<void>;
+    /**
+     * Check whether telemetry collection is available.
+     *
+     * @returns True if collection is operational.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Release resources held by this accessor.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=sub-accessors.d.ts.map

package/dist/sub-accessors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-accessors.d.ts","sourceRoot":"","sources":["../src/sub-accessors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAElF;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE/D;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/sub-accessors.js

@@ -0,0 +1,22 @@
+/**
+ * Sub-accessor interfaces for UmbrellaDataAccessor role-specific databases.
+ *
+ * Each interface provides typed access to a specific CLEO database role.
+ * These are returned by UmbrellaDataAccessor.getSubAccessor(role).
+ *
+ * Implementors:
+ *   - BrainAccessor        → brain.db (memory observations, semantic graph)
+ *   - ConduitAccessor      → conduit.db (project-scoped messaging)
+ *   - NexusAccessor        → nexus.db (code intelligence graph)
+ *   - SignaldockAccessor   → signaldock.db (global agent identity)
+ *   - TelemetryAccessor    → (future — telemetry collection)
+ *
+ * See DocsAccessor in docs-accessor.ts for the docs/llmtxt sub-accessor.
+ *
+ * @task T9188
+ * @epic T9048
+ * @see ADR-068 (DB Charter — per-DB write ownership)
+ * @see ADR-069 (Coordination Layers — Storage Layer contract)
+ */
+export {};
+//# sourceMappingURL=sub-accessors.js.map

package/dist/sub-accessors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sub-accessors.js","sourceRoot":"","sources":["../src/sub-accessors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.56",
+  "version": "2026.5.58",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -82,7 +82,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.56"
+    "@cleocode/lafs": "2026.5.58"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/emit-schemas.mjs",

package/src/docs-accessor.ts

@@ -0,0 +1,208 @@
+/**
+ * DocsAccessor — unified interface for all document operations in CLEO.
+ *
+ * Abstracts the scattered document surfaces behind a single typed API:
+ *   - llmtxt/sdk (AgentSession, receipt, version patches)
+ *   - llmtxt/blob (content-addressed blob store)
+ *   - llmtxt/graph (KnowledgeGraph)
+ *   - raw filesystem agent-outputs (migrated via T9064)
+ *
+ * Consumers depend on DocsAccessor, NOT on llmtxt/* subpaths directly.
+ * The llmtxt SDK becomes an implementation detail of DocsAccessorImpl.
+ *
+ * DB storage split (ADR-068 — DB Charter):
+ *   - storeDoc(kind=session-receipt | transcript) → writes to llmtxt.db
+ *   - storeDoc(kind=adr | agent-output | attachment) → writes to manifest.db (blob store)
+ *   - searchDocs() → queries llmtxt.db via llmtxt/similarity
+ *   - listDocs(kind=knowledge-graph-node) → queries llmtxt.db graph tables
+ *
+ * Coordination model (ADR-069 — Coordination Layers):
+ *   - DocsAccessor is a read/write accessor in the Storage Layer.
+ *   - CLI commands go through the Dispatch Layer; they accept a DocsAccessor
+ *     injected via the existing createDataAccessor() → UmbrellaDataAccessor chain.
+ *   - No direct SQLite access in consumers — all queries route through DocsAccessor.
+ *
+ * @task T9063
+ * @epic T9048
+ * @see ADR-068 (DB Charter — per-DB write ownership)
+ * @see ADR-069 (Coordination Layers — Storage Layer contract)
+ * @see T1824 (Decision Storage Consolidation — DocsAccessor becomes the write path for ADRs)
+ * @see T1825 (ADR migration — ADR files ingest via storeDoc(kind='adr'))
+ */
+
+// ---------------------------------------------------------------------------
+// Document kind discriminated union
+// ---------------------------------------------------------------------------
+
+/**
+ * All document kinds that DocsAccessor can store and retrieve.
+ *
+ * - `adr`                — Architecture Decision Records (docs/adr/*.md)
+ * - `agent-output`       — Agent session markdown outputs (.cleo/agent-outputs/*.md)
+ * - `transcript`         — Full agent conversation transcripts (llmtxt.db)
+ * - `attachment`         — Task attachments (manifest.db blob store)
+ * - `session-receipt`    — llmtxt session receipts (llmtxt.db sessions table)
+ * - `knowledge-graph-node` — Nodes from llmtxt/graph KnowledgeGraph (llmtxt.db)
+ */
+export type DocKind =
+  | 'adr'
+  | 'agent-output'
+  | 'transcript'
+  | 'attachment'
+  | 'session-receipt'
+  | 'knowledge-graph-node';
+
+// ---------------------------------------------------------------------------
+// Core document record
+// ---------------------------------------------------------------------------
+
+/**
+ * A stored document record returned by getDoc / listDocs.
+ */
+export interface DocRecord {
+  /** Content-addressed identifier (SHA-256 hex for blob-backed; UUID for DB-backed). */
+  readonly id: string;
+  /** Document kind. */
+  readonly kind: DocKind;
+  /** Raw content of the document (UTF-8 text or base64 for binary). */
+  readonly content: string;
+  /** Human-readable title or filename. */
+  readonly title: string | null;
+  /** ISO 8601 creation timestamp. */
+  readonly createdAt: string;
+  /** Linked task IDs (e.g. the task this agent-output was produced for). */
+  readonly linkedTaskIds: string[];
+  /** Arbitrary metadata blob (kind-specific). */
+  readonly meta: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Method parameter types
+// ---------------------------------------------------------------------------
+
+/**
+ * Parameters for {@link DocsAccessor.storeDoc}.
+ */
+export interface StoreDocParams {
+  /** Document kind determining which backing store is used. */
+  kind: DocKind;
+  /** Raw document content (UTF-8). */
+  content: string;
+  /** Human-readable title or filename. */
+  title?: string;
+  /** Task IDs to link to this document. */
+  linkedTaskIds?: string[];
+  /** Arbitrary metadata to attach (kind-specific). */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Result from {@link DocsAccessor.storeDoc}.
+ */
+export interface StoreDocResult {
+  /** Assigned document ID (SHA-256 for blob-backed, UUID for DB-backed). */
+  readonly id: string;
+  /** The backing store that received the write. */
+  readonly backend: 'llmtxt.db' | 'manifest.db';
+}
+
+/**
+ * Filters for {@link DocsAccessor.listDocs}.
+ */
+export interface ListDocsFilters {
+  /** Restrict to one document kind. */
+  kind?: DocKind;
+  /** Restrict to documents linked to this task ID. */
+  linkedTaskId?: string;
+  /** Maximum number of results. Default: 100. */
+  limit?: number;
+  /** Offset for pagination. */
+  offset?: number;
+  /** Order by. Default: 'createdAt'. */
+  orderBy?: 'createdAt' | 'title';
+}
+
+/**
+ * A search hit from {@link DocsAccessor.searchDocs}.
+ */
+export interface DocSearchHit {
+  /** The matching document record. */
+  readonly doc: DocRecord;
+  /** Similarity score (0–1, higher is more relevant). */
+  readonly score: number;
+}
+
+/**
+ * Export format for {@link DocsAccessor.exportDoc}.
+ */
+export type DocExportFormat = 'markdown' | 'json' | 'plain';
+
+// ---------------------------------------------------------------------------
+// DocsAccessor interface
+// ---------------------------------------------------------------------------
+
+/**
+ * DocsAccessor — unified interface for all CLEO document operations.
+ *
+ * Backed by llmtxt.db (sessions + receipts) and manifest.db (blob attachments).
+ * Both backing stores are opaque to consumers — all access goes through this
+ * interface.
+ *
+ * DB write ownership (ADR-068):
+ *   - `session-receipt`, `transcript`, `knowledge-graph-node` → llmtxt.db
+ *   - `adr`, `agent-output`, `attachment` → manifest.db (blob store)
+ *
+ * @see ADR-068 — DB Charter per-DB write ownership table
+ * @see ADR-069 — Coordination Layers: DocsAccessor is a Storage Layer contract
+ */
+export interface DocsAccessor {
+  /**
+   * Store a document, routing to the correct backing store by kind.
+   *
+   * @param params - Document content, kind, and metadata.
+   * @returns The assigned ID and backend that received the write.
+   */
+  storeDoc(params: StoreDocParams): Promise<StoreDocResult>;
+
+  /**
+   * Retrieve a document by ID or content hash.
+   *
+   * @param idOrHash - Document ID (UUID or SHA-256 hex).
+   * @returns The document record, or null if not found.
+   */
+  getDoc(idOrHash: string): Promise<DocRecord | null>;
+
+  /**
+   * List documents matching filters with pagination support.
+   *
+   * @param filters - Optional filter bag.
+   * @returns Array of matching document records.
+   */
+  listDocs(filters?: ListDocsFilters): Promise<DocRecord[]>;
+
+  /**
+   * Search documents by semantic similarity via llmtxt/similarity.
+   *
+   * Queries the llmtxt.db embeddings index. Only documents with embeddings
+   * are returned (agent-outputs, ADRs, transcripts ingested via storeDoc).
+   *
+   * @param query - Natural language query string.
+   * @param limit - Maximum hits to return. Default: 10.
+   * @returns Ranked search results with similarity scores.
+   */
+  searchDocs(query: string, limit?: number): Promise<DocSearchHit[]>;
+
+  /**
+   * Export a document in the requested format.
+   *
+   * @param id - Document ID.
+   * @param format - Output format. Default: 'markdown'.
+   * @returns Formatted document content string, or null if not found.
+   */
+  exportDoc(id: string, format?: DocExportFormat): Promise<string | null>;
+
+  /**
+   * Release any resources held by this accessor (close DB connections).
+   */
+  close(): Promise<void>;
+}

package/src/index.ts

@@ -254,6 +254,17 @@ export type {
   DependencySpec,
 } from './dependency.js';
 export type { AdapterManifest, DetectionPattern } from './discovery.js';
+// === DocsAccessor Contracts (T9063) ===
+export type {
+  DocExportFormat,
+  DocKind,
+  DocRecord,
+  DocSearchHit,
+  DocsAccessor,
+  ListDocsFilters,
+  StoreDocParams,
+  StoreDocResult,
+} from './docs-accessor.js';
 // === Error Utilities ===
 export {
   ClassifierUnregisteredAgentError,
@@ -1024,6 +1035,17 @@ export type {
   PlaybookRun,
   PlaybookRunStatus,
 } from './playbook.js';
+// === PostgresDataAccessor Contracts — cloud-sync scaffold (T9062) ===
+export type {
+  CreatePostgresDataAccessorFn,
+  PostgresDataAccessor,
+  PostgresDataAccessorOptions,
+  PostgresSyncDirection,
+  PostgresTenantNamespace,
+  PostgresTenantStrategy,
+  SyncResult,
+  SyncStatus,
+} from './postgres-data-accessor.js';
 export type { AdapterPathProvider } from './provider-paths.js';
 // === Release Pipeline (T1597 / ADR-063) ===
 export type {
@@ -1131,6 +1153,16 @@ export {
   // Terminal state sets
   TERMINAL_TASK_STATUSES,
 } from './status-registry.js';
+// === Sub-Accessor Contracts (T9188) ===
+export type {
+  BrainAccessor,
+  BrainMemoryHit,
+  BrainObserveParams,
+  ConduitAccessor,
+  NexusAccessor,
+  SignaldockAccessor,
+  TelemetryAccessor,
+} from './sub-accessors.js';
 // === Task Types ===
 export type {
   AcceptanceItem,

package/src/postgres-data-accessor.ts

@@ -0,0 +1,199 @@
+/**
+ * PostgresDataAccessor — interface stub for cloud-sync backend.
+ *
+ * SCAFFOLD ONLY (T9062). This file defines the type surface and namespacing
+ * contract for the PostgreSQL-backed DataAccessor. Full implementation
+ * (sync commands, migration, multi-tenant namespacing, auth) is deferred
+ * to T9062 child tasks.
+ *
+ * Architecture overview (ADR-TBD — cloud-sync):
+ *   - CLEO is local-first SQLite for portability and offline operation.
+ *   - A PostgresDataAccessor provides an engine-neutral drop-in replacement
+ *     for SqliteDataAccessor — same DataAccessor interface, different engine.
+ *   - Multi-tenant namespacing: each CLEO project maps to a Postgres
+ *     "tenant namespace" (schema or row-level tenant key) inside a shared
+ *     cluster. Cross-tenant isolation is enforced at the DB layer.
+ *   - Sync model: pull/push with last-write-wins per row (initial design).
+ *     CRDT merge (cr-sqlite) is opt-in per ADR from T947.
+ *   - Auth: each tenant identified by SignalDock identity (Ed25519 keypair).
+ *     Push receipts signed with the same primitive as llmtxt/sdk receipts.
+ *
+ * Engine-neutral proof:
+ *   The DataAccessor interface in @cleocode/contracts carries `engine: 'sqlite'`.
+ *   PostgresDataAccessor will carry `engine: 'postgres'`. Both satisfy the
+ *   same interface contract, proving the abstraction from T9050 is real.
+ *
+ * @task T9062
+ * @epic T9048
+ * @see packages/contracts/src/data-accessor.ts (DataAccessor interface)
+ * @see packages/contracts/src/postgres-sync-spec.ts (sync semantics spec)
+ * @see docs/adr/ (ADR-TBD: cloud-sync architecture — to be authored in T9062)
+ */
+
+import type { DataAccessor } from './data-accessor.js';
+
+// ---------------------------------------------------------------------------
+// Multi-tenant namespacing
+// ---------------------------------------------------------------------------
+
+/**
+ * Strategy for isolating tenant data in a shared Postgres cluster.
+ *
+ * - `schema`:   Each project gets a dedicated Postgres schema
+ *               (`cleo_<projectHash>`). Strongest isolation; higher overhead.
+ * - `row-level`: All projects share tables; tenant key (`project_id`) filters
+ *               every query. Simpler to manage; requires RLS enforcement.
+ */
+export type PostgresTenantStrategy = 'schema' | 'row-level';
+
+/**
+ * Identifies a CLEO project namespace inside the shared Postgres cluster.
+ *
+ * Generated deterministically from the project root hash (the same
+ * `projectHash` used in worktree paths) to ensure stable cross-machine
+ * identity without requiring a central registry lookup.
+ */
+export interface PostgresTenantNamespace {
+  /**
+   * Postgres-safe schema name (schema strategy) or tenant key (row-level).
+   * Format: `cleo_<projectHash>` where projectHash is the 16-char hex used
+   * in worktree directory names (e.g. `cleo_1e3146b7352ba279`).
+   */
+  readonly namespaceName: string;
+  /** Original hex project hash. */
+  readonly projectHash: string;
+  /** Isolation strategy in use for this cluster. */
+  readonly strategy: PostgresTenantStrategy;
+}
+
+// ---------------------------------------------------------------------------
+// Connection options
+// ---------------------------------------------------------------------------
+
+/**
+ * Connection options for the PostgresDataAccessor.
+ *
+ * All credentials are passed at construction time. The accessor never
+ * reads environment variables directly — callers are responsible for
+ * resolving the connection string from their config/secret store.
+ */
+export interface PostgresDataAccessorOptions {
+  /**
+   * PostgreSQL connection string (libpq format).
+   * Example: `postgresql://user:pass@host:5432/cleo_sync`.
+   */
+  connectionString: string;
+  /** Project namespace within the cluster. */
+  namespace: PostgresTenantNamespace;
+  /**
+   * Optional connection pool size. Default: 5.
+   * Keep small — CLI invocations are short-lived, not long-running servers.
+   */
+  poolSize?: number;
+  /**
+   * Optional Ed25519 signing keypair for authenticated push receipts.
+   * When present, every push batch is signed with this key.
+   * Aligns with llmtxt/sdk ContributionReceipt signing.
+   */
+  signingKeyHex?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sync semantics
+// ---------------------------------------------------------------------------
+
+/**
+ * Direction of a sync operation.
+ *
+ * - `push`: Write local SQLite state → Postgres.
+ * - `pull`: Read Postgres state → update local SQLite.
+ * - `bidirectional`: Pull then push (last-write-wins per row).
+ */
+export type PostgresSyncDirection = 'push' | 'pull' | 'bidirectional';
+
+/**
+ * Result from a sync operation.
+ */
+export interface SyncResult {
+  /** Direction that was executed. */
+  direction: PostgresSyncDirection;
+  /** Number of rows written to Postgres (push) or read from Postgres (pull). */
+  rowsSynced: number;
+  /** Number of conflicts resolved (last-write-wins). */
+  conflictsResolved: number;
+  /** ISO-8601 timestamp of sync completion. */
+  completedAt: string;
+}
+
+/**
+ * Status report from `getStatus()`.
+ */
+export interface SyncStatus {
+  /** Whether the Postgres connection is healthy. */
+  connected: boolean;
+  /** ISO-8601 timestamp of the last successful sync, or null if never synced. */
+  lastSyncedAt: string | null;
+  /** Number of local changes not yet pushed. */
+  pendingPushCount: number;
+  /** Whether the remote has changes not yet pulled. */
+  remoteAhead: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// PostgresDataAccessor interface stub
+// ---------------------------------------------------------------------------
+
+/**
+ * PostgresDataAccessor — Postgres-backed implementation of DataAccessor.
+ *
+ * INTERFACE STUB — full implementation deferred to T9062 child tasks.
+ *
+ * Extends the base DataAccessor interface with `engine: 'postgres'` and
+ * adds cloud-sync-specific methods (sync, getStatus, close).
+ *
+ * All methods from DataAccessor are inherited and must be implemented
+ * using Postgres queries (pg or postgres.js driver). The implementation
+ * will live in @cleocode/core (NOT in @cleocode/cleo — CLI-layer only).
+ *
+ * @see DataAccessor for the full list of inherited methods.
+ */
+export interface PostgresDataAccessor extends Omit<DataAccessor, 'engine'> {
+  /**
+   * The storage engine backing this accessor.
+   * Discriminates from SqliteDataAccessor at the type level.
+   */
+  readonly engine: 'postgres';
+
+  /**
+   * Sync local state with the Postgres backend.
+   *
+   * @param direction - Which direction(s) to sync.
+   * @returns Summary of the sync operation.
+   */
+  sync(direction?: PostgresSyncDirection): Promise<SyncResult>;
+
+  /**
+   * Get the current sync status (connection health + divergence metrics).
+   *
+   * @returns Sync status report.
+   */
+  getStatus(): Promise<SyncStatus>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory signature (implementation deferred)
+// ---------------------------------------------------------------------------
+
+/**
+ * Factory type for creating a PostgresDataAccessor.
+ *
+ * The concrete implementation (`createPostgresDataAccessor`) lives in
+ * @cleocode/core and will be exported from @cleocode/core/internal once
+ * the full implementation is complete (T9062 child tasks).
+ *
+ * @param options - Connection and namespace options.
+ * @returns A fully initialized PostgresDataAccessor.
+ */
+export type CreatePostgresDataAccessorFn = (
+  options: PostgresDataAccessorOptions,
+) => Promise<PostgresDataAccessor>;