@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/durable/fs-store.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Filesystem `EventStore`.
+ *
+ * Layout under the store directory:
+ *
+ *   tasks/<taskId>/events/<seq,9 digits>.json      one canonical event, immutable
+ *   tasks/<taskId>/segments/S<from>-<to>.jsonl     packed, verified events (compaction)
+ *   tasks/<taskId>/prune-<n>.prepare.json          prune decision register (ADR-019): one attempt per file pair,
+ *   tasks/<taskId>/prune-<n>.decision.json         create-only, never deleted, never rewritten
+ *   tasks/<taskId>/tombstone.json                  published from the `commit` record of the register
+ *   durable-protocol.json                          version marker; created only by `initializeProtocol()`
+ *
+ * Concurrency needs no lock file. The one linearizable primitive is "create
+ * `<seq>.json` if it does not exist" — `createFile` of the safe-write
+ * primitive (temp file, fsync, `link()`, ADR-012). Of N writers racing for the
+ * same slot exactly one wins; the others see `conflict`, re-read and retry.
+ * There is no owner to declare dead, so none of the stale-lock failure modes
+ * (PID reuse across namespaces, wedged lock after a crash; ADR-015) exist.
+ *
+ * Crash behaviour:
+ *  - before `link()`           : nothing is visible; the temp file is a stranger.
+ *  - between `link()`/`unlink` : the event is complete and visible, but the file
+ *    has two names (`nlink == 2`). The strict reader of ADR-014 refuses such a
+ *    file, which would wedge the task for good. Here that state is *provable
+ *    residue* — the second name is `<file>.tmp.<pid>.<rand>` with the same
+ *    dev/ino — and the reader removes exactly that name and re-reads. Any
+ *    other second link stays a hard `StoreSecurityError`.
+ *  - compaction / prune       : ordered so that every prefix of the steps is a
+ *    consistent state (segment before unlink, tombstone before removal).
+ *
+ * Out of scope (same as the rest of MONOLITH, ADR-013): a local adversary that
+ * swaps directories concurrently (TM-C), NFS/SMB, Windows.
+ */
+import { StoreIoError } from './errors.js';
+import { type DecisionBy, type PruneOutcome, type PruneState } from './types.js';
+import { type WriteWarning } from '../root/index.js';
+import type { AppendOutcome, CompactionResult, EventStore, LogRead, TaskEvent, Tombstone } from './types.js';
+export type FsStoreTarget = {
+    scope: 'project';
+    projectRoot: string;
+    dir: string;
+} | {
+    scope: 'trusted-directory';
+    dir: string;
+};
+export interface FsStoreOptions {
+    target: FsStoreTarget;
+    /** Receives non-fatal findings of the write primitive (e.g. directory fsync unsupported). */
+    onWarning?: (w: WriteWarning) => void;
+    /** `'full'` (default) fsyncs file and directory; `'file'` only the file. */
+    durability?: 'full' | 'file';
+}
+/** Packed segments stay well below this; it is the reader's ceiling. */
+export declare const MAX_SEGMENT_BYTES: number;
+export declare class AppendOutcomeUnknownError extends StoreIoError {
+    readonly taskId: string;
+    readonly seq: number;
+    constructor(taskId: string, seq: number, cause?: unknown);
+}
+/** What the version marker says about the store (Design A, sections 13 and 46.5). */
+export type ProtocolStatus = 
+/** `durable-protocol.json` is present and understood: the store may be written. */
+{
+    mode: 'ready';
+    version: 2;
+}
+/** No marker: read-only diagnostics. Nothing is created, nothing is migrated. */
+ | {
+    mode: 'diagnostic';
+    reason: 'uninitialized';
+    tasksPresent: boolean;
+}
+/** A marker this build does not understand (a newer version, or damaged): the store is not opened as compatible. */
+ | {
+    mode: 'incompatible';
+    reason: 'unsupported-version' | 'invalid-marker';
+};
+export declare class FsEventStore implements EventStore {
+    private readonly root;
+    private readonly boundaryDir;
+    private boundaryCache;
+    private readonly opts;
+    /** True once a valid marker was seen. Only then may a read repair anything (it is a mutation). Never reset: the marker is never removed. */
+    private ready;
+    private readonly maxAttempts;
+    private readonly seams;
+    constructor(opts: FsStoreOptions);
+    /**
+     * The trust boundary. In `trusted-directory` scope the directory is the boundary and is created on the
+     * first write if missing (same contract as the state keeper); a read of a store that does not exist yet
+     * simply finds nothing. In `project` scope the project root must already exist.
+     */
+    private boundaryFor;
+    private taskDir;
+    private eventsDir;
+    private segmentsDir;
+    private refsDir;
+    private wrapSafe;
+    private mapWriteError;
+    private markerRead;
+    private hasTasks;
+    /**
+     * What this store may be used for. Pure observation: it creates nothing and repairs nothing. A store with no marker is
+     * `diagnostic` (empty or not): reads work, every mutation is refused until the operator calls `initializeProtocol()`.
+     */
+    protocolStatus(): Promise<ProtocolStatus>;
+    /**
+     * Explicit operator action (Design A section 46.5, ADR-018 D3): publish `durable-protocol.json` (`{"v":2}`, create-only)
+     * in an EMPTY store, with every runtime of an older version stopped. It refuses a store that holds tasks (that needs the
+     * migration decision of the operator, not a bootstrap), refuses a marker of another version, and is a no-op when a valid
+     * marker is already there. Opening a store never does this.
+     */
+    initializeProtocol(): Promise<'initialized' | 'already-initialized'>;
+    /** The same operator action as `initializeProtocol`, for scripts and tests that are not async. */
+    initializeProtocolSync(): 'initialized' | 'already-initialized';
+    /** Called first by every public method. A write needs a valid marker; a read needs the marker to be absent or valid. */
+    private gate;
+    /** Verified directory (no symlink below the boundary) or `null` if it does not exist. */
+    private existingDir;
+    private listDir;
+    /**
+     * The second name of a freshly published file, if (and only if) it is
+     * provably this file's staging name: `<name>.tmp.<pid>.<rand>` in the same
+     * directory with the same dev/ino. Returns the removed name or `null`.
+     * Removing it is a mutation: a store without a valid marker (diagnostics only) never does it.
+     */
+    private repairResidue;
+    /** `null` when the file is missing. Throws on anything unsafe or unreadable. */
+    private readManaged;
+    /**
+     * The same safe read, reported as an observation instead of an exception, for the places that must tell
+     * "not there" (`absent`) from "there and wrong" (`bad`: evidence) from "could not find out" (`ioerr`: never evidence).
+     */
+    private readFileObs;
+    private registerIO;
+    /** Files of the task still on disk (events, segments, references, staging). `> 0` after a commit means "deleting". */
+    private residueCount;
+    /** `derivePruneState` over the real directory. Reads only. */
+    private derive;
+    /** The error a state that grants nothing turns into. */
+    private refusal;
+    pruneState(taskId: string): Promise<PruneState>;
+    private publishRecord;
+    /**
+     * The precondition of an irreversible prune (F-1): the log, read now, is that of a finished task whose head is the one
+     * the tombstone names. Meaningful only for an attempt that is already visible in the register (or, as a refusal that
+     * leaves no residue, just before one is published): from the moment the prepare is visible, an append that lands after
+     * this read settles through G2, finds the open attempt and closes it with `abort`, so a commit can never follow it.
+     */
+    private assertPrunable;
+    preparePrune(tombstone: Tombstone): Promise<{
+        attempt: number;
+        created: boolean;
+    }>;
+    decidePrune(taskId: string, attempt: number, outcome: PruneOutcome, tombstone?: Tombstone, by?: DecisionBy): Promise<PruneOutcome>;
+    markPruned(tombstone: Tombstone): Promise<void>;
+    withdrawTombstone(tombstone: Tombstone): Promise<void>;
+    prune(tombstone: Tombstone, opts?: {
+        requireCommit?: boolean;
+    }): Promise<{
+        removedFiles: number;
+    }>;
+    /**
+     * The events (and covered segment lines) still on disk with `seq <= upTo`, each verified on its own; no gap is an error,
+     * because a roll-forward that was interrupted leaves gaps. A segment wins over a loose copy of the same slot (the reader's
+     * rule). Anything that cannot be read safely or does not verify throws: the audit then refuses instead of guessing.
+     */
+    private survivingEvents;
+    /**
+     * O-1: a committed register is not self-proving (its checksum is unkeyed), so the data still on disk must not contradict
+     * it before anything is unlinked. See `committedProblem` for what a partly removed log can and cannot prove. Reads only.
+     *
+     * I-1: the data is read FIRST and `tombstone.json` AFTER it. The roll-forward publishes the tombstone before its first
+     * unlink and nothing ever removes it, so a tombstone that is still absent after the data was read proves that no unlink
+     * had begun when the data was read (it was absent at every earlier moment too): a gap in the data is then not a removal
+     * but a torn observation or real damage. The loose files are read before the segments are listed (see `survivingEvents`), so a
+     * compaction that moves events into a segment meanwhile does not tear the observation. Read the
+     * other way round, a concurrent pruner that publishes the tombstone and removes events between the two reads is taken
+     * for damage. A gap seen without a tombstone is still looked at again a few times before it is refused (a defence in depth,
+     * not what F-1 relies on). No lock: a pruner that races this audit only ever turns the verdict
+     * from "the whole log must be there" into "a part may be gone", and the roll-forward still checks the tombstone it finds.
+     */
+    private auditCommitted;
+    /**
+     * Prune cleanup (class C, section 30.3): only for a verified, consistent `COMMITTED`. Publishes `tombstone.json` from the
+     * commit, then removes the data of the task. It never touches the register, `tombstone.json` or the task directory,
+     * decides nothing, and finishing a half-done run is the same call again.
+     */
+    private rollForward;
+    /**
+     * G1 (section 24.6): an optional early refusal, so that a write to a pruned or damaged task does not leave a file
+     * behind. Safety never depends on it (G2 decides); turning it off changes only how much is left over.
+     */
+    private earlyCheck;
+    /**
+     * G2 (section 24.2): after a file was published, ask the register. It never unlinks anything: a published file is
+     * shared state (F-1, class A is forbidden). `PREPARING` is closed with an `abort` (always safe), at most
+     * `MAX_WRITE_RESOLVE` times; a pruner that keeps opening attempts leaves the outcome UNKNOWN, never a deletion.
+     */
+    private settle;
+    listTaskIds(): Promise<string[]>;
+    readLog(taskId: string, opts?: {
+        afterSeq?: number;
+        rawEvents?: boolean;
+    }): Promise<LogRead>;
+    private readLogImpl;
+    private fileExists;
+    private slotName;
+    /** The loose file of a slot as an observation (trimmed line), never an exception. */
+    private readSlot;
+    private listSegments;
+    /** A segment as its lines, validated the way `readLog` validates it. */
+    private readSegmentLines;
+    /**
+     * `CanonRead` for the slots `from..to` (section 40.2). Every loose file is read BEFORE the single listing of
+     * `segments/` (the order is what makes a slot that was compacted in between visible, section 35.3), and a slot
+     * covered by a segment takes the segment's row: a loose file next to it is a copy or an orphan and is not consulted
+     * (CEI-2), so an I/O error on it does not matter. Writes nothing.
+     */
+    private canonRead;
+    /**
+     * Canonical Event Identity (section 35.2), run right after the `link` of a loose file (or its `EEXIST`): the slot was
+     * read first (`slot`), the listing of `segments/` comes strictly after. Confirmation needs the slot to equal the event
+     * of the caller, canonically: the row of a covering segment, or — if nothing covers it — the loose file.
+     */
+    private cei;
+    /** AV-4: the error for a write that is not valid, chosen from the register only AFTER the refusal (section 31.1). */
+    private refuseWrite;
+    append(event: TaskEvent): Promise<AppendOutcome>;
+    /** The file is already visible: say so on the corruption error. */
+    private published;
+    /** Removes `name` only if its bytes are exactly `line` (a copy the caller published itself, class B). */
+    private removeOwnLooseFile;
+    compact(taskId: string, throughSeq: number, events: TaskEvent[]): Promise<CompactionResult>;
+    /** Removes the loose event file `name` iff its content is exactly `line`. `true` if it was removed. */
+    private removeLooseIfIdentical;
+    sweepCompacted(taskId: string): Promise<{
+        removedFiles: number;
+        keptFiles: number;
+    }>;
+    pinReference(parentId: string, childId: string, at: string): Promise<'pinned' | 'parent-pruned' | 'parent-missing'>;
+    listReferences(parentId: string): Promise<Array<{
+        childId: string;
+        at: string;
+    }>>;
+    /** fsync `dir` and every ancestor down to the store root: directory entries created by mkdir are not durable until their parent is synced. */
+    private fsyncChain;
+    /**
+     * Mode A (the only mode claimed): a failed directory fsync is a warning of the write primitive, never a reason to refuse or
+     * to continue differently — durability verification (`DV`) is Mode B and is not called here (Design A section 18.2).
+     */
+    private fsyncDir;
+}
+//# sourceMappingURL=fs-store.d.ts.map

package/dist/durable/fs-store.d.ts.map

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