@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/registry.js

@@ -0,0 +1,235 @@
+import { noSuggestion } from "./prompt-state.js";
+export const freshSession = (sessionId) => ({
+    rev: 0,
+    parentSession: null,
+    rootSession: sessionId,
+    nextChapterNumber: 1,
+    nextPlanNumber: 1,
+    collections: [],
+    chapters: [],
+    reservations: {},
+    promptSuggestion: noSuggestion,
+    plans: {},
+    finalized: {},
+});
+/** Persist a summarize-time plan so finalization survives a restart. */
+export function rememberPlan(state, compactionId, plan) {
+    return { ...state, plans: { ...state.plans, [compactionId]: plan } };
+}
+/** Record a post-commit finalization for one compaction. Same write twice is a no-op. */
+export function markFinalized(state, compactionId, numbers) {
+    if (state.finalized[compactionId] !== undefined)
+        return state;
+    return { ...state, finalized: { ...state.finalized, [compactionId]: [...numbers] } };
+}
+/** True when a compaction's chapters are already committed (finalizer + scan use this). */
+export const isFinalized = (state, compactionId) => state.finalized[compactionId] !== undefined;
+/** Immutably updated copy with `n` numbers reserved for `attemptId`. */
+export function reserve(state, attemptId, count) {
+    if (count <= 0 || !Number.isInteger(count)) {
+        throw new Error(`reserve: count must be a positive integer, got ${count}`);
+    }
+    const existing = state.reservations[attemptId];
+    if (existing !== undefined) {
+        if (existing.length !== count) {
+            // Same attempt, different size: the caller's chapter set changed under a
+            // half-finished attempt. Reusing a shorter list would silently drop
+            // chapters; growing would collide. Refuse — never guess.
+            throw new Error(`reserve: attempt "${attemptId}" already holds ${existing.length} numbers, requested ${count}`);
+        }
+        return { state, numbers: [...existing] };
+    }
+    // Never hand out a number the row already carries. A committed number with no matching
+    // reservation is a real state, not a bug: an orphan row written before this field existed, or a
+    // chapter whose record a lost update erased while its file survived (#59). Allocating into it would
+    // put two `0NN-*.md` in one tree, so allocation SKIPS it and spends the next free number instead.
+    const taken = new Set(state.chapters.map((c) => c.number));
+    const numbers = [];
+    let cursor = state.nextChapterNumber;
+    while (numbers.length < count) {
+        if (!taken.has(cursor))
+            numbers.push(cursor);
+        cursor += 1;
+    }
+    return {
+        state: {
+            ...state,
+            nextChapterNumber: cursor,
+            reservations: { ...state.reservations, [attemptId]: numbers },
+        },
+        numbers,
+    };
+}
+/** The same allocation rule for plan documents, on its own counter. */
+export function reservePlan(state, attemptId, count) {
+    if (count <= 0 || !Number.isInteger(count)) {
+        throw new Error(`reservePlan: count must be a positive integer, got ${count}`);
+    }
+    const key = `plan:${attemptId}`;
+    const existing = state.reservations[key];
+    if (existing !== undefined) {
+        if (existing.length !== count) {
+            throw new Error(`reservePlan: attempt "${key}" already holds ${existing.length} numbers, requested ${count}`);
+        }
+        return { state, numbers: [...existing] };
+    }
+    // Same skip rule as reserve(): plan documents are numbered independently but the collision
+    // hazard is identical (a lost update rewinding nextPlanNumber re-issues `plan-003` over a twin).
+    const taken = new Set(state.chapters.flatMap((c) => c.planDocs ?? [])
+        .map((d) => /plan-(\d+)-/.exec(d.path)?.[1]).filter((n) => n !== undefined).map(Number));
+    const numbers = [];
+    let cursor = state.nextPlanNumber;
+    while (numbers.length < count) {
+        if (!taken.has(cursor))
+            numbers.push(cursor);
+        cursor += 1;
+    }
+    return {
+        state: {
+            ...state,
+            nextPlanNumber: cursor,
+            reservations: { ...state.reservations, [key]: numbers },
+        },
+        numbers,
+    };
+}
+/**
+ * Append verified chapter records.
+ *
+ * Identity is `(number, sha256)`, never `number` alone (#59). An identical record is a no-op — that is
+ * what makes a retry after a crash safe. A record reusing a number for DIFFERENT bytes is not a retry,
+ * it is a collision: one door's reservation was rewound by a lost update and another door has now been
+ * handed a number whose file already exists. Measured in the field: chapter 15 was spent twice in
+ * `session-aac0254e`, and number-only dedupe silently DROPPED the second record while its 960 KB file
+ * stayed on disk — a chapter no TOC cites and no tool can find. Refusing is the only honest option.
+ */
+/**
+ * The ONE test for "may this chapter be shown as knowledge?" (#60, widened by #255). Both tombstone
+ * statuses fail it: a `superseded` husk left by repair, and a `removed` stub whose bytes the operator
+ * deleted. Every derived layer — the TOC a child is seeded with, the flat index, the enrichment queue,
+ * anything else that reads `state.chapters` — goes through this predicate, because a second hand-rolled
+ * comparison is how a widened meaning silently fails to reach one layer (#59; the gate is
+ * tests/unit/one-predicate.test.ts). Records written before this field existed are `undefined`, i.e.
+ * active: legacy archives are never silently hidden by a new filter.
+ */
+export function isActiveChapter(c) {
+    return c.status !== 'superseded' && c.status !== 'removed';
+}
+/**
+ * The ONE positive arm for the #255 tombstone (chapter-only status value — plan statuses share the
+ * word `superseded` but not this one). For auditors that must COUNT removed stubs, not hide them:
+ * the knowledge gate above, the count below, one status read each, both here (#59).
+ */
+export function isRemovedChapter(c) {
+    return c.status === 'removed';
+}
+export function appendChapters(state, records) {
+    const byNumber = new Map(state.chapters.map((c) => [c.number, c]));
+    const fresh = [];
+    for (const r of records) {
+        const prior = byNumber.get(r.number);
+        if (prior !== undefined) {
+            if (prior.sha256 !== r.sha256 || prior.path !== r.path) {
+                throw new Error(`appendChapters: chapter number ${r.number} is already committed with different content `
+                    + `(${prior.path} sha ${prior.sha256.slice(0, 12)}…) — refusing to overwrite or silently drop `
+                    + `${r.path} (sha ${r.sha256.slice(0, 12)}…). A reused number means a lost registry update (#59).`);
+            }
+            continue; // identical retry
+        }
+        fresh.push(r);
+        byNumber.set(r.number, r);
+    }
+    return fresh.length === 0 ? state : { ...state, chapters: [...state.chapters, ...fresh] };
+}
+/**
+ * Free an attempt's retry key WITHOUT un-spacing its numbers (#59). Reserve-before-write exists so a
+ * crash cannot re-issue a number whose file may already be on disk; that guarantee must not be undone
+ * here. What this does is stop a burned key from living forever: a door that reserved and then failed
+ * (a read-back that did not verify, a refusal after writing) currently leaves `reservations[k]` behind
+ * with no file and no record, which is the state the field showed at numbers 20 and 37.
+ *
+ * `numbersSpent` stays monotonic — only the attempt key goes.
+ */
+export function releaseReservation(state, attemptId) {
+    if (state.reservations[attemptId] === undefined)
+        return state;
+    const { [attemptId]: _gone, ...rest } = state.reservations;
+    return { ...state, reservations: rest };
+}
+/**
+ * Commit point for a continuation: the child inherits the PARENT's root and
+ * gets its direct parent recorded. Set once, never rewritten — re-pointing a
+ * linked session would silently re-home every chapter below it. Same link
+ * twice is a no-op (retry safety); a DIFFERENT link is corruption or a bug,
+ * and it throws.
+ */
+export function linkChild(state, parentSessionId, parentRootSession) {
+    if (state.parentSession !== null) {
+        if (state.parentSession === parentSessionId && state.rootSession === parentRootSession)
+            return state;
+        throw new Error(`linkChild: session already linked to parent ${state.parentSession} (root ${state.rootSession});`
+            + ` refusing rewrite to parent ${parentSessionId} (root ${parentRootSession})`);
+    }
+    return { ...state, parentSession: parentSessionId, rootSession: parentRootSession };
+}
+/**
+ * Walk parent links root-first. Throws on a cycle or a missing parent — both
+ * are registry corruption, and an infinite walk is how a small bad write
+ * becomes a hung plugin at the worst moment.
+ */
+export function ancestorPath(get, sessionId, maxDepth = 1000) {
+    const path = [];
+    const seen = new Set();
+    let cursor = sessionId;
+    while (cursor !== undefined) {
+        if (seen.has(cursor))
+            throw new Error(`ancestorPath: cycle through ${cursor}`);
+        if (seen.size >= maxDepth)
+            throw new Error(`ancestorPath: exceeded depth ${maxDepth}`);
+        seen.add(cursor);
+        const state = get(cursor);
+        if (state === undefined) {
+            if (cursor === sessionId)
+                return [cursor]; // unregistered root: itself is the path
+            throw new Error(`ancestorPath: missing state for parent ${cursor} (registry corruption)`);
+        }
+        path.unshift(cursor);
+        cursor = state.parentSession ?? undefined;
+    }
+    return path;
+}
+/**
+ * The flat, chronological, numbered index the TOC renders — reading order IS
+ * causal order (docs/architecture.md § Ancestry). Ancestor sessions first;
+ * within a session, by reserved number. Siblings are excluded by construction:
+ * the walk never enters them.
+ */
+export function buildIndex(path, get, status) {
+    const entries = [];
+    for (const sessionId of path) {
+        const state = get(sessionId);
+        if (state === undefined)
+            continue;
+        // #255: the flat index shows ONLY knowledge — tombstones (superseded, removed) fail the one
+        // predicate. This is what lets `/chapters-remove list` be the same view a child is seeded from.
+        for (const chapter of [...state.chapters].filter(isActiveChapter).sort((a, b) => a.number - b.number)) {
+            entries.push({
+                authorSession: sessionId,
+                number: chapter.number,
+                path: chapter.path,
+                title: chapter.title,
+                summary: chapter.summary,
+                status: status(chapter),
+            });
+        }
+    }
+    return entries;
+}
+/** Append one turn's signature. Idempotent per turn (same seqs → no-op), like appendChapters. */
+export function appendCollection(state, sig) {
+    const last = state.collections[state.collections.length - 1];
+    if (last !== undefined && last.seqs.length === sig.seqs.length && last.seqs.every((q, i) => q === sig.seqs[i]))
+        return state;
+    return { ...state, collections: [...state.collections, sig] };
+}
+//# sourceMappingURL=registry.js.map

package/lib/registry.js.map

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

package/lib/removal.d.ts

@@ -0,0 +1,159 @@
+import { type ChapterRecord } from './archive.ts';
+import { type SessionState } from './registry.ts';
+import type { RegistryStore } from './store.ts';
+import { type RemovedGuard } from './sync.ts';
+export type RemovalRows = readonly (readonly [string, SessionState])[];
+export interface RemovalTarget {
+    sessionId: string;
+    rootSession: string;
+    record: ChapterRecord;
+}
+export type ResolveOutcome = {
+    target: RemovalTarget;
+} | {
+    refusal: string;
+};
+export interface RemovalFile {
+    abs: string;
+    /** The stored-path dialect of the registry record (what `sameStoredPath` compares). */
+    stored: string;
+    bytes: number;
+}
+export interface DanglingRef {
+    /** The surviving chapter (or artifact of the search) that still names the removed one. */
+    referrer: string;
+    /** Which spelling of the removed chapter the referrer cites. */
+    needle: string;
+    how: 'cited-in-body' | 'cited-in-toc';
+}
+export interface RemovalPlan {
+    targets: RemovalTarget[];
+    chapterFiles: RemovalFile[];
+    /** Orphan blobs + plan documents: each named ONLY by the targets. */
+    blobFiles: RemovalFile[];
+    dangling: DanglingRef[];
+    /** Files the plan expected on disk and did not find — stated, never silent (a stub can outrun a lost tree). */
+    missing: string[];
+}
+export interface ApplyPorts {
+    store: RegistryStore;
+    cwd: string;
+    rows: RemovalRows;
+    now: () => string;
+    /** The resolved store ROOT (the directory holding session trees). Defaults to `<cwd>/.dsh-chapters`. */
+    storeDir?: string | undefined;
+    /** Linked project: the removal also unlinks the mirror copies, so the sync commit carries the
+     * deletion (`publishIntoClone` copies — it can never propagate a deletion by itself). Absent ⇒
+     * store-only removal (an unlinked project), which is the normal state, not an error. */
+    cloneDir?: string | undefined;
+    projectKey?: string | undefined;
+}
+export interface ApplyOutcome {
+    journalId: string;
+    /** Stored paths actually unlinked (or already absent). */
+    removed: string[];
+    /** session:number of every record flipped to the removed stub. */
+    stubbed: string[];
+    problems: string[];
+    dangling: DanglingRef[];
+    bytes: number;
+}
+export interface Journal {
+    journalId: string;
+    at: string;
+    cwd: string;
+    /** 'planned' is written BEFORE the first unlink; 'applied'/'partial' rewrite it after. */
+    status: 'planned' | 'applied' | 'partial';
+    entries: {
+        sessionId: string;
+        number: number;
+        title: string;
+        startSeq: number;
+        endSeq: number;
+        path: string;
+        sha256: string;
+        removedFiles: string[];
+        appliedAt?: string;
+    }[];
+    problems?: string[];
+}
+/**
+ * Resolve one operator-supplied id to exactly one ACTIVE chapter record. Accepted dialects:
+ * registry path (the `list`/journal output), pool path from a search hit
+ * (`chapters/<key>/<session>/<file>.md` — matched by its `<session>/<file>` tail),
+ * `<sessionId>:<number>`, and a bare TOC display ordinal (needs the caller's session, because the
+ * ordinal is a position in the caller's ancestor-path flat index, not a registry number).
+ * Zero matches, several matches, or a tombstone each refuse with specifics — removal is destructive
+ * and never guesses.
+ */
+export declare function resolveRemovalId(raw: string, rows: RemovalRows, cwd: string, callerSessionId?: string): ResolveOutcome;
+/**
+ * The exact deletion set + the dangling report, from registry rows and the filesystem — written
+ * for the dry-run and consumed unchanged by apply. Reads only; deletes nothing.
+ */
+export declare function planRemoval(opts: {
+    targets: readonly RemovalTarget[];
+    rows: RemovalRows;
+    cwd: string;
+}): RemovalPlan;
+/**
+ * Every SURVIVING chapter body that still names a removed chapter — by any dialect: the stored path,
+ * the filename, or the absolute path a TOC copy would carry. This is the operator's "should the
+ * referrer stay?" list, and the seed for missing-access.log.
+ */
+export declare function scanDangling(rows: RemovalRows, targets: readonly RemovalTarget[], cwd: string, targetKeys?: Set<string>): DanglingRef[];
+/**
+ * Execute a plan. Safety order, pinned by tests: journal (status 'planned') BEFORE the first unlink;
+ * unlinks; stub the record through `store.mutate` (never a snapshot put, #59) ONLY for targets whose
+ * chapter file is gone; append the dangling report to the missing-access log; rewrite the journal as
+ * applied (or partial, naming every problem). Idempotence: a second apply finds the records already
+ * tombstoned by the caller's resolve step — resolve refuses tombstones, so there is nothing to redo.
+ */
+export declare function applyRemoval(ports: ApplyPorts, plan: RemovalPlan): Promise<ApplyOutcome>;
+export declare const MISSING_ACCESS_FILE: string;
+export declare function appendMissingAccess(storeDir: string, lines: readonly string[], problems?: string[]): void;
+export declare function readMissingAccess(storeDir: string, maxLines: number): {
+    lines: string[];
+    total: number;
+    withheld: number;
+    file: string;
+};
+/**
+ * The rehydrate guard (#255): every name a `removed` stub owns, in the mirror walk's identity
+ * (`<sessionDir>#<file>` for chapters and plan documents; blob basename for content-addressed
+ * artifacts). Rehydration that skips these cannot resurrect a decision; the count lands in the
+ * sync steps. Keys are session-id-scoped and content-addressed-scoped, so they cannot collide
+ * across projects on one machine.
+ */
+export declare function removedGuard(rows: Iterable<readonly [string, SessionState]>): RemovedGuard;
+import { type SaveSessionConfig } from './save-core.ts';
+import type { SessionEventLike } from './types.ts';
+export interface RestorePorts {
+    store: RegistryStore;
+    cwd: string;
+    storeDir: string;
+    /** The payload-bearing durable-log read (#58's contract) — never a metadata-only record list. */
+    readLog(sessionId: string): Promise<SessionEventLike[] | null>;
+    config: SaveSessionConfig;
+    now: () => string;
+}
+export interface RestoreOutcome {
+    journalId: string;
+    /** `sid:number → ch.N` per entry whose span re-rendered and committed under a NEW number. */
+    restored: string[];
+    /** Legitimate no-ops, stated: already superseded, still-active, span already covered. */
+    skipped: string[];
+    /** Failures with names: no journal, no log, rendered nothing, vanished record. */
+    problems: string[];
+}
+/**
+ * Reversal is RE-DERIVATION (#255): the journaled span is re-rendered from the session's durable
+ * log through the SAME save core every door calls — a repaired chapter is byte-for-byte a normal
+ * chapter, and so is a restored one. The number is NEW (a spent number stays spent; identity is
+ * `(number, sha256)`); the removed stub flips to `superseded` with `repairs[].class =
+ * 'operator-restore'`, which is how an audit tells a restore from a repair. The log is never
+ * touched. A span that renders nothing REFUSES (never commit an empty archive); an unreadable log
+ * is UNRECOVERABLE and said so. One journal id can span trees: apply wrote one per affected tree,
+ * so restore collects entries from every `<tree>/removals/<id>.json`.
+ */
+export declare function restoreRemoval(ports: RestorePorts, journalId: string): Promise<RestoreOutcome>;