@cleocode/contracts 2026.4.68 → 2026.4.70

package/src/attachment-schema.ts

@@ -0,0 +1,223 @@
+/**
+ * Zod validation schemas for {@link Attachment} and related types.
+ *
+ * Kept in a separate file from the plain TypeScript types so that consumers
+ * that do not need runtime validation (e.g. type-only imports) pay zero cost.
+ *
+ * All schemas are named `*Schema` and their inferred types are compatible with
+ * the canonical TypeScript interfaces in `./attachment.ts`.
+ *
+ * Uses `z.discriminatedUnion('kind', [...])` for O(1) variant lookup on the
+ * `kind` discriminant.
+ *
+ * @epic T760
+ * @task T795
+ */
+
+import { z } from 'zod';
+
+// ─── Shared field schemas ──────────────────────────────────────────────────────
+
+/**
+ * Common optional fields shared by all attachment variants.
+ *
+ * Not exported as a standalone validator — always composed into full variant
+ * schemas via `.extend()`.
+ */
+const attachmentCommonSchema = z.object({
+  /** Free-text description of what this attachment contains. */
+  description: z.string().optional(),
+  /** Labels for filtering (e.g., `["rfc", "spec"]`). */
+  labels: z.array(z.string()).optional(),
+});
+
+// ─── Variant schemas ───────────────────────────────────────────────────────────
+
+/**
+ * Zod schema for {@link LocalFileAttachment}.
+ *
+ * Validates that `path` is non-empty, `sha256` is a 64-character hex string,
+ * and `size` is a non-negative integer.
+ */
+export const localFileAttachmentSchema = attachmentCommonSchema.extend({
+  kind: z.literal('local-file'),
+  /** Path to the file (absolute or project-root-relative, forward-slashes only). */
+  path: z.string().min(1),
+  /** SHA-256 hex digest (64 hex characters). */
+  sha256: z.string().length(64),
+  /** IANA MIME type. */
+  mime: z.string().min(1),
+  /** File size in bytes (non-negative integer). */
+  size: z.number().int().nonnegative(),
+});
+
+/**
+ * Zod schema for {@link UrlAttachment}.
+ *
+ * Validates that `url` is a well-formed absolute URL. The optional `cachedSha256`
+ * is validated as a 64-character hex string when present.
+ */
+export const urlAttachmentSchema = attachmentCommonSchema.extend({
+  kind: z.literal('url'),
+  /** The remote URL — must be a valid absolute URL. */
+  url: z.string().url(),
+  /** SHA-256 of the cached body (64 hex characters). */
+  cachedSha256: z.string().length(64).optional(),
+  /** ISO 8601 timestamp when the body was cached. */
+  cachedAt: z.string().datetime().optional(),
+  /** IANA MIME type detected from the Content-Type header. */
+  mime: z.string().optional(),
+});
+
+/**
+ * Zod schema for {@link BlobAttachment}.
+ *
+ * Validates that `sha256` is 64 hex characters, `storageKey` is non-empty,
+ * and `size` is a non-negative integer.
+ */
+export const blobAttachmentSchema = attachmentCommonSchema.extend({
+  kind: z.literal('blob'),
+  /** SHA-256 hex digest of the uncompressed content (64 hex characters). */
+  sha256: z.string().length(64),
+  /** Storage key inside `.cleo/attachments/sha256/`. */
+  storageKey: z.string().min(1),
+  /** IANA MIME type. */
+  mime: z.string().min(1),
+  /** Size of the uncompressed content in bytes. */
+  size: z.number().int().nonnegative(),
+});
+
+/**
+ * Zod schema for {@link LlmsTxtAttachment}.
+ *
+ * Validates that `content` is non-empty, `sha256` is 64 hex characters, and
+ * `source` is one of the two allowed literal values.
+ */
+export const llmsTxtAttachmentSchema = attachmentCommonSchema.extend({
+  kind: z.literal('llms-txt'),
+  /** Where the llms.txt content originated. */
+  source: z.enum(['url', 'generated']),
+  /** Full markdown content of the llms.txt (stored inline). */
+  content: z.string().min(1),
+  /** SHA-256 hex digest of `content` (64 hex characters). */
+  sha256: z.string().length(64),
+});
+
+/**
+ * Zod schema for {@link LlmtxtDocAttachment}.
+ *
+ * Validates that `slug` is non-empty and `backend` is one of the two allowed
+ * literal values. `pinnedVersion` is an opaque string when present.
+ */
+export const llmtxtDocAttachmentSchema = attachmentCommonSchema.extend({
+  kind: z.literal('llmtxt-doc'),
+  /** Document slug from the llmtxt backend. */
+  slug: z.string().min(1),
+  /** Which backend owns the document. */
+  backend: z.enum(['local', 'remote']),
+  /**
+   * Version string pinned at attach time.
+   *
+   * Opaque: integer version for local backends, API-assigned string for remote.
+   */
+  pinnedVersion: z.string().optional(),
+});
+
+// ─── Discriminated union ──────────────────────────────────────────────────────
+
+/**
+ * Zod discriminated-union schema for {@link Attachment}.
+ *
+ * Uses `z.discriminatedUnion('kind', [...])` for O(1) variant lookup.
+ * Parse with `attachmentSchema.parse(input)` or
+ * `attachmentSchema.safeParse(input)`.
+ *
+ * @example
+ * ```ts
+ * const att = attachmentSchema.parse({
+ *   kind: 'local-file',
+ *   path: 'docs/rfc-003.md',
+ *   sha256: 'a'.repeat(64),
+ *   mime: 'text/markdown',
+ *   size: 8192,
+ *   description: 'RFC draft v3',
+ * });
+ * ```
+ */
+export const attachmentSchema = z.discriminatedUnion('kind', [
+  localFileAttachmentSchema,
+  urlAttachmentSchema,
+  blobAttachmentSchema,
+  llmsTxtAttachmentSchema,
+  llmtxtDocAttachmentSchema,
+]);
+
+/** Inferred TypeScript type from {@link attachmentSchema}. */
+export type AttachmentSchemaInput = z.input<typeof attachmentSchema>;
+
+// ─── AttachmentMetadata schema ────────────────────────────────────────────────
+
+/**
+ * Zod schema for {@link AttachmentMetadata}.
+ *
+ * Validates the persisted registry row. The embedded `attachment` field is
+ * validated recursively through the discriminated union.
+ */
+export const attachmentMetadataSchema = z.object({
+  /**
+   * Unique attachment ID.
+   *
+   * Pattern: `att_<base62>` or UUID fallback. Must be non-empty.
+   */
+  id: z.string().min(1),
+  /**
+   * Content hash — SHA-256 hex (64 chars) for byte-backed kinds, empty string
+   * for kinds that delegate content storage externally.
+   */
+  sha256: z.string(),
+  /** The full attachment value (validated through the discriminated union). */
+  attachment: attachmentSchema,
+  /** ISO 8601 creation timestamp. */
+  createdAt: z.string().datetime(),
+  /**
+   * Reference count — how many `AttachmentRef` rows point at this attachment.
+   *
+   * Must be a non-negative integer.
+   */
+  refCount: z.number().int().nonnegative(),
+});
+
+/** Inferred TypeScript type from {@link attachmentMetadataSchema}. */
+export type AttachmentMetadataSchemaInput = z.input<typeof attachmentMetadataSchema>;
+
+// ─── AttachmentRef schema ─────────────────────────────────────────────────────
+
+/**
+ * Zod schema for {@link AttachmentRef}.
+ *
+ * Validates the junction row linking one attachment to one owner. `ownerType`
+ * is restricted to the six supported CLEO entity types.
+ */
+export const attachmentRefSchema = z.object({
+  /** ID of the attachment (→ `attachments.id`). Must be non-empty. */
+  attachmentId: z.string().min(1),
+  /**
+   * The domain entity type that owns this attachment.
+   *
+   * Restricted to the six supported CLEO entity types.
+   */
+  ownerType: z.enum(['task', 'observation', 'session', 'decision', 'learning', 'pattern']),
+  /** ID of the owning entity. Must be non-empty. */
+  ownerId: z.string().min(1),
+  /** ISO 8601 timestamp when the ref was created. */
+  attachedAt: z.string().datetime(),
+  /**
+   * Agent identity (or `"human"`) that created the ref.
+   *
+   * Optional; populated from the active session credential when available.
+   */
+  attachedBy: z.string().optional(),
+});
+
+/** Inferred TypeScript type from {@link attachmentRefSchema}. */
+export type AttachmentRefSchemaInput = z.input<typeof attachmentRefSchema>;

package/src/attachment.ts

@@ -0,0 +1,245 @@
+/**
+ * Attachment discriminated union and metadata types.
+ *
+ * An `Attachment` represents any content artifact that can be associated
+ * with a CLEO owner (task, observation, session, decision, learning, pattern).
+ * Five attachment kinds are supported:
+ * - `local-file`  — a file on disk, tracked by path + SHA-256 hash
+ * - `url`         — a remote URL, optionally cached to the content-addressed store
+ * - `blob`        — raw bytes stored content-addressed in `.cleo/attachments/sha256/`
+ * - `llms-txt`    — a generated or fetched llms.txt site-index snapshot (RFC llmstxt.org)
+ * - `llmtxt-doc`  — a pointer into an llmtxt document (local or remote backend)
+ *
+ * `AttachmentMetadata` is the row persisted in the attachment registry.
+ * `AttachmentRef` is the junction row linking an attachment to an owner.
+ *
+ * @epic T760
+ * @task T795
+ * @see {@link https://github.com/kryptobaseddev/cleo} T760 unified attachments
+ */
+
+// ─── Attachment variants ──────────────────────────────────────────────────────
+
+/**
+ * A file on disk inside or adjacent to the CLEO project.
+ *
+ * The `path` is stored as recorded at attach time; the `sha256` is the content
+ * hash computed at that moment. On fetch, the runtime re-hashes the file and
+ * emits a warning if the file has drifted from the stored hash.
+ */
+export interface LocalFileAttachment {
+  kind: 'local-file';
+  /** Path to the file (absolute or project-root-relative, forward-slashes only). */
+  path: string;
+  /** SHA-256 hex digest of the file at attach time. */
+  sha256: string;
+  /** IANA MIME type (e.g., `"text/markdown"`, `"application/pdf"`). */
+  mime: string;
+  /** File size in bytes at attach time. */
+  size: number;
+  /** Optional free-text description of what this file contains. */
+  description?: string;
+  /** Labels for filtering (e.g., `["rfc", "spec"]`). */
+  labels?: string[];
+}
+
+/**
+ * A remote URL, optionally cached to the content-addressed store.
+ *
+ * When `--cache` is passed on attach, the body is fetched, hashed, and stored
+ * at `.cleo/attachments/sha256/<hash[0..2]>/<hash[2..]>.<ext>`. The
+ * `cachedSha256` and `cachedAt` fields are populated on a successful cache.
+ */
+export interface UrlAttachment {
+  kind: 'url';
+  /** The remote URL. Must be a valid absolute URL. */
+  url: string;
+  /** SHA-256 of the fetched body if the URL has been cached locally. */
+  cachedSha256?: string;
+  /** ISO 8601 timestamp when the body was cached. */
+  cachedAt?: string;
+  /** IANA MIME type detected from the Content-Type header. */
+  mime?: string;
+  /** Optional free-text description. */
+  description?: string;
+  /** Labels for filtering. */
+  labels?: string[];
+}
+
+/**
+ * Raw bytes stored content-addressed in `.cleo/attachments/sha256/`.
+ *
+ * No external path dependency — the content is always retrievable by
+ * `storageKey` as long as the attachment has a positive `refCount`.
+ */
+export interface BlobAttachment {
+  kind: 'blob';
+  /** SHA-256 hex digest of the uncompressed content. */
+  sha256: string;
+  /** Storage key inside `.cleo/attachments/sha256/` (e.g., `"ab/abcdef…12.pdf"`). */
+  storageKey: string;
+  /** IANA MIME type. */
+  mime: string;
+  /** Size of the uncompressed content in bytes. */
+  size: number;
+  /** Optional free-text description. */
+  description?: string;
+  /** Labels for filtering. */
+  labels?: string[];
+}
+
+/**
+ * A generated or fetched llms.txt site-index snapshot (per llmstxt.org spec).
+ *
+ * The content is stored inline — llms.txt files are small by design.
+ * `source: 'url'` means it was fetched from a remote site;
+ * `source: 'generated'` means it was produced by `cleo docs generate`.
+ */
+export interface LlmsTxtAttachment {
+  kind: 'llms-txt';
+  /** Where the llms.txt content originated. */
+  source: 'url' | 'generated';
+  /**
+   * Full markdown content of the llms.txt (stored inline; small by design per
+   * the llmstxt.org spec).
+   */
+  content: string;
+  /** SHA-256 hex digest of `content`. */
+  sha256: string;
+  /** Optional free-text description. */
+  description?: string;
+  /** Labels for filtering. */
+  labels?: string[];
+}
+
+/**
+ * A pointer into an llmtxt document managed by a local or remote backend.
+ *
+ * `backend: 'local'`  — the document lives in `.cleo/llmtxt/` (llmtxt LocalBackend).
+ * `backend: 'remote'` — the document lives on an llmtxt.my SaaS instance.
+ *
+ * This attachment kind delegates content storage to the llmtxt package; CLEO
+ * only stores the pointer (slug + backend + optional pinned version).
+ */
+export interface LlmtxtDocAttachment {
+  kind: 'llmtxt-doc';
+  /** Document slug from the llmtxt backend (e.g., `"9fZLOnf5"`). */
+  slug: string;
+  /** Which backend owns the document. */
+  backend: 'local' | 'remote';
+  /**
+   * Version string pinned at attach time.
+   *
+   * For `local` backends this is the integer version number serialised as a
+   * string; for `remote` backends it is the version identifier returned by the
+   * API.
+   */
+  pinnedVersion?: string;
+  /** Optional free-text description. */
+  description?: string;
+  /** Labels for filtering. */
+  labels?: string[];
+}
+
+// ─── Discriminated union ──────────────────────────────────────────────────────
+
+/**
+ * A content artifact attachable to any CLEO owner
+ * (task, observation, session, decision, learning, or pattern).
+ *
+ * The `kind` field is the discriminant. All variants share optional
+ * `description` and `labels` fields.
+ *
+ * @example
+ * ```ts
+ * const att: Attachment = {
+ *   kind: 'local-file',
+ *   path: 'docs/rfc-003.md',
+ *   sha256: 'a1b2c3...ff',
+ *   mime: 'text/markdown',
+ *   size: 8192,
+ *   description: 'RFC draft v3',
+ *   labels: ['rfc', 'spec'],
+ * };
+ * ```
+ */
+export type Attachment =
+  | LocalFileAttachment
+  | UrlAttachment
+  | BlobAttachment
+  | LlmsTxtAttachment
+  | LlmtxtDocAttachment;
+
+/** All valid `kind` discriminants for `Attachment`. */
+export type AttachmentKind = Attachment['kind'];
+
+// ─── Registry row ─────────────────────────────────────────────────────────────
+
+/**
+ * Persisted metadata row for one attachment in the attachment registry
+ * (`.cleo/attachments/index.db`).
+ *
+ * The full {@link Attachment} value is stored as a JSON blob in the `attachment`
+ * field so the registry does not need a column per variant.
+ */
+export interface AttachmentMetadata {
+  /**
+   * Unique attachment ID.
+   *
+   * Pattern: `att_<base62>` — generated by `llmtxt.generateId()` or a UUID
+   * fallback.
+   */
+  id: string;
+  /**
+   * Content hash.
+   *
+   * For `local-file`, `blob`, and `llms-txt` variants this is the SHA-256
+   * of the bytes at attach time. For `url` it is `cachedSha256` when the URL
+   * has been cached, or the empty string when it has not. For `llmtxt-doc` it
+   * is the empty string (content is managed by the llmtxt backend).
+   */
+  sha256: string;
+  /** The full attachment value (all kind-specific fields). */
+  attachment: Attachment;
+  /** ISO 8601 timestamp when this attachment was first registered. */
+  createdAt: string;
+  /**
+   * How many {@link AttachmentRef} rows point at this attachment.
+   *
+   * When `refCount` drops to zero the blob is eligible for GC via
+   * `cleo docs attachments gc`. Blobs are NEVER auto-deleted.
+   */
+  refCount: number;
+}
+
+// ─── Junction row ─────────────────────────────────────────────────────────────
+
+/**
+ * Junction row linking one attachment to one owner.
+ *
+ * Stored in the `attachment_refs` table of `.cleo/attachments/index.db`.
+ * A single attachment can be referenced by multiple owners simultaneously
+ * (e.g., the same RFC PDF attached to an epic and to every child task).
+ */
+export interface AttachmentRef {
+  /** ID of the attachment (→ `attachments.id`). */
+  attachmentId: string;
+  /**
+   * The domain entity type that owns this attachment.
+   *
+   * Determines which CLEO store to query when resolving the owner's display
+   * name (`tasks.db` for task/session/decision/learning/pattern;
+   * `brain.db` for observation).
+   */
+  ownerType: 'task' | 'observation' | 'session' | 'decision' | 'learning' | 'pattern';
+  /** The ID of the owning entity (e.g., `"T766"`, `"O-abc123"`, `"ses_..."`). */
+  ownerId: string;
+  /** ISO 8601 timestamp when the ref was created. */
+  attachedAt: string;
+  /**
+   * Agent identity (or `"human"`) that created the ref.
+   *
+   * Populated from the active session's agent credential when available.
+   */
+  attachedBy?: string;
+}

package/src/index.ts

@@ -6,6 +6,42 @@
  * Implementation packages (@cleocode/core, @cleocode/cleo) import from here.
  */
 
+// === Acceptance Gate Types (machine-verifiable criteria) ===
+export type {
+  AcceptanceGate,
+  AcceptanceGateKind,
+  AcceptanceGateResult,
+  CommandGate,
+  FileAssertion,
+  FileGate,
+  GateBase,
+  HttpGate,
+  LintGate,
+  ManualGate,
+  TestGate,
+} from './acceptance-gate.js';
+export type {
+  AcceptanceArrayInput,
+  AcceptanceGateResultInput,
+  AcceptanceGateSchemaInput,
+  AcceptanceItemInput,
+  FileAssertionInput,
+} from './acceptance-gate-schema.js';
+// === Acceptance Gate Zod Schemas (runtime validation) ===
+export {
+  acceptanceArraySchema,
+  acceptanceGateResultSchema,
+  acceptanceGateSchema,
+  acceptanceItemSchema,
+  commandGateSchema,
+  fileAssertionSchema,
+  fileGateSchema,
+  gateBaseSchema,
+  httpGateSchema,
+  lintGateSchema,
+  manualGateSchema,
+  testGateSchema,
+} from './acceptance-gate-schema.js';
 // === Provider Adapter Contracts ===
 export type { AdapterHealthStatus, CLEOProviderAdapter } from './adapter.js';
 // === Agent Registry (credential management) ===
@@ -34,6 +70,18 @@ export type {
   CycleTimeDistribution,
   CycleTimePercentiles,
 } from './archive.js';
+// === Attachment Types ===
+export type {
+  Attachment,
+  AttachmentKind,
+  AttachmentMetadata,
+  AttachmentRef,
+  BlobAttachment,
+  LlmsTxtAttachment,
+  LlmtxtDocAttachment,
+  LocalFileAttachment,
+  UrlAttachment,
+} from './attachment.js';
 // === Backup Manifest Types ===
 export type {
   BackupDatabaseEntry,
@@ -323,6 +371,7 @@ export {
 } from './status-registry.js';
 // === Task Types ===
 export type {
+  AcceptanceItem,
   CancelledTask,
   CompletedTask,
   EpicLifecycle,

package/src/task.ts

@@ -21,10 +21,23 @@
  * @task T4456
  */
 
+import type { AcceptanceGate } from './acceptance-gate.js';
 import type { TaskStatus } from './status-registry.js';
 
 export type { TaskStatus };
 
+/**
+ * A single acceptance criterion — either a free-text string (legacy) or a
+ * structured {@link AcceptanceGate} (machine-verifiable).
+ *
+ * Mixed arrays of these are stored as JSON in the `acceptance_json` column.
+ *
+ * @epic T760
+ * @task T780
+ * @task T800
+ */
+export type AcceptanceItem = string | AcceptanceGate;
+
 /** Task priority levels. */
 export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
 
@@ -169,8 +182,15 @@ export interface Task {
   /** File paths associated with this task. @defaultValue undefined */
   files?: string[];
 
-  /** Acceptance criteria for completion. @defaultValue undefined */
-  acceptance?: string[];
+  /**
+   * Mixed acceptance criteria — free-text strings (legacy) and/or structured
+   * {@link AcceptanceGate} objects (machine-verifiable).
+   *
+   * @epic T760
+   * @task T780
+   * @defaultValue undefined
+   */
+  acceptance?: AcceptanceItem[];
 
   /** IDs of tasks this task depends on. @defaultValue undefined */
   depends?: string[];
@@ -296,8 +316,8 @@ export interface TaskCreate {
   /** File paths associated with this task. @defaultValue undefined */
   files?: string[];
 
-  /** Acceptance criteria. @defaultValue undefined */
-  acceptance?: string[];
+  /** Acceptance criteria (string or AcceptanceGate objects). @defaultValue undefined */
+  acceptance?: AcceptanceItem[];
 
   /** IDs of tasks this task depends on. @defaultValue undefined */
   depends?: string[];