@cleocode/contracts 2026.4.69 → 2026.4.70

package/dist/attachment-schema.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 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';
+/**
+ * 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 declare const localFileAttachmentSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"local-file">;
+    path: z.ZodString;
+    sha256: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * 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 declare const urlAttachmentSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+    cachedSha256: z.ZodOptional<z.ZodString>;
+    cachedAt: z.ZodOptional<z.ZodString>;
+    mime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Zod schema for {@link BlobAttachment}.
+ *
+ * Validates that `sha256` is 64 hex characters, `storageKey` is non-empty,
+ * and `size` is a non-negative integer.
+ */
+export declare const blobAttachmentSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"blob">;
+    sha256: z.ZodString;
+    storageKey: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * 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 declare const llmsTxtAttachmentSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"llms-txt">;
+    source: z.ZodEnum<{
+        url: "url";
+        generated: "generated";
+    }>;
+    content: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 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 declare const llmtxtDocAttachmentSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"llmtxt-doc">;
+    slug: z.ZodString;
+    backend: z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+    }>;
+    pinnedVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 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 declare const attachmentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"local-file">;
+    path: z.ZodString;
+    sha256: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+    cachedSha256: z.ZodOptional<z.ZodString>;
+    cachedAt: z.ZodOptional<z.ZodString>;
+    mime: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"blob">;
+    sha256: z.ZodString;
+    storageKey: z.ZodString;
+    mime: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"llms-txt">;
+    source: z.ZodEnum<{
+        url: "url";
+        generated: "generated";
+    }>;
+    content: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    kind: z.ZodLiteral<"llmtxt-doc">;
+    slug: z.ZodString;
+    backend: z.ZodEnum<{
+        local: "local";
+        remote: "remote";
+    }>;
+    pinnedVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+/** Inferred TypeScript type from {@link attachmentSchema}. */
+export type AttachmentSchemaInput = z.input<typeof attachmentSchema>;
+/**
+ * Zod schema for {@link AttachmentMetadata}.
+ *
+ * Validates the persisted registry row. The embedded `attachment` field is
+ * validated recursively through the discriminated union.
+ */
+export declare const attachmentMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    sha256: z.ZodString;
+    attachment: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"local-file">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+        mime: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"url">;
+        url: z.ZodString;
+        cachedSha256: z.ZodOptional<z.ZodString>;
+        cachedAt: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"blob">;
+        sha256: z.ZodString;
+        storageKey: z.ZodString;
+        mime: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"llms-txt">;
+        source: z.ZodEnum<{
+            url: "url";
+            generated: "generated";
+        }>;
+        content: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodLiteral<"llmtxt-doc">;
+        slug: z.ZodString;
+        backend: z.ZodEnum<{
+            local: "local";
+            remote: "remote";
+        }>;
+        pinnedVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+    createdAt: z.ZodString;
+    refCount: z.ZodNumber;
+}, z.core.$strip>;
+/** Inferred TypeScript type from {@link attachmentMetadataSchema}. */
+export type AttachmentMetadataSchemaInput = z.input<typeof attachmentMetadataSchema>;
+/**
+ * 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 declare const attachmentRefSchema: z.ZodObject<{
+    attachmentId: z.ZodString;
+    ownerType: z.ZodEnum<{
+        pattern: "pattern";
+        task: "task";
+        session: "session";
+        observation: "observation";
+        decision: "decision";
+        learning: "learning";
+    }>;
+    ownerId: z.ZodString;
+    attachedAt: z.ZodString;
+    attachedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred TypeScript type from {@link attachmentRefSchema}. */
+export type AttachmentRefSchemaInput = z.input<typeof attachmentRefSchema>;
+//# sourceMappingURL=attachment-schema.d.ts.map

package/dist/attachment-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-schema.d.ts","sourceRoot":"","sources":["../src/attachment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;iBAUpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;iBAU9B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;iBAU/B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAQlC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;iBAYpC,CAAC;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAM3B,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAIrE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsBnC,CAAC;AAEH,sEAAsE;AACtE,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAIrF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;iBAmB9B,CAAC;AAEH,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/attachment-schema.js

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

package/dist/attachment-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-schema.js","sourceRoot":"","sources":["../src/attachment-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,kFAAkF;AAElF;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,8DAA8D;IAC9D,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,sDAAsD;IACtD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvC,CAAC,CAAC;AAEH,kFAAkF;AAElF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,kFAAkF;IAClF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,8CAA8C;IAC9C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;IAC7B,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,iDAAiD;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACrC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC,MAAM,CAAC;IAC/D,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACtB,qDAAqD;IACrD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,sDAAsD;IACtD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IAC9C,mDAAmD;IACnD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC1C,4DAA4D;IAC5D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC,MAAM,CAAC;IAChE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,0EAA0E;IAC1E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;IAC7B,sDAAsD;IACtD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,sBAAsB;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,iDAAiD;IACjD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACrC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAAsB,CAAC,MAAM,CAAC;IACnE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IAC3B,6CAA6C;IAC7C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACpC,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,2DAA2D;IAC3D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;CAC9B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,sBAAsB,CAAC,MAAM,CAAC;IACrE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;IAC7B,6CAA6C;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,uCAAuC;IACvC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACpC;;;;OAIG;IACH,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAEH,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC3D,yBAAyB;IACzB,mBAAmB;IACnB,oBAAoB;IACpB,uBAAuB;IACvB,yBAAyB;CAC1B,CAAC,CAAC;AAKH,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C;;;;OAIG;IACH,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,6EAA6E;IAC7E,UAAU,EAAE,gBAAgB;IAC5B,mCAAmC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACzC,CAAC,CAAC;AAKH,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,oEAAoE;IACpE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACxF,kDAAkD;IAClD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,mDAAmD;IACnD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC;;;;OAIG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC"}

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"}