@cleocode/contracts 2026.4.69 → 2026.4.72

package/dist/attachment.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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
+ */
+/**
+ * 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[];
+}
+/**
+ * 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'];
+/**
+ * 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 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;
+}
+//# sourceMappingURL=attachment.d.ts.map

package/dist/attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.d.ts","sourceRoot":"","sources":["../src/attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC;IACZ,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,6CAA6C;IAC7C,MAAM,EAAE,KAAK,GAAG,WAAW,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,UAAU,GAClB,mBAAmB,GACnB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;AAIhD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,UAAU,EAAE,UAAU,CAAC;IACvB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;IACpF,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/attachment.js

@@ -0,0 +1,21 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=attachment.js.map

package/dist/attachment.js.map

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

package/dist/evidence-record-schema.d.ts

@@ -0,0 +1,202 @@
+/**
+ * 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';
+/**
+ * Zod schema for {@link ImplDiffRecord}.
+ *
+ * Validates that `filesChanged` is a non-empty array and that `linesAdded` /
+ * `linesRemoved` are non-negative integers.
+ */
+export declare const implDiffRecordSchema: z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"impl-diff">;
+    phase: z.ZodLiteral<"implement">;
+    filesChanged: z.ZodArray<z.ZodString>;
+    linesAdded: z.ZodNumber;
+    linesRemoved: z.ZodNumber;
+}, z.core.$strip>;
+/** 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 declare const validateSpecCheckRecordSchema: z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"validate-spec-check">;
+    phase: z.ZodLiteral<"validate">;
+    reqIdsChecked: z.ZodArray<z.ZodString>;
+    passed: z.ZodBoolean;
+    details: z.ZodString;
+}, z.core.$strip>;
+/** 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 declare const testOutputRecordSchema: z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"test-output">;
+    phase: z.ZodLiteral<"test">;
+    command: z.ZodString;
+    exitCode: z.ZodNumber;
+    testsPassed: z.ZodNumber;
+    testsFailed: z.ZodNumber;
+}, z.core.$strip>;
+/** 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 declare const lintReportRecordSchema: z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"lint-report">;
+    phase: z.ZodEnum<{
+        test: "test";
+        implement: "implement";
+    }>;
+    tool: z.ZodString;
+    passed: z.ZodBoolean;
+    warnings: z.ZodNumber;
+    errors: z.ZodNumber;
+}, z.core.$strip>;
+/** 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 declare const commandOutputRecordSchema: z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"command-output">;
+    phase: z.ZodEnum<{
+        test: "test";
+        implement: "implement";
+        validate: "validate";
+    }>;
+    cmd: z.ZodString;
+    exitCode: z.ZodNumber;
+}, z.core.$strip>;
+/** Inferred TypeScript type from {@link commandOutputRecordSchema}. */
+export type CommandOutputRecordInput = z.input<typeof commandOutputRecordSchema>;
+/**
+ * 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 declare const evidenceRecordSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"impl-diff">;
+    phase: z.ZodLiteral<"implement">;
+    filesChanged: z.ZodArray<z.ZodString>;
+    linesAdded: z.ZodNumber;
+    linesRemoved: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"validate-spec-check">;
+    phase: z.ZodLiteral<"validate">;
+    reqIdsChecked: z.ZodArray<z.ZodString>;
+    passed: z.ZodBoolean;
+    details: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"test-output">;
+    phase: z.ZodLiteral<"test">;
+    command: z.ZodString;
+    exitCode: z.ZodNumber;
+    testsPassed: z.ZodNumber;
+    testsFailed: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"lint-report">;
+    phase: z.ZodEnum<{
+        test: "test";
+        implement: "implement";
+    }>;
+    tool: z.ZodString;
+    passed: z.ZodBoolean;
+    warnings: z.ZodNumber;
+    errors: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    agentIdentity: z.ZodString;
+    attachmentSha256: z.ZodString;
+    ranAt: z.ZodString;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"command-output">;
+    phase: z.ZodEnum<{
+        test: "test";
+        implement: "implement";
+        validate: "validate";
+    }>;
+    cmd: z.ZodString;
+    exitCode: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+/** Inferred TypeScript type from {@link evidenceRecordSchema}. */
+export type EvidenceRecordInput = z.input<typeof evidenceRecordSchema>;
+//# sourceMappingURL=evidence-record-schema.d.ts.map

package/dist/evidence-record-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-record-schema.d.ts","sourceRoot":"","sources":["../src/evidence-record-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAM/B,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;iBAMxC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;iBAOjC,CAAC;AAEH,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;iBAOjC,CAAC;AAEH,oEAAoE;AACpE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAKpC,CAAC;AAEH,uEAAuE;AACvE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAIjF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAM/B,CAAC;AAEH,kEAAkE;AAClE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/evidence-record-schema.js

@@ -0,0 +1,130 @@
+/**
+ * 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(),
+});
+/**
+ * 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),
+});
+/**
+ * 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(),
+});
+/**
+ * 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(),
+});
+/**
+ * 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(),
+});
+// ─── 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,
+]);
+//# sourceMappingURL=evidence-record-schema.js.map

package/dist/evidence-record-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-record-schema.js","sourceRoot":"","sources":["../src/evidence-record-schema.ts"],"names":[],"mappings":"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"}