@cleocode/contracts 2026.4.69 → 2026.4.72

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/evidence-record-schema.ts

@@ -0,0 +1,158 @@
+/**
+ * Zod validation schemas for {@link EvidenceRecord} and its variants.
+ *
+ * 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 `*RecordSchema` and derive their inferred types from
+ * the canonical TypeScript interfaces in `./evidence-record.ts`.
+ *
+ * The top-level {@link evidenceRecordSchema} is a `z.discriminatedUnion` on
+ * `"kind"` so Zod can route to the correct variant in O(1).
+ *
+ * @epic T810
+ * @task T816
+ */
+
+import { z } from 'zod';
+
+// ─── Shared base fields ───────────────────────────────────────────────────────
+
+/**
+ * Zod schema for the provenance fields shared by every EvidenceRecord variant.
+ *
+ * Not exported as a standalone validator; always composed into a full record
+ * schema via `.extend()`.
+ */
+const evidenceBaseSchema = z.object({
+  /** Identity string of the agent that produced this record. */
+  agentIdentity: z.string().min(1),
+  /** SHA-256 hex digest (64 chars) of the attached artifact. */
+  attachmentSha256: z.string().length(64),
+  /** ISO 8601 timestamp at which the action ran. */
+  ranAt: z.string().datetime(),
+  /** Wall-clock duration of the action in milliseconds. */
+  durationMs: z.number().nonnegative(),
+});
+
+// ─── Individual variant schemas ───────────────────────────────────────────────
+
+/**
+ * Zod schema for {@link ImplDiffRecord}.
+ *
+ * Validates that `filesChanged` is a non-empty array and that `linesAdded` /
+ * `linesRemoved` are non-negative integers.
+ */
+export const implDiffRecordSchema = evidenceBaseSchema.extend({
+  kind: z.literal('impl-diff'),
+  phase: z.literal('implement'),
+  filesChanged: z.array(z.string().min(1)).min(1),
+  linesAdded: z.number().int().nonnegative(),
+  linesRemoved: z.number().int().nonnegative(),
+});
+
+/** Inferred TypeScript type from {@link implDiffRecordSchema}. */
+export type ImplDiffRecordInput = z.input<typeof implDiffRecordSchema>;
+
+/**
+ * Zod schema for {@link ValidateSpecCheckRecord}.
+ *
+ * Validates that `reqIdsChecked` is non-empty and `details` is non-blank.
+ */
+export const validateSpecCheckRecordSchema = evidenceBaseSchema.extend({
+  kind: z.literal('validate-spec-check'),
+  phase: z.literal('validate'),
+  reqIdsChecked: z.array(z.string().min(1)).min(1),
+  passed: z.boolean(),
+  details: z.string().min(1),
+});
+
+/** Inferred TypeScript type from {@link validateSpecCheckRecordSchema}. */
+export type ValidateSpecCheckRecordInput = z.input<typeof validateSpecCheckRecordSchema>;
+
+/**
+ * Zod schema for {@link TestOutputRecord}.
+ *
+ * Validates that `command` is non-blank and test counts are non-negative.
+ */
+export const testOutputRecordSchema = evidenceBaseSchema.extend({
+  kind: z.literal('test-output'),
+  phase: z.literal('test'),
+  command: z.string().min(1),
+  exitCode: z.number().int(),
+  testsPassed: z.number().int().nonnegative(),
+  testsFailed: z.number().int().nonnegative(),
+});
+
+/** Inferred TypeScript type from {@link testOutputRecordSchema}. */
+export type TestOutputRecordInput = z.input<typeof testOutputRecordSchema>;
+
+/**
+ * Zod schema for {@link LintReportRecord}.
+ *
+ * `phase` is restricted to `'implement' | 'test'`.
+ * `warnings` and `errors` are non-negative integers.
+ */
+export const lintReportRecordSchema = evidenceBaseSchema.extend({
+  kind: z.literal('lint-report'),
+  phase: z.enum(['implement', 'test']),
+  tool: z.string().min(1),
+  passed: z.boolean(),
+  warnings: z.number().int().nonnegative(),
+  errors: z.number().int().nonnegative(),
+});
+
+/** Inferred TypeScript type from {@link lintReportRecordSchema}. */
+export type LintReportRecordInput = z.input<typeof lintReportRecordSchema>;
+
+/**
+ * Zod schema for {@link CommandOutputRecord}.
+ *
+ * `phase` can be `'implement'`, `'validate'`, or `'test'`.
+ * `cmd` must be non-blank.
+ */
+export const commandOutputRecordSchema = evidenceBaseSchema.extend({
+  kind: z.literal('command-output'),
+  phase: z.enum(['implement', 'validate', 'test']),
+  cmd: z.string().min(1),
+  exitCode: z.number().int(),
+});
+
+/** Inferred TypeScript type from {@link commandOutputRecordSchema}. */
+export type CommandOutputRecordInput = z.input<typeof commandOutputRecordSchema>;
+
+// ─── Discriminated union ──────────────────────────────────────────────────────
+
+/**
+ * Zod discriminated-union schema for {@link EvidenceRecord}.
+ *
+ * Uses `z.discriminatedUnion('kind', [...])` for O(1) variant lookup.
+ * Parse with `evidenceRecordSchema.parse(input)` or
+ * `evidenceRecordSchema.safeParse(input)`.
+ *
+ * @example
+ * ```ts
+ * const rec = evidenceRecordSchema.parse({
+ *   kind: 'test-output',
+ *   phase: 'test',
+ *   agentIdentity: 'T816-worker',
+ *   attachmentSha256: 'a'.repeat(64),
+ *   command: 'pnpm test',
+ *   exitCode: 0,
+ *   testsPassed: 10,
+ *   testsFailed: 0,
+ *   ranAt: '2026-04-16T00:00:00.000Z',
+ *   durationMs: 1234,
+ * });
+ * ```
+ */
+export const evidenceRecordSchema = z.discriminatedUnion('kind', [
+  implDiffRecordSchema,
+  validateSpecCheckRecordSchema,
+  testOutputRecordSchema,
+  lintReportRecordSchema,
+  commandOutputRecordSchema,
+]);
+
+/** Inferred TypeScript type from {@link evidenceRecordSchema}. */
+export type EvidenceRecordInput = z.input<typeof evidenceRecordSchema>;

package/src/evidence-record.ts

@@ -0,0 +1,182 @@
+/**
+ * EvidenceRecord discriminated union — typed proof artifacts produced by IVTR agents.
+ *
+ * Each variant represents a specific kind of evidence that an IVTR-phase agent
+ * (implement, validate, test) can emit. All variants share a common set of
+ * provenance fields (`agentIdentity`, `attachmentSha256`, `ranAt`, `durationMs`)
+ * so that evidence rows can be queried, correlated, and archived uniformly.
+ *
+ * Five kinds are defined:
+ * - `impl-diff`         — a code change produced by an implement-phase agent
+ * - `validate-spec-check` — a spec-requirements check by a validate-phase agent
+ * - `test-output`       — the output of a test command run by a test-phase agent
+ * - `lint-report`       — a static-analysis run (biome, tsc, etc.)
+ * - `command-output`    — a generic CLI command invocation with exit code
+ *
+ * @epic T810
+ * @task T816
+ * @see {@link EvidenceRecordKind} for all discriminant values
+ */
+
+// ─── Variants ────────────────────────────────────────────────────────────────
+
+/**
+ * Evidence that an implement-phase agent produced a code diff.
+ *
+ * `filesChanged` lists the relative paths of every modified file.
+ * `attachmentSha256` is the SHA-256 hex digest of the serialised diff attachment.
+ */
+export interface ImplDiffRecord {
+  kind: 'impl-diff';
+  /** RCASD lifecycle phase that produced this record. */
+  phase: 'implement';
+  /** Identity string of the agent that ran this action (e.g. `"T816-worker"`). */
+  agentIdentity: string;
+  /** SHA-256 hex digest (64 chars) of the attached diff blob. */
+  attachmentSha256: string;
+  /** Relative paths of every file the diff touches. */
+  filesChanged: string[];
+  /** Net lines added across all changed files. */
+  linesAdded: number;
+  /** Net lines removed across all changed files. */
+  linesRemoved: number;
+  /** ISO 8601 timestamp at which the diff was captured. */
+  ranAt: string;
+  /** Wall-clock duration of the implement action in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Evidence that a validate-phase agent checked one or more REQ-IDs against
+ * the implementation and recorded a pass/fail verdict.
+ */
+export interface ValidateSpecCheckRecord {
+  kind: 'validate-spec-check';
+  /** RCASD lifecycle phase that produced this record. */
+  phase: 'validate';
+  /** Identity string of the agent that ran this action. */
+  agentIdentity: string;
+  /** SHA-256 hex digest (64 chars) of the spec-check report attachment. */
+  attachmentSha256: string;
+  /** REQ-IDs checked in this run (e.g. `["IVTR-01", "IVTR-02"]`). */
+  reqIdsChecked: string[];
+  /** `true` when all checked REQ-IDs passed; `false` if any failed. */
+  passed: boolean;
+  /** Human-readable summary of results per REQ-ID. */
+  details: string;
+  /** ISO 8601 timestamp at which the check ran. */
+  ranAt: string;
+  /** Wall-clock duration of the validation check in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Evidence that a test-phase agent ran a test command and recorded counts.
+ */
+export interface TestOutputRecord {
+  kind: 'test-output';
+  /** RCASD lifecycle phase that produced this record. */
+  phase: 'test';
+  /** Identity string of the agent that ran this action. */
+  agentIdentity: string;
+  /** SHA-256 hex digest (64 chars) of the test-output attachment. */
+  attachmentSha256: string;
+  /** The full test command that was executed (e.g. `"pnpm --filter @cleocode/contracts run test"`). */
+  command: string;
+  /** Exit code returned by the test command. */
+  exitCode: number;
+  /** Number of individual test cases that passed. */
+  testsPassed: number;
+  /** Number of individual test cases that failed. */
+  testsFailed: number;
+  /** ISO 8601 timestamp at which the test command started. */
+  ranAt: string;
+  /** Wall-clock duration of the full test run in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Evidence that a lint / static-analysis tool was run.
+ *
+ * The `phase` field is `'implement' | 'test'` because lint is commonly run
+ * after a code change (implement) or as part of a test suite (test).
+ */
+export interface LintReportRecord {
+  kind: 'lint-report';
+  /** RCASD lifecycle phase that produced this record. */
+  phase: 'implement' | 'test';
+  /** Identity string of the agent that ran this action. */
+  agentIdentity: string;
+  /** SHA-256 hex digest (64 chars) of the lint-output attachment. */
+  attachmentSha256: string;
+  /** Name of the lint tool that was invoked (e.g. `"biome"`, `"tsc"`). */
+  tool: string;
+  /** `true` when the lint run produced zero errors. */
+  passed: boolean;
+  /** Number of warnings emitted (may be > 0 even when `passed` is `true`). */
+  warnings: number;
+  /** Number of errors emitted. Non-zero means `passed` is `false`. */
+  errors: number;
+  /** ISO 8601 timestamp at which the lint tool was invoked. */
+  ranAt: string;
+  /** Wall-clock duration of the lint run in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Evidence that an agent ran an arbitrary CLI command and recorded its exit code.
+ *
+ * Use this as the catch-all when none of the other variants fit.
+ */
+export interface CommandOutputRecord {
+  kind: 'command-output';
+  /** RCASD lifecycle phase that produced this record. */
+  phase: 'implement' | 'validate' | 'test';
+  /** Identity string of the agent that ran this action. */
+  agentIdentity: string;
+  /** SHA-256 hex digest (64 chars) of the command-output attachment. */
+  attachmentSha256: string;
+  /** The CLI command that was executed. */
+  cmd: string;
+  /** Exit code returned by the command. */
+  exitCode: number;
+  /** ISO 8601 timestamp at which the command was invoked. */
+  ranAt: string;
+  /** Wall-clock duration of the command in milliseconds. */
+  durationMs: number;
+}
+
+// ─── Discriminated union ──────────────────────────────────────────────────────
+
+/**
+ * A typed evidence record produced by an IVTR-phase agent.
+ *
+ * The `kind` discriminant selects the variant. All variants carry
+ * `agentIdentity`, `attachmentSha256`, `ranAt`, and `durationMs` for
+ * uniform provenance tracking.
+ *
+ * @example
+ * ```ts
+ * const rec: EvidenceRecord = {
+ *   kind: 'test-output',
+ *   phase: 'test',
+ *   agentIdentity: 'T816-worker',
+ *   attachmentSha256: 'a'.repeat(64),
+ *   command: 'pnpm --filter @cleocode/contracts run test',
+ *   exitCode: 0,
+ *   testsPassed: 10,
+ *   testsFailed: 0,
+ *   ranAt: '2026-04-16T00:00:00.000Z',
+ *   durationMs: 1234,
+ * };
+ * ```
+ */
+export type EvidenceRecord =
+  | ImplDiffRecord
+  | ValidateSpecCheckRecord
+  | TestOutputRecord
+  | LintReportRecord
+  | CommandOutputRecord;
+
+/** All valid `kind` discriminants for {@link EvidenceRecord}. */
+export type EvidenceRecordKind = EvidenceRecord['kind'];