Twitch-VOD-Manager/tasks/v5.0.0-plan-04-resume-foundation.md

Plan 04: Smart-Resume Foundation (Pillar 6 — Storage-Layer)

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans.

Goal: Chunk-Index-Schema in SQLite + sha1-Hash-Helper-Modul. Vorbereitung fuer den eigentlichen Smart-Resume-Mechanismus, der in einem Folgeplan in den bestehenden Recorder integriert wird. Plan 04 ist rein additiv — kein bestehender Code wird modifiziert.

Architecture: Neue Tabelle chunk_index (additiv im Schema). Hash-Helpers als pure infra-Modul (sha1 von Buffer + Streaming-File-Hash). Store-Modul (CRUD) folgt dem Pattern von token-store.

Tech Stack: Node crypto (sha1), better-sqlite3, vitest.

---

Out of Scope

• Integration in den bestehenden Recorder/Downloader (kommt in Plan 04b)
• Resume-Logik beim App-Start (Plan 04b)
• HLS-Manifest-Parser (vielleicht Plan 04b)

---

File Structure

Neu:

• src/main/infra/chunk-hash.ts — sha1-Helper (Buffer + File)
• src/main/infra/chunk-hash.test.ts
• src/main/domain/chunk-index-store.ts — CRUD auf chunk_index
• src/main/domain/chunk-index-store.test.ts

Modifiziert:

• src/main/infra/schema-v5.ts — neue Tabelle chunk_index
• src/main/infra/db.test.ts — 1 Test fuer neue Tabelle
• CLAUDE.md
• tasks/v5.0.0-roadmap.md

---

Tasks

Task 1: Schema-Extension chunk_index

In schema-v5.ts vor migrations_applied:

CREATE TABLE IF NOT EXISTS chunk_index (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    item_id TEXT NOT NULL,
    chunk_seq INTEGER NOT NULL,
    sha1_hex TEXT NOT NULL,
    bytes INTEGER NOT NULL,
    created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
    UNIQUE(item_id, chunk_seq)
);

CREATE INDEX IF NOT EXISTS idx_chunk_item ON chunk_index(item_id);
CREATE INDEX IF NOT EXISTS idx_chunk_sha1 ON chunk_index(sha1_hex);

• Schema-Konstante erweitern
• db.test.ts: 1 neuer Test fuer chunk_index
• Commit: feat(db): add chunk_index table (sha1 of recorded HLS segments)

---

Task 2: chunk-hash Modul

API:

export function hashBuffer(b: Buffer): string;          // sha1 hex
export function hashFile(filePath: string): Promise<string>;  // streaming sha1

Tests:

• known input → known sha1 (fixture: 'hello' → aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d)

• empty buffer → da39a3ee5e6b4b0d3255bfef95601890afd80709

• File hash via tmp file matches buffer hash for same content

• Large file (1MB+) hashes successfully

• Tests + Modul

• Commit: feat(resume): chunk-hash sha1 helpers (4 tests)

---

Task 3: chunk-index-store Modul

API:

export interface ChunkRecord {
    id: number;
    itemId: string;
    chunkSeq: number;
    sha1Hex: string;
    bytes: number;
    createdAt: number;
}

export interface ChunkIndexStore {
    record(itemId: string, chunkSeq: number, sha1Hex: string, bytes: number): ChunkRecord;
    listForItem(itemId: string): ChunkRecord[];
    countForItem(itemId: string): number;
    lookupBySha1(sha1Hex: string): ChunkRecord[];
    deleteForItem(itemId: string): number;  // returns deleted-row count
}

export function createChunkIndexStore(db: DbHandle): ChunkIndexStore;

Tests (mit MemorySecureStorage NICHT noetig — kein encryption hier):

1. record + listForItem
2. UNIQUE(item_id, chunk_seq) — zweimal gleicher (itemId, chunkSeq) → INSERT OR REPLACE (latest wins)
3. countForItem
4. lookupBySha1 (dedupe-Erkennung)
5. deleteForItem
6. Ordering — listForItem nach chunk_seq ASC
7. Bytes-Roundtrip

• Tests + Modul
• Commit: feat(resume): chunk-index-store CRUD (7 tests)

---

Task 4: Full Verification + Bump 5.0.0-alpha.3

• npm run test:e2e:release Exit 0 (unit jetzt >= 138)
• npm version 5.0.0-alpha.3 --no-git-tag-version
• Commit + Tag v5.0.0-alpha.3

---

Task 5: Docs

CLAUDE.md "Smart-Resume" Notiz:

Recorded HLS-Segments koennen mit sha1-Hash in chunk_index Tabelle protokolliert werden (src/main/domain/chunk-index-store.ts). Vorbereitung fuer Crash-Recovery + Integrity-Check; eigentliche Integration in den Recorder kommt in Folgeplan.

Roadmap: Plan 04 → DONE, Plan 04b "Resume Integration" als naechster Eintrag.

---

Done-Definition

1. chunk_index Tabelle existiert nach openDatabase
2. hashBuffer + hashFile getestet (known-input + roundtrip)
3. ChunkIndexStore CRUD getestet
4. test:e2e:release Exit 0

5. = 12 neue unit tests

6. v5.0.0-alpha.3 getaggt