@krischoichoi/channel-files 0.6.0

package/lib/catalog/store.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+import { type AttachmentCatalogRecordV2 } from './types.js';
+/** Errors raised for programmer misuse (an invalid record on write). */
+export declare class CatalogStoreError extends Error {
+    readonly code: 'CATALOG_INVALID_RECORD';
+    constructor(message: string);
+}
+/** Stable logical IDs are generated as `att-${randomUUID()}` by the pipeline. */
+export declare const attachmentIdSchema: z.ZodString;
+/** Zod schema for `AttachmentCatalogRecordV2` (read-time validation). */
+export declare const attachmentCatalogRecordV2Schema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    attachmentId: z.ZodString;
+    owner: z.ZodObject<{
+        sessionId: z.ZodString;
+    }, z.core.$strip>;
+    provenance: z.ZodObject<{
+        channelId: z.ZodString;
+        accountId: z.ZodString;
+        conversationId: z.ZodString;
+        conversationType: z.ZodOptional<z.ZodEnum<{
+            dm: "dm";
+            group: "group";
+        }>>;
+        threadId: z.ZodOptional<z.ZodString>;
+        messageId: z.ZodString;
+    }, z.core.$strip>;
+    file: z.ZodObject<{
+        kind: z.ZodEnum<{
+            file: "file";
+            audio: "audio";
+            video: "video";
+        }>;
+        name: z.ZodString;
+        mimeType: z.ZodOptional<z.ZodString>;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>;
+    storage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        backend: z.ZodLiteral<"channel-v1">;
+    }, z.core.$strip>, z.ZodObject<{
+        backend: z.ZodLiteral<"harness-native">;
+        nativeId: z.ZodString;
+    }, z.core.$strip>], "backend">;
+    migration: z.ZodOptional<z.ZodObject<{
+        sourceBackend: z.ZodOptional<z.ZodLiteral<"channel-v1">>;
+        migratedAt: z.ZodOptional<z.ZodNumber>;
+        verifiedAt: z.ZodOptional<z.ZodNumber>;
+        legacyRetained: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    createdAt: z.ZodNumber;
+}, z.core.$strip>;
+/** Type guard over the zod schema (never trusts an unparsed object). */
+export declare function isAttachmentCatalogRecordV2(value: unknown): value is AttachmentCatalogRecordV2;
+/**
+ * Catalog v2 root — a sibling of the v1 tree under the shared attachments
+ * root (`<channelData>/attachments/catalog/v2`). Never collides with
+ * `attachments/v1/sessions/...`.
+ */
+export declare function resolveCatalogRoot(): string;
+export interface CatalogStoreOptions {
+    /**
+     * Catalog v2 root; records live at `<root>/by-id/<attachmentId>.json`.
+     * Defaults to `resolveCatalogRoot()`.
+     */
+    root?: string;
+    /** Corrupt-record diagnostics; defaults to `console.warn`. */
+    log?: (message: string) => void;
+}
+/**
+ * Patch accepted by `CatalogStore.update` — deliberately limited to the
+ * fields lazy migration transitions: the storage locator and the migration
+ * state block.
+ */
+export interface CatalogRecordPatch {
+    storage?: AttachmentCatalogRecordV2['storage'];
+    migration?: AttachmentCatalogRecordV2['migration'];
+}
+/**
+ * Filesystem-backed catalog v2 store. All methods are non-fatal on missing
+ * data: `get`/`update` return `undefined`, `list` returns `[]`, and no catalog
+ * method breaks the legacy fallback when the catalog is absent or corrupt.
+ */
+export declare class CatalogStore {
+    private readonly root;
+    private readonly byIdDir;
+    private readonly log;
+    constructor(options?: CatalogStoreOptions);
+    /**
+     * Atomically publish one record. The record is validated with zod
+     * `safeParse` before anything is written; an invalid record raises
+     * `CatalogStoreError` and leaves no file behind.
+     */
+    put(record: AttachmentCatalogRecordV2): Promise<void>;
+    /**
+     * Read one record. Returns `undefined` for a missing attachment id AND for
+     * a corrupt record (invalid JSON or schema mismatch — logged, never thrown).
+     */
+    get(attachmentId: string): Promise<AttachmentCatalogRecordV2 | undefined>;
+    private readRecord;
+    /**
+     * List all readable records, sorted by `attachmentId`. Corrupt and
+     * transient (`.tmp`) files are skipped; a missing catalog dir returns `[]`.
+     */
+    list(): Promise<AttachmentCatalogRecordV2[]>;
+    /**
+     * Apply a migration-state patch atomically: read current, merge `storage` /
+     * `migration` onto it, write back under a writer lock.
+     * Returns the merged record; `undefined` when the attachment id is missing
+     * (non-fatal — nothing is written). A merged record that fails zod
+     * validation raises `CatalogStoreError` (programmer misuse).
+     */
+    update(attachmentId: string, patch: CatalogRecordPatch): Promise<AttachmentCatalogRecordV2 | undefined>;
+    private recordFile;
+    private writeRecord;
+    /** Validate a record before persisting; never writes an unparsed object. */
+    private parseRecord;
+    /** Parse + validate a record read back from disk (corrupt -> undefined). */
+    private parseFileRecord;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/catalog/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/catalog/store.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAEpB,wEAAwE;AACxE,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;gBAC5B,OAAO,EAAE,MAAM;CAK5B;AAED,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,aAG9B,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkC1C,CAAC;AAEH,wEAAwE;AACxE,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,yBAAyB,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,yBAAyB,CAAC,SAAS,CAAC,CAAC;IAC/C,SAAS,CAAC,EAAE,yBAAyB,CAAC,WAAW,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAEpC,OAAO,GAAE,mBAAwB;IAM7C;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D;;;OAGG;IACG,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC;YAKjE,UAAU;IAaxB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAiBlD;;;;;;OAMG;IACG,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC;IAiBjD,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,WAAW;IAUnB,4EAA4E;IAC5E,OAAO,CAAC,WAAW;IAWnB,4EAA4E;IAC5E,OAAO,CAAC,eAAe;CAsBxB"}

package/lib/catalog/store.js

@@ -0,0 +1,227 @@
+/**
+ * Attachment Catalog v2 store.
+ *
+ * Filesystem layout:
+ *
+ * \`\`\`
+ * attachments/
+ *   v1/                         # legacy tree — NEVER touched by this module
+ *   catalog/
+ *     v2/
+ *       by-id/
+ *         <attachmentId>.json   # one atomic JSON file per record
+ * \`\`\`
+ *
+ * Every write uses Harness's public `writeFileAtomic`; read-modify-write
+ * updates also use its cross-process writer lock. A reader never observes a
+ * half-written record. `get` treats missing AND corrupt records the same way — it returns
+ * `undefined` and never throws; corrupt JSON is logged and skipped. This is
+ * deliberate: the catalog is an OPTIONAL index — "catalog miss MUST be a
+ * non-fatal fallback", nothing may break if the catalog directory is absent.
+ * The legacy `attachments/v1` tree remains the authoritative fallback for
+ * reads.
+ *
+ * Records are validated with zod `safeParse` on BOTH write and read
+ * (AGENTS.md 5.4 — trusted-boundary payloads must be parsed, never cast).
+ * Unknown extra fields are tolerated on read (zod `z.object` strips them);
+ * they never make a record corrupt.
+ */
+import { mkdir, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { z } from 'zod';
+import { resolveAttachmentsRoot } from '../paths.js';
+import { CATALOG_SCHEMA_VERSION, } from './types.js';
+/** Errors raised for programmer misuse (an invalid record on write). */
+export class CatalogStoreError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = 'CatalogStoreError';
+        this.code = 'CATALOG_INVALID_RECORD';
+    }
+}
+/** Stable logical IDs are generated as `att-${randomUUID()}` by the pipeline. */
+export const attachmentIdSchema = z.string().regex(/^att-[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i, 'attachmentId must use the att-UUID format');
+/** Zod schema for `AttachmentCatalogRecordV2` (read-time validation). */
+export const attachmentCatalogRecordV2Schema = z.object({
+    schemaVersion: z.literal(CATALOG_SCHEMA_VERSION),
+    attachmentId: attachmentIdSchema,
+    owner: z.object({
+        sessionId: z.string().min(1),
+    }),
+    provenance: z.object({
+        channelId: z.string().min(1),
+        accountId: z.string().min(1),
+        conversationId: z.string().min(1),
+        conversationType: z.enum(['dm', 'group']).optional(),
+        threadId: z.string().optional(),
+        messageId: z.string().min(1),
+    }),
+    file: z.object({
+        kind: z.enum(['file', 'audio', 'video']),
+        name: z.string(),
+        mimeType: z.string().optional(),
+        bytes: z.number().int().nonnegative(),
+        sha256: z.string().regex(/^[0-9a-f]{64}$/),
+    }),
+    storage: z.discriminatedUnion('backend', [
+        z.object({ backend: z.literal('channel-v1') }),
+        z.object({ backend: z.literal('harness-native'), nativeId: z.string().min(1) }),
+    ]),
+    migration: z
+        .object({
+        sourceBackend: z.literal('channel-v1').optional(),
+        migratedAt: z.number().optional(),
+        verifiedAt: z.number().optional(),
+        legacyRetained: z.boolean().optional(),
+    })
+        .optional(),
+    createdAt: z.number(),
+});
+/** Type guard over the zod schema (never trusts an unparsed object). */
+export function isAttachmentCatalogRecordV2(value) {
+    return attachmentCatalogRecordV2Schema.safeParse(value).success;
+}
+/**
+ * Catalog v2 root — a sibling of the v1 tree under the shared attachments
+ * root (`<channelData>/attachments/catalog/v2`). Never collides with
+ * `attachments/v1/sessions/...`.
+ */
+export function resolveCatalogRoot() {
+    return join(resolveAttachmentsRoot(), '..', 'catalog', 'v2');
+}
+/**
+ * Filesystem-backed catalog v2 store. All methods are non-fatal on missing
+ * data: `get`/`update` return `undefined`, `list` returns `[]`, and no catalog
+ * method breaks the legacy fallback when the catalog is absent or corrupt.
+ */
+export class CatalogStore {
+    root;
+    byIdDir;
+    log;
+    constructor(options = {}) {
+        this.root = options.root ?? resolveCatalogRoot();
+        this.byIdDir = join(this.root, 'by-id');
+        this.log = options.log ?? ((message) => console.warn('[channel-files:catalog] ' + message));
+    }
+    /**
+     * Atomically publish one record. The record is validated with zod
+     * `safeParse` before anything is written; an invalid record raises
+     * `CatalogStoreError` and leaves no file behind.
+     */
+    async put(record) {
+        const parsed = this.parseRecord(record);
+        await mkdir(this.byIdDir, { recursive: true, mode: 0o700 });
+        const file = this.recordFile(parsed.attachmentId);
+        await withFileLock(file, () => this.writeRecord(file, parsed));
+    }
+    /**
+     * Read one record. Returns `undefined` for a missing attachment id AND for
+     * a corrupt record (invalid JSON or schema mismatch — logged, never thrown).
+     */
+    async get(attachmentId) {
+        if (!attachmentIdSchema.safeParse(attachmentId).success)
+            return undefined;
+        return this.readRecord(attachmentId);
+    }
+    async readRecord(attachmentId) {
+        let text;
+        try {
+            text = await readFile(this.recordFile(attachmentId), 'utf8');
+        }
+        catch {
+            // Missing record (or missing catalog dir) is a normal, non-fatal miss.
+            return undefined;
+        }
+        return this.parseFileRecord(text, attachmentId);
+    }
+    /**
+     * List all readable records, sorted by `attachmentId`. Corrupt and
+     * transient (`.tmp`) files are skipped; a missing catalog dir returns `[]`.
+     */
+    async list() {
+        let entries;
+        try {
+            entries = await readdir(this.byIdDir);
+        }
+        catch {
+            return [];
+        }
+        const records = [];
+        for (const name of entries) {
+            if (!name.endsWith('.json'))
+                continue; // ignore transient .tmp files
+            const attachmentId = name.slice(0, -'.json'.length);
+            const record = await this.get(attachmentId);
+            if (record !== undefined)
+                records.push(record);
+        }
+        return records.sort((a, b) => a.attachmentId.localeCompare(b.attachmentId));
+    }
+    /**
+     * Apply a migration-state patch atomically: read current, merge `storage` /
+     * `migration` onto it, write back under a writer lock.
+     * Returns the merged record; `undefined` when the attachment id is missing
+     * (non-fatal — nothing is written). A merged record that fails zod
+     * validation raises `CatalogStoreError` (programmer misuse).
+     */
+    async update(attachmentId, patch) {
+        if (!attachmentIdSchema.safeParse(attachmentId).success)
+            return undefined;
+        await mkdir(this.byIdDir, { recursive: true, mode: 0o700 });
+        const file = this.recordFile(attachmentId);
+        return withFileLock(file, async () => {
+            const current = await this.readRecord(attachmentId);
+            if (current === undefined)
+                return undefined;
+            const merged = this.parseRecord({
+                ...current,
+                ...(patch.storage !== undefined ? { storage: patch.storage } : {}),
+                ...(patch.migration !== undefined ? { migration: patch.migration } : {}),
+            });
+            await this.writeRecord(file, merged);
+            return merged;
+        });
+    }
+    recordFile(attachmentId) {
+        return join(this.byIdDir, attachmentId + '.json');
+    }
+    writeRecord(file, record) {
+        return writeFileAtomic(file, JSON.stringify(record, null, 2), {
+            mode: 0o600,
+            dirMode: 0o700,
+        });
+    }
+    /** Validate a record before persisting; never writes an unparsed object. */
+    parseRecord(record) {
+        const result = attachmentCatalogRecordV2Schema.safeParse(record);
+        if (!result.success) {
+            throw new CatalogStoreError('invalid catalog record for \'' + (record?.attachmentId ?? '?') + '\': '
+                + result.error.message);
+        }
+        return result.data;
+    }
+    /** Parse + validate a record read back from disk (corrupt -> undefined). */
+    parseFileRecord(text, attachmentId) {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            this.log('corrupt catalog record (invalid JSON) for ' + attachmentId);
+            return undefined;
+        }
+        const result = attachmentCatalogRecordV2Schema.safeParse(value);
+        if (!result.success) {
+            this.log('corrupt catalog record (schema mismatch) for ' + attachmentId);
+            return undefined;
+        }
+        if (result.data.attachmentId !== attachmentId) {
+            this.log('corrupt catalog record (attachmentId mismatch) for ' + attachmentId);
+            return undefined;
+        }
+        return result.data;
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/catalog/store.js.map

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

package/lib/catalog/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Attachment Catalog v2.
+ *
+ * The catalog is a NEW logical-id -> backend-locator map kept SEPARATE from
+ * the legacy `attachments/v1` tree, which is never rewritten in place. One
+ * record is written per attachment at:
+ *
+ * \`\`\`
+ * attachments/
+ *   v1/                       # legacy tree — fully untouched
+ *   catalog/
+ *     v2/
+ *       by-id/
+ *         <attachmentId>.json # AttachmentCatalogRecordV2
+ * \`\`\`
+ *
+ * The record deliberately carries NO transient platform state — no
+ * `resourceRef`, no provider URL, no token, no `downloadCode` (same rule as
+ * `StoredChannelAsset`). It exists so the resolve flow can later pick a
+ * backend (Native-first + legacy fallback) without parsing v1 metadata, and
+ * so lazy migration can record the channel-v1 -> harness-native transition
+ * explicitly.
+ *
+ * `attachmentId` is the stable logical id (`att-<uuid>`) and is NEVER a path
+ * or a Harness native id.
+ */
+/** Schema version of `AttachmentCatalogRecordV2` (mirrors the v2 directory). */
+export declare const CATALOG_SCHEMA_VERSION: 2;
+/** Binary kinds a generic (non-image) attachment record may describe. */
+export type CatalogFileKind = 'file' | 'audio' | 'video';
+/** Storage backends a catalog record may point at. */
+export type CatalogStorageBackend = 'channel-v1' | 'harness-native';
+/**
+ * One catalog v2 record. `storage` discriminates where the real bytes live;
+ * `migration` (when present) records that a copy + verify transition happened
+ * and that the legacy backend was retained.
+ */
+export interface AttachmentCatalogRecordV2 {
+    schemaVersion: typeof CATALOG_SCHEMA_VERSION;
+    /** Stable logical attachment id (`att-<uuid>`); never a path or native id. */
+    attachmentId: string;
+    /** Session ACL owner — the ONLY identity that gates read access. */
+    owner: {
+        sessionId: string;
+    };
+    /** De-identified platform provenance (debug / migration only). */
+    provenance: {
+        channelId: string;
+        accountId: string;
+        conversationId: string;
+        conversationType?: 'dm' | 'group';
+        threadId?: string;
+        messageId: string;
+    };
+    file: {
+        kind: CatalogFileKind;
+        name: string;
+        mimeType?: string;
+        /** Final byte length (computed by the store that wrote the bytes). */
+        bytes: number;
+        sha256: string;
+    };
+    storage: {
+        backend: 'channel-v1';
+    } | {
+        backend: 'harness-native';
+        nativeId: string;
+    };
+    /**
+     * Lazy-migration state. Present once a legacy record has
+     * been copied to the native backend, read back and hash-verified.
+     * `legacyRetained` must stay `true` — migration is copy + verify,
+     * never move/delete.
+     */
+    migration?: {
+        sourceBackend?: 'channel-v1';
+        migratedAt?: number;
+        verifiedAt?: number;
+        legacyRetained?: boolean;
+    };
+    createdAt: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/catalog/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAC;AAEjD,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzD,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,OAAO,sBAAsB,CAAC;IAC7C,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,KAAK,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,kEAAkE;IAClE,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC;QAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,IAAI,EAAE;QACJ,IAAI,EAAE,eAAe,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,sEAAsE;QACtE,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,EACH;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,GACzB;QAAE,OAAO,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QACV,aAAa,CAAC,EAAE,YAAY,CAAC;QAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/lib/catalog/types.js

@@ -0,0 +1,29 @@
+/**
+ * Attachment Catalog v2.
+ *
+ * The catalog is a NEW logical-id -> backend-locator map kept SEPARATE from
+ * the legacy `attachments/v1` tree, which is never rewritten in place. One
+ * record is written per attachment at:
+ *
+ * \`\`\`
+ * attachments/
+ *   v1/                       # legacy tree — fully untouched
+ *   catalog/
+ *     v2/
+ *       by-id/
+ *         <attachmentId>.json # AttachmentCatalogRecordV2
+ * \`\`\`
+ *
+ * The record deliberately carries NO transient platform state — no
+ * `resourceRef`, no provider URL, no token, no `downloadCode` (same rule as
+ * `StoredChannelAsset`). It exists so the resolve flow can later pick a
+ * backend (Native-first + legacy fallback) without parsing v1 metadata, and
+ * so lazy migration can record the channel-v1 -> harness-native transition
+ * explicitly.
+ *
+ * `attachmentId` is the stable logical id (`att-<uuid>`) and is NEVER a path
+ * or a Harness native id.
+ */
+/** Schema version of `AttachmentCatalogRecordV2` (mirrors the v2 directory). */
+export const CATALOG_SCHEMA_VERSION = 2;
+//# sourceMappingURL=types.js.map

package/lib/catalog/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+export * from './attachments/index.js';
+export * from './attachment-resolver.js';
+export * from './paths.js';
+export * from './service.js';
+export * from './catalog/types.js';
+export * from './catalog/store.js';
+export * from './catalog/legacy-backfill.js';
+export * from './backends/harness-native.js';
+export * from './migration/verify.js';
+export * from './migration/migrate-on-read.js';
+export { name, apply } from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/lib/index.js

@@ -0,0 +1,12 @@
+export * from './attachments/index.js';
+export * from './attachment-resolver.js';
+export * from './paths.js';
+export * from './service.js';
+export * from './catalog/types.js';
+export * from './catalog/store.js';
+export * from './catalog/legacy-backfill.js';
+export * from './backends/harness-native.js';
+export * from './migration/verify.js';
+export * from './migration/migrate-on-read.js';
+export { name, apply } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/lib/migration/migrate-on-read.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Lazy migration ON READ.
+ *
+ * NOT YET WIRED into the resolve flow. This module is standalone, default-off
+ * infrastructure: the first release ships with `migration.nativeOnRead =
+ * false` and the resolver turn-on is a later wave. Only when `enabled` is true
+ * AND the running Harness host reports a generic attachment capability does a
+ * read of a legacy record trigger a copy.
+ *
+ * Contract:
+ *
+ * - never MOVE or DELETE legacy bytes — migration is copy + verify + retain
+ *   (`legacyRetained: true`); deleting legacy bytes is GC's job, separate from
+ *   the migration transaction;
+ * - copy to native -> read back -> verify sha256 + bytes -> catalog switch;
+ * - ANY failure (copy fail, read-back fail, hash mismatch, length mismatch,
+ *   catalog get/update fail or throw, missing catalog record) ->
+ *   `{ outcome: 'legacy-authoritative' }`: legacy remains authoritative and
+ *   readable, the catalog is unchanged;
+ * - a record already at `harness-native` is an idempotent no-op
+ *   (`{ outcome: 'migrated' }`, nothing copied).
+ */
+import type { NativeGenericAttachmentCapability } from '../backends/harness-native.js';
+import type { CatalogStore } from '../catalog/store.js';
+import type { AttachmentCatalogRecordV2 } from '../catalog/types.js';
+export interface MigrationOptions {
+    /**
+     * Master switch; defaults to `false` in release ('migration.nativeOnRead'
+     * policy). Migration never runs unless explicitly enabled.
+     */
+    enabled: boolean;
+    /** Capability probe result of the running Harness host. */
+    native: NativeGenericAttachmentCapability;
+    /**
+     * Copy the record's bytes into the native backend; resolves to the native
+     * id. Must never move or delete the legacy bytes.
+     */
+    copyToNative: (record: AttachmentCatalogRecordV2) => Promise<string>;
+    /** Read the copied bytes back from the native backend for verification. */
+    readBackNative: (nativeId: string) => Promise<Uint8Array>;
+    /** Catalog v2 used for the locator transition (get + update only). */
+    catalog: Pick<CatalogStore, 'get' | 'update'>;
+}
+export type MigrateOnReadOutcome = 'skipped-legacy' | 'migrated' | 'legacy-authoritative';
+export interface MigrateOnReadResult {
+    outcome: MigrateOnReadOutcome;
+}
+/**
+ * Attempt a lazy copy+verify migration of one legacy catalog record.
+ *
+ * @returns
+ * - `skipped-legacy` — migration disabled or native capability unavailable;
+ *   the caller keeps serving from the legacy backend untouched.
+ * - `migrated` — native copy verified (sha256 + bytes) and the catalog now
+ *   points at `harness-native` with the migration block recorded; legacy
+ *   bytes retained.
+ * - `legacy-authoritative` — any failure; legacy backend stays authoritative
+ *   and the catalog is unchanged.
+ */
+export declare function migrateOnRead(options: MigrationOptions, record: AttachmentCatalogRecordV2): Promise<MigrateOnReadResult>;
+//# sourceMappingURL=migrate-on-read.d.ts.map

package/lib/migration/migrate-on-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-on-read.d.ts","sourceRoot":"","sources":["../../src/migration/migrate-on-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAGrE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,MAAM,EAAE,iCAAiC,CAAC;IAC1C;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,yBAAyB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,2EAA2E;IAC3E,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1D,sEAAsE;IACtE,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;CAC/C;AAED,MAAM,MAAM,oBAAoB,GAC5B,gBAAgB,GAChB,UAAU,GACV,sBAAsB,CAAC;AAE3B,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,mBAAmB,CAAC,CA6C9B"}

package/lib/migration/migrate-on-read.js

@@ -0,0 +1,61 @@
+import { readBackVerified } from './verify.js';
+/**
+ * Attempt a lazy copy+verify migration of one legacy catalog record.
+ *
+ * @returns
+ * - `skipped-legacy` — migration disabled or native capability unavailable;
+ *   the caller keeps serving from the legacy backend untouched.
+ * - `migrated` — native copy verified (sha256 + bytes) and the catalog now
+ *   points at `harness-native` with the migration block recorded; legacy
+ *   bytes retained.
+ * - `legacy-authoritative` — any failure; legacy backend stays authoritative
+ *   and the catalog is unchanged.
+ */
+export async function migrateOnRead(options, record) {
+    if (!options.enabled || !options.native.available) {
+        return { outcome: 'skipped-legacy' };
+    }
+    try {
+        // The catalog is the authoritative state: re-read it so the transition
+        // cannot clobber a concurrent one, and so a missing catalog record fails
+        // safe to legacy-authoritative (catalog miss is never fatal).
+        const current = await options.catalog.get(record.attachmentId);
+        if (current === undefined)
+            return { outcome: 'legacy-authoritative' };
+        if (current.storage.backend === 'harness-native') {
+            // Already migrated — idempotent no-op, nothing copied.
+            return { outcome: 'migrated' };
+        }
+        // 1) COPY (never move/delete the legacy bytes).
+        const nativeId = await options.copyToNative(current);
+        // 2) READ BACK + VERIFY sha256 and byte length.
+        const verified = await readBackVerified({
+            readBack: () => options.readBackNative(nativeId),
+            expectedSha256: current.file.sha256,
+            expectedBytes: current.file.bytes,
+        });
+        if (!verified)
+            return { outcome: 'legacy-authoritative' };
+        // 3) CATALOG SWITCH to harness-native + record the migration state
+        //    (sourceBackend channel-v1, legacyRetained: true).
+        const now = Date.now();
+        const updated = await options.catalog.update(current.attachmentId, {
+            storage: { backend: 'harness-native', nativeId },
+            migration: {
+                sourceBackend: 'channel-v1',
+                migratedAt: now,
+                verifiedAt: now,
+                legacyRetained: true,
+            },
+        });
+        if (updated === undefined)
+            return { outcome: 'legacy-authoritative' };
+        return { outcome: 'migrated' };
+    }
+    catch {
+        // Copy fail, read-back fail, catalog get/update fail: legacy stays
+        // authoritative, catalog unchanged, legacy bytes untouched.
+        return { outcome: 'legacy-authoritative' };
+    }
+}
+//# sourceMappingURL=migrate-on-read.js.map

package/lib/migration/migrate-on-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-on-read.js","sourceRoot":"","sources":["../../src/migration/migrate-on-read.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA8B/C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAyB,EACzB,MAAiC;IAEjC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IACvC,CAAC;IACD,IAAI,CAAC;QACH,uEAAuE;QACvE,yEAAyE;QACzE,8DAA8D;QAC9D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC/D,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;QACtE,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,KAAK,gBAAgB,EAAE,CAAC;YACjD,uDAAuD;YACvD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;QACjC,CAAC;QAED,gDAAgD;QAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAErD,gDAAgD;QAChD,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC;YACtC,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC;YAChD,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM;YACnC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;QAE1D,mEAAmE;QACnE,uDAAuD;QACvD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE;YACjE,OAAO,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE;YAChD,SAAS,EAAE;gBACT,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE,GAAG;gBACf,UAAU,EAAE,GAAG;gBACf,cAAc,EAAE,IAAI;aACrB;SACF,CAAC,CAAC;QACH,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;QACtE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,4DAA4D;QAC5D,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC"}