project-mgr 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.1 - 2026-10-16
+
+### Changed
+
+- Prefer an installed `pmgr` in the Skill and remove automatic `npx @latest` execution from examples.
+- Require explicit status values and evidence-backed historical backfills without a minimum entry count.
+- Document database permission handling, stable ledger paths, and read-back verification after writes.
+
+This release updates Skill guidance only; CLI behavior and storage architecture are unchanged.
+
+## 0.3.0 - 2026-10-16
+
+### Added
+
+- Explicit completion of multiple predecessor activities, append-only revocation, and completion-source links in the activity feed.
+- Independent Current/Superseded markers, preserved original snapshot details, and a direct entry route with a return-to-list control.
+- Migration 3 adds portable entry and event identities and rejects obsolete writers that omit entry UUIDs.
+
+### Changed
+
+- Export is now a version-2 bundle rather than a JSON array or entry-per-line JSONL. JSONL emits one complete bundle per line. Existing consumers must adapt; legacy imports remain supported.
+- Imports preserve completion history and recording times, reject conflicting identities atomically, and deduplicate version-2 re-imports. Independently migrated legacy databases may require restoring into a fresh database due to differing UUIDs.
+
+### Fixed
+
+- Invalid percent-encoding in entry/project detail routes returns 400 instead of 500.
+
 ## 0.2.0 - 2026-08-07
 
 ### Added

package/README.md

@@ -298,3 +298,24 @@ pnpm build
 ```
 
 Coverage thresholds for statements, branches, functions, and lines are all 100%. See the [architecture document](docs/architecture.md) for the detailed design.
+
+## Completing earlier activities
+
+Project status and activity completion are separate. Inspect `pmgr history --project demo --json` before linking entries. `status` is the original snapshot; `effectiveStatus` includes explicit follow-up completion, and `isCurrent` identifies the latest project snapshot. Missing `completedBy` does not mean an entry is unfinished.
+
+```bash
+# One update completes multiple older entries (local numeric IDs or portable UUIDs).
+pmgr add --project demo --status active --summary "Deployment accepted" \
+  --completes 12 --completes 15 --source agent --json
+# Link an existing follow-up, or correct an erroneous link without deleting history.
+pmgr complete --entry 12 --by 18 --source agent --json
+pmgr revoke-completion --entry 12 --by 18 --reason "Acceptance still pending" --source agent --json
+```
+
+Only link entries whose entire outstanding work is resolved, including blockers and next steps. Same-project links require a strictly later follow-up occurrence time; equal-time links are rejected. A target has one active completion source. Repeating that link is a no-op; revoke before replacing it. `add --completes` writes the snapshot, metadata, and links atomically. Existing history is not automatically reconciled.
+
+Activity cards display Completed with a follow-up link and retain original details in an expandable section. Current/Superseded identifies snapshot recency independently of completion. `/api/entries/<id-or-uid>` and `/?entry=<uid>` open an entry even outside the initial activity page. Date filters select snapshots; completion annotations reflect today's result. `at` continues returning the historical project snapshot without completion evidence; historical completion queries are deferred.
+
+Export now emits a version-2 bundle `{ "version": 2, "entries": [...], "completions": [...] }`. JSONL emits one complete bundle per line. Entries retain UUIDs and recording times; events retain UUIDs and per-target predecessor links, including revocations. Import accepts legacy entry objects/arrays/JSONL and version-2 bundles, checks identity conflicts, and applies each file atomically. Re-importing the same bundle is idempotent. Event order is significant: import events in exported order; divergent histories fail instead of silently merging. Older clients cannot import version-2 bundles. Migration adds UUIDs to existing snapshots without changing their content.
+
+Independently migrated copies of legacy data receive different UUIDs. Cross-import may fail on an existing `externalRef`; no implicit identity adoption occurs. Restore a bundle into a fresh database for a faithful migration. Older writers are rejected if they omit UUIDs. With an existing `externalRef`, `add` retains its existing snapshot and applies explicitly supplied `--completes` links to that snapshot; identical active links are no-ops. Use `complete` to make after-the-fact reconciliation explicit.

package/dist/cli.js

@@ -2,8 +2,8 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { addStatus, at, current, history, importStatuses, listProjects, openLedger, parseTime, setProjectMetadata, startServer, toPortableStatusEntry, ValidationError, } from "./index.js";
-const repeats = new Set(["next", "blocker", "decision", "tag"]);
+import { addStatus, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
+const repeats = new Set(["next", "blocker", "decision", "tag", "completes"]);
 function parse(argv) {
     const command = [];
     const flags = Object.create(null);
@@ -53,9 +53,12 @@ const allowedFlags = new Map([
             "at",
             "source",
             "external-ref",
+            "completes",
             "json",
         ]),
     ],
+    ["complete", new Set(["entry", "by", "reason", "source", "json"])],
+    ["revoke-completion", new Set(["entry", "by", "reason", "source", "json"])],
     ["import", new Set(["file", "json"])],
     ["current", new Set(["project", "json"])],
     ["projects", new Set(["query", "json"])],
@@ -85,7 +88,7 @@ function validateInvocation(command, flags) {
     const action = command[statusCommand ? 1 : 0];
     const allowed = typeof action === "string" ? allowedFlags.get(action) : undefined;
     if (typeof action !== "string" || !allowed)
-        throw new ValidationError("usage: pmgr <add|import|current|projects|list|set-project|history|at|export|serve> (or: pmgr status <action>)");
+        throw new ValidationError("usage: pmgr <add|complete|revoke-completion|import|current|projects|list|set-project|history|at|export|serve> (or: pmgr status <action>)");
     const positional = command.slice(statusCommand ? 2 : 1);
     if (action === "import") {
         if (positional.length > 1)
@@ -124,7 +127,7 @@ function output(value, json, write) {
         write(`${JSON.stringify(value)}\n`);
     else if (Array.isArray(value)) {
         const rows = value
-            .map((entry) => `${entry.project}\t${entry.status}\t${entry.occurredAt}\t${entry.summary}`)
+            .map((entry) => `${entry.project}\t${entry.effectiveStatus ?? entry.status}\t${entry.occurredAt}\t${entry.summary}${entry.completedBy ? ` (completed by #${entry.completedBy.id}; original: ${entry.status})` : ""}`)
             .join("\n");
         write(`${rows || "No entries found."}\n`);
     }
@@ -188,26 +191,35 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                 const project = stringFlag(flags, "project", true);
                 const description = stringFlag(flags, "description");
                 const notes = stringFlag(flags, "notes");
-                if (description !== undefined || notes !== undefined) {
-                    setProjectMetadata(db, { project, description, notes });
-                }
-                output(addStatus(db, {
-                    project,
-                    status: stringFlag(flags, "status"),
-                    summary: stringFlag(flags, "summary", true),
-                    progress: stringFlag(flags, "progress"),
-                    blockers: listFlag(flags, "blocker"),
-                    nextSteps: listFlag(flags, "next"),
-                    decisions: listFlag(flags, "decision"),
-                    tags: listFlag(flags, "tag"),
-                    occurredAt: stringFlag(flags, "at"),
-                    source: stringFlag(flags, "source"),
-                    externalRef: stringFlag(flags, "external-ref"),
-                }).entry, json, write);
+                const result = db
+                    .transaction(() => {
+                    if (description !== undefined || notes !== undefined) {
+                        setProjectMetadata(db, { project, description, notes });
+                    }
+                    return addStatus(db, {
+                        project,
+                        status: stringFlag(flags, "status"),
+                        summary: stringFlag(flags, "summary", true),
+                        progress: stringFlag(flags, "progress"),
+                        blockers: listFlag(flags, "blocker"),
+                        nextSteps: listFlag(flags, "next"),
+                        decisions: listFlag(flags, "decision"),
+                        tags: listFlag(flags, "tag"),
+                        occurredAt: stringFlag(flags, "at"),
+                        source: stringFlag(flags, "source"),
+                        externalRef: stringFlag(flags, "external-ref"),
+                    }, "human", listFlag(flags, "completes")).entry;
+                })
+                    .immediate();
+                output(result, json, write);
                 break;
             }
+            case "complete":
+            case "revoke-completion":
+                output(changeCompletion(db, stringFlag(flags, "entry", true), stringFlag(flags, "by", true), action === "complete" ? "complete" : "revoke", stringFlag(flags, "reason"), (stringFlag(flags, "source") ?? "human")), json, write);
+                break;
             case "import":
-                output(importStatuses(db, imported(stringFlag(flags, "file") ??
+                output(importLedger(db, imported(stringFlag(flags, "file") ??
                     command[command[0] === "status" ? 2 : 1] ??
                     "")).map((result) => result.entry), json, write);
                 break;
@@ -261,19 +273,12 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                 output(at(db, stringFlag(flags, "project", true), parseTime(stringFlag(flags, "at", true), "at")) ?? null, json, write);
                 break;
             case "export": {
-                const entries = history(db, stringFlag(flags, "project"), {
-                    limit: -1,
-                })
-                    .reverse()
-                    .map(toPortableStatusEntry);
+                const bundle = exportLedger(db, stringFlag(flags, "project"));
                 const format = stringFlag(flags, "format") ?? "json";
-                if (format === "jsonl")
-                    write(entries.map((entry) => JSON.stringify(entry)).join("\n") +
-                        (entries.length ? "\n" : ""));
-                else if (format === "json")
-                    output(entries, true, write);
-                else
+                if (format !== "json" && format !== "jsonl")
                     throw new ValidationError("--format must be json or jsonl");
+                // JSONL contains one versioned bundle per line, preserving event order.
+                output(bundle, true, write);
                 break;
             }
             case "serve": {

package/dist/db.d.ts

@@ -17,9 +17,41 @@ export declare function setProjectMetadata(db: Ledger, value: unknown): ProjectM
 export declare function listProjects(db: Ledger, options?: {
     query?: string;
 }): ProjectOverview[];
-export declare function addStatus(db: Ledger, value: unknown, defaultSource?: Source): InsertResult;
+export declare function addStatus(db: Ledger, value: unknown, defaultSource?: Source, completes?: string[]): InsertResult;
 export declare function importStatuses(db: Ledger, values: unknown[]): InsertResult[];
 export declare function current(db: Ledger, project?: string): StatusEntry[];
 export declare function history(db: Ledger, project?: string, options?: HistoryOptions): StatusEntry[];
 export declare function at(db: Ledger, project: string, occurredAt: string): StatusEntry | undefined;
 export declare function countEntries(db: Ledger, project?: string): number;
+export type CompletionEvent = {
+    uid: string;
+    targetUid: string;
+    byUid: string;
+    previousUid: string | null;
+    action: "complete" | "revoke";
+    reason?: string;
+    recordedAt: string;
+    source: Source;
+};
+export declare function getEntry(db: Ledger, ref: string): StatusEntry | undefined;
+export declare function changeCompletion(db: Ledger, targetRef: string, byRef: string, action?: CompletionEvent["action"], reason?: string, source?: Source): CompletionEvent;
+export declare function exportLedger(db: Ledger, project?: string): {
+    version: number;
+    entries: {
+        recordedAt: string;
+        progress?: string | undefined;
+        externalRef?: string | undefined;
+        uid: string;
+        project: string;
+        status: import("./domain.js").ProjectStatus;
+        summary: string;
+        blockers: string[];
+        nextSteps: string[];
+        decisions: string[];
+        tags: string[];
+        occurredAt: string;
+        source: Source;
+    }[];
+    completions: CompletionEvent[];
+};
+export declare function importLedger(db: Ledger, values: unknown[]): InsertResult[];

package/dist/db.js

@@ -1,8 +1,10 @@
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { validateProjectMetadataInput, validateStatusEntry, ValidationError, } from "./domain.js";
+import { validateProjectMetadataInput, validateStatusEntry, ValidationError, toPortableStatusEntry, validateUid, parseTime, sources, } from "./domain.js";
 const migration1 = `
 CREATE TABLE IF NOT EXISTS projects (
   id INTEGER PRIMARY KEY,
@@ -50,12 +52,36 @@ export function openLedger(path = databasePath()) {
             db.exec(migration2);
             db.prepare("INSERT INTO schema_migrations(version) VALUES (2)").run();
         }
+        if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 3").get()) {
+            db.exec(`ALTER TABLE status_entries ADD COLUMN uid TEXT;
+        CREATE UNIQUE INDEX idx_entry_uid ON status_entries(uid);
+        CREATE TABLE completion_events (
+          id INTEGER PRIMARY KEY,
+          uid TEXT NOT NULL UNIQUE,
+          target_uid TEXT NOT NULL REFERENCES status_entries(uid),
+          by_uid TEXT NOT NULL REFERENCES status_entries(uid),
+          previous_uid TEXT REFERENCES completion_events(uid),
+          action TEXT NOT NULL CHECK(action IN ('complete', 'revoke')),
+          reason TEXT,
+          recorded_at TEXT NOT NULL,
+          source TEXT NOT NULL
+        );
+        CREATE INDEX idx_completion_target ON completion_events(target_uid, id DESC);`);
+            for (const row of db.prepare("SELECT id FROM status_entries").all()) {
+                db.prepare("UPDATE status_entries SET uid = ? WHERE id = ?").run(randomUUID(), row.id);
+            }
+            db.exec(`CREATE TRIGGER require_entry_uid BEFORE INSERT ON status_entries
+        WHEN NEW.uid IS NULL
+        BEGIN SELECT RAISE(ABORT, 'entry uid required; upgrade the writer'); END;`);
+            db.prepare("INSERT INTO schema_migrations(version) VALUES (3)").run();
+        }
     }).immediate();
     return db;
 }
 function entryFromRow(row) {
     return {
         id: row.id,
+        uid: row.uid,
         project: row.project,
         status: row.status,
         summary: row.summary,
@@ -173,28 +199,51 @@ export function listProjects(db, options = {}) {
         return false;
     });
 }
-export function addStatus(db, value, defaultSource = "human") {
+export function addStatus(db, value, defaultSource = "human", completes = []) {
     const input = validateStatusEntry(value, defaultSource);
-    return db.transaction(() => addValidatedStatus(db, input))();
+    return db
+        .transaction(() => {
+        const result = addValidatedStatus(db, input);
+        for (const target of completes)
+            changeCompletion(db, target, result.entry.uid, "complete", undefined, input.source);
+        return result;
+    })
+        .immediate();
 }
-function addValidatedStatus(db, input) {
+function addValidatedStatus(db, input, recordedAt) {
+    if (input.uid) {
+        const existing = one(db, `${select} WHERE e.uid = ?`, input.uid);
+        if (existing) {
+            const candidate = toPortableStatusEntry({
+                ...input,
+                id: existing.id,
+                recordedAt: existing.recordedAt,
+            });
+            if (!isDeepStrictEqual(toPortableStatusEntry(existing), candidate) ||
+                (recordedAt !== undefined && recordedAt !== existing.recordedAt))
+                throw new ValidationError("conflicting entry uid");
+            return { entry: existing, inserted: false };
+        }
+    }
     if (input.externalRef) {
         const existing = one(db, `${select} WHERE e.external_ref = ?`, input.externalRef);
         if (existing) {
+            if (input.uid)
+                throw new ValidationError("externalRef conflicts with portable uid");
             if (existing.project !== input.project)
                 throw new ValidationError(`externalRef is already used by project ${existing.project}`);
             return { entry: existing, inserted: false };
         }
     }
-    const now = new Date().toISOString();
+    const now = recordedAt ?? new Date().toISOString();
     upsertProjectMetadata(db, { project: input.project });
     const project = db
         .prepare("SELECT id FROM projects WHERE slug = ?")
         .get(input.project);
     const result = db
-        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null);
+        .prepare(`INSERT INTO status_entries(project_id, status, summary, progress, blockers_json, next_steps_json, decisions_json, tags_json, occurred_at, recorded_at, source, external_ref, uid)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(project.id, input.status, input.summary, input.progress ?? null, JSON.stringify(input.blockers), JSON.stringify(input.nextSteps), JSON.stringify(input.decisions), JSON.stringify(input.tags), input.occurredAt, now, input.source, input.externalRef ?? null, input.uid ?? randomUUID());
     return {
         entry: one(db, `${select} WHERE e.id = ?`, result.lastInsertRowid),
         inserted: true,
@@ -209,7 +258,7 @@ export function current(db, project) {
     const rows = db
         .prepare(`${select} WHERE e.id IN (SELECT id FROM (SELECT id, ROW_NUMBER() OVER (PARTITION BY project_id ORDER BY occurred_at DESC, id DESC) AS position FROM status_entries) WHERE position = 1)${where} ORDER BY e.occurred_at DESC, e.id DESC`)
         .all(...(project ? [project] : []));
-    return rows.map(entryFromRow);
+    return rows.map((row) => annotateEntry(db, entryFromRow(row)));
 }
 export function history(db, project, options = {}) {
     const clauses = [];
@@ -231,7 +280,7 @@ export function history(db, project, options = {}) {
     const rows = db
         .prepare(`${select}${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY e.occurred_at DESC, e.id DESC LIMIT ? OFFSET ?`)
         .all(...params, limit, offset);
-    return rows.map(entryFromRow);
+    return rows.map((row) => annotateEntry(db, entryFromRow(row)));
 }
 export function at(db, project, occurredAt) {
     return one(db, `${select} WHERE p.slug = ? AND e.occurred_at <= ? ORDER BY e.occurred_at DESC, e.id DESC LIMIT 1`, project, occurredAt);
@@ -248,3 +297,203 @@ export function countEntries(db, project) {
         .get();
     return row.count;
 }
+function completionFromRow(row) {
+    return {
+        uid: row.uid,
+        targetUid: row.target_uid,
+        byUid: row.by_uid,
+        previousUid: row.previous_uid,
+        action: row.action,
+        ...(row.reason === null ? {} : { reason: row.reason }),
+        recordedAt: row.recorded_at,
+        source: row.source,
+    };
+}
+function latestCompletion(db, uid) {
+    const row = db
+        .prepare("SELECT * FROM completion_events WHERE target_uid = ? ORDER BY id DESC LIMIT 1")
+        .get(uid);
+    return row && completionFromRow(row);
+}
+export function getEntry(db, ref) {
+    const entry = /^\d+$/.test(ref)
+        ? one(db, `${select} WHERE e.id = ?`, ref)
+        : one(db, `${select} WHERE e.uid = ?`, ref);
+    return entry && annotateEntry(db, entry);
+}
+function annotateEntry(db, entry) {
+    const latest = latestCompletion(db, entry.uid);
+    const followUp = latest?.action === "complete"
+        ? one(db, `${select} WHERE e.uid = ?`, latest.byUid)
+        : undefined;
+    const newest = one(db, `${select} WHERE p.slug = ? ORDER BY e.occurred_at DESC, e.id DESC LIMIT 1`, entry.project);
+    return {
+        ...entry,
+        effectiveStatus: followUp ? "completed" : entry.status,
+        isCurrent: newest?.id === entry.id,
+        ...(followUp && latest
+            ? {
+                completedBy: {
+                    uid: followUp.uid,
+                    id: followUp.id,
+                    summary: followUp.summary,
+                    occurredAt: followUp.occurredAt,
+                    recordedAt: latest.recordedAt,
+                },
+            }
+            : {}),
+    };
+}
+function validateCompletionPair(db, targetRef, byRef) {
+    const target = getEntry(db, targetRef);
+    const by = getEntry(db, byRef);
+    if (!target || !by)
+        throw new ValidationError("completion entry not found");
+    if (target.project !== by.project)
+        throw new ValidationError("completion entries must belong to the same project");
+    if (target.occurredAt >= by.occurredAt)
+        throw new ValidationError("completion target must have a strictly earlier occurrence time");
+    return [target, by];
+}
+function insertCompletion(db, event) {
+    const existing = db
+        .prepare("SELECT * FROM completion_events WHERE uid = ?")
+        .get(event.uid);
+    if (existing) {
+        if (!isDeepStrictEqual(completionFromRow(existing), event))
+            throw new ValidationError("conflicting completion uid");
+        return;
+    }
+    validateCompletionPair(db, event.targetUid, event.byUid);
+    const latest = latestCompletion(db, event.targetUid);
+    // A per-target chain preserves event order and detects divergent imported histories.
+    if ((latest?.uid ?? null) !== event.previousUid)
+        throw new ValidationError("completion event order conflicts with target history");
+    if (event.action === "complete" && latest?.action === "complete")
+        throw new ValidationError("target already completed; revoke first");
+    if (event.action === "revoke" &&
+        (latest?.action !== "complete" || latest.byUid !== event.byUid))
+        throw new ValidationError("no matching active completion to revoke");
+    db.prepare(`INSERT INTO completion_events(uid, target_uid, by_uid, previous_uid, action, reason, recorded_at, source)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(event.uid, event.targetUid, event.byUid, event.previousUid, event.action, event.reason ?? null, event.recordedAt, event.source);
+}
+export function changeCompletion(db, targetRef, byRef, action = "complete", reason, source = "human") {
+    if (action !== "complete" && action !== "revoke")
+        throw new ValidationError("invalid completion action");
+    if (!sources.includes(source))
+        throw new ValidationError("source is invalid");
+    if (reason !== undefined &&
+        (typeof reason !== "string" || !reason.trim() || reason.length > 2000))
+        throw new ValidationError("reason must be a non-empty string of at most 2000 characters");
+    if (action === "revoke" && !reason)
+        throw new ValidationError("revocation requires a reason");
+    return db
+        .transaction(() => {
+        const [target, by] = validateCompletionPair(db, targetRef, byRef);
+        const latest = latestCompletion(db, target.uid);
+        if (action === "complete" &&
+            latest?.action === "complete" &&
+            latest.byUid === by.uid)
+            return latest;
+        const event = {
+            uid: randomUUID(),
+            targetUid: target.uid,
+            byUid: by.uid,
+            previousUid: latest?.uid ?? null,
+            action,
+            ...(reason ? { reason: reason.trim() } : {}),
+            source,
+            recordedAt: new Date().toISOString(),
+        };
+        insertCompletion(db, event);
+        return event;
+    })
+        .immediate();
+}
+export function exportLedger(db, project) {
+    return db.transaction(() => {
+        const entries = db
+            .prepare(`${select}${project ? " WHERE p.slug = ?" : ""} ORDER BY e.occurred_at, e.id`)
+            .all(...(project ? [project] : []))
+            .map(entryFromRow)
+            .map((entry) => ({
+            ...toPortableStatusEntry(entry),
+            recordedAt: entry.recordedAt,
+        }));
+        const rows = db
+            .prepare(`SELECT c.* FROM completion_events c JOIN status_entries e ON e.uid = c.target_uid JOIN projects p ON p.id = e.project_id ${project ? "WHERE p.slug = ?" : ""} ORDER BY c.id`)
+            .all(...(project ? [project] : []));
+        return { version: 2, entries, completions: rows.map(completionFromRow) };
+    })();
+}
+function record(value, keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ValidationError("expected an object");
+    const result = value;
+    for (const key of Object.keys(result))
+        if (!keys.includes(key))
+            throw new ValidationError(`unknown field: ${key}`);
+    return result;
+}
+function validateCompletionEvent(value) {
+    const row = record(value, [
+        "uid",
+        "targetUid",
+        "byUid",
+        "previousUid",
+        "action",
+        "reason",
+        "recordedAt",
+        "source",
+    ]);
+    if (row.action !== "complete" && row.action !== "revoke")
+        throw new ValidationError("invalid completion action");
+    if (!sources.includes(row.source))
+        throw new ValidationError("source is invalid");
+    if (row.reason !== undefined &&
+        (typeof row.reason !== "string" ||
+            !row.reason.trim() ||
+            row.reason.length > 2000))
+        throw new ValidationError("invalid completion reason");
+    if (row.action === "revoke" && !row.reason)
+        throw new ValidationError("revocation requires a reason");
+    return {
+        uid: validateUid(row.uid),
+        targetUid: validateUid(row.targetUid),
+        byUid: validateUid(row.byUid),
+        previousUid: row.previousUid === null ? null : validateUid(row.previousUid),
+        action: row.action,
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+        recordedAt: parseTime(row.recordedAt, "recordedAt"),
+        source: row.source,
+    };
+}
+export function importLedger(db, values) {
+    // Both legacy entries and versioned bundles are accepted atomically, including JSONL.
+    return db
+        .transaction(() => {
+        const results = [];
+        for (const value of values) {
+            if (value && typeof value === "object" && "version" in value) {
+                const bundle = record(value, ["version", "entries", "completions"]);
+                if (bundle.version !== 2 ||
+                    !Array.isArray(bundle.entries) ||
+                    !Array.isArray(bundle.completions))
+                    throw new ValidationError("invalid ledger bundle");
+                for (const item of bundle.entries) {
+                    if (!item || typeof item !== "object" || Array.isArray(item))
+                        throw new ValidationError("entry must be an object");
+                    const { recordedAt, ...input } = item;
+                    validateUid(input.uid);
+                    results.push(addValidatedStatus(db, validateStatusEntry(input, "import"), parseTime(recordedAt, "recordedAt")));
+                }
+                for (const event of bundle.completions)
+                    insertCompletion(db, validateCompletionEvent(event));
+            }
+            else
+                results.push(addValidatedStatus(db, validateStatusEntry(value, "import")));
+        }
+        return results;
+    })
+        .immediate();
+}

package/dist/domain.d.ts

@@ -19,6 +19,7 @@ export type ProjectMetadataInput = {
     notes?: string | null;
 };
 export type StatusEntryInput = {
+    uid?: string;
     project: string;
     status: ProjectStatus;
     summary: string;
@@ -36,8 +37,17 @@ export type StatusEntry = Required<Omit<StatusEntryInput, "progress" | "external
     progress?: string;
     externalRef?: string;
     recordedAt: string;
+    effectiveStatus?: ProjectStatus;
+    isCurrent?: boolean;
+    completedBy?: {
+        uid: string;
+        id: number;
+        summary: string;
+        occurredAt: string;
+        recordedAt: string;
+    };
 };
-export type PortableStatusEntry = Omit<StatusEntry, "id" | "recordedAt">;
+export type PortableStatusEntry = Omit<StatusEntry, "id" | "recordedAt" | "effectiveStatus" | "isCurrent" | "completedBy">;
 export declare class ValidationError extends Error {
     constructor(message: string);
 }
@@ -45,3 +55,4 @@ export declare function parseTime(value: unknown, field: string): string;
 export declare function validateProjectMetadataInput(value: unknown): ProjectMetadataInput;
 export declare function validateStatusEntry(value: unknown, defaultSource?: Source): StatusEntryInput & Required<Pick<StatusEntryInput, "occurredAt" | "source">>;
 export declare function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry;
+export declare function validateUid(value: unknown): string;

package/dist/domain.js

@@ -9,6 +9,7 @@ export const statuses = [
 ];
 export const sources = ["human", "agent", "import"];
 const keys = new Set([
+    "uid",
     "project",
     "status",
     "summary",
@@ -120,6 +121,7 @@ export function validateStatusEntry(value, defaultSource = "human") {
     if (externalRef && externalRef.length > 200)
         throw new ValidationError("externalRef must be at most 200 characters");
     return {
+        ...(input.uid === undefined ? {} : { uid: validateUid(input.uid) }),
         project,
         status: statusInput,
         summary: text(input.summary, "summary", true),
@@ -137,6 +139,7 @@ export function validateStatusEntry(value, defaultSource = "human") {
 }
 export function toPortableStatusEntry(entry) {
     const result = {
+        uid: entry.uid,
         project: entry.project,
         status: entry.status,
         summary: entry.summary,
@@ -153,3 +156,9 @@ export function toPortableStatusEntry(entry) {
         result.externalRef = entry.externalRef;
     return result;
 }
+export function validateUid(value) {
+    if (typeof value !== "string" ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value))
+        throw new ValidationError("uid must be a lowercase UUID");
+    return value;
+}

package/dist/server.js

@@ -1,7 +1,7 @@
 import { exec } from "node:child_process";
 import { createServer, } from "node:http";
 import { URL } from "node:url";
-import { countEntries, history, listProjects, openLedger, } from "./db.js";
+import { countEntries, getEntry, history, listProjects, openLedger, } from "./db.js";
 import { getWebUIHTML } from "./web/ui.js";
 export function openBrowser(url) {
     const platform = process.platform;
@@ -41,6 +41,18 @@ export function handleRequest(req, res, db) {
     const reqUrl = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
     const pathname = reqUrl.pathname;
     const query = parseQueryParams(reqUrl);
+    let entryRef;
+    let projectSlug;
+    try {
+        if (pathname.startsWith("/api/entries/"))
+            entryRef = decodeURIComponent(pathname.slice("/api/entries/".length));
+        if (pathname.startsWith("/api/projects/"))
+            projectSlug = decodeURIComponent(pathname.slice("/api/projects/".length));
+    }
+    catch {
+        sendJson(res, 400, { error: "Invalid URL encoding" });
+        return;
+    }
     if (pathname === "/" || pathname === "/index.html") {
         res.writeHead(200, {
             "Content-Type": "text/html; charset=utf-8",
@@ -55,7 +67,7 @@ export function handleRequest(req, res, db) {
         return;
     }
     if (pathname.startsWith("/api/projects/")) {
-        const slug = decodeURIComponent(pathname.slice("/api/projects/".length));
+        const slug = projectSlug;
         const projects = listProjects(db);
         const target = projects.find((p) => p.project === slug);
         if (!target) {
@@ -66,6 +78,11 @@ export function handleRequest(req, res, db) {
         }
         return;
     }
+    if (pathname.startsWith("/api/entries/")) {
+        const entry = getEntry(db, entryRef);
+        sendJson(res, entry ? 200 : 404, entry ?? { error: "Entry not found" });
+        return;
+    }
     if (pathname === "/api/history") {
         const project = query.project;
         const since = query.since;