@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/journal/entry.d.ts

@@ -0,0 +1,74 @@
+import type { MutationImpact, OperationConfidence, OperationDescriptor, OperationResult } from '../domain/index.js';
+/** The current on-disk schema version for one journal line. */
+export declare const MODEM_CONTROL_JOURNAL_SCHEMA_VERSION = 1;
+/** The two phases the operation engine emits, mirrored one-to-one on disk. */
+export type JournalPhase = 'started' | 'completed';
+/**
+ * How an operation ended, projected from `OperationResult` WITHOUT its value.
+ *
+ * `unknown-outcome` keeps the frozen domain reason union verbatim rather than
+ * widening to `string`, because those three reasons are the entire vocabulary a
+ * recovery pass branches on and a fourth spelling would silently read as an
+ * ordinary failure.
+ */
+export type JournalOutcome = {
+    readonly status: 'applied';
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+} | {
+    readonly status: 'failed';
+    readonly reason: string;
+} | {
+    readonly status: 'unknown-outcome';
+    readonly reason: 'stale-generation' | 'write-reply-timed-out' | 'write-reply-dropped';
+};
+/**
+ * The descriptor facts a recovery pass needs, flattened out of the descriptor.
+ *
+ * The descriptor itself is not persisted: it carries FUNCTIONS (`readback.matches`,
+ * the constraint predicates) that no serialization round-trips, so storing it would
+ * produce a document that reads back as a different object than it was written from.
+ * These are the fields that answer "what was being changed, by whom, on what
+ * evidence" — everything a human or a reconciler needs to judge a stranded write.
+ */
+export interface JournalDescriptorEvidence {
+    readonly descriptorId: string;
+    readonly provider: string;
+    readonly authority: 'provider' | 'controller' | 'hardware';
+    readonly mutationImpact: MutationImpact;
+    readonly profiles: readonly string[];
+    readonly firmware: readonly string[];
+    readonly confidence: OperationConfidence;
+}
+interface JournalEntryBase {
+    readonly schemaVersion: typeof MODEM_CONTROL_JOURNAL_SCHEMA_VERSION;
+    readonly operationId: string;
+    /** The serialized `PhysicalModemId`. Stored as text; branding is a compile-time fact. */
+    readonly physicalModemId: string;
+    /** The serialized `DeviceGeneration` the operation was fenced to. */
+    readonly generation: number;
+    readonly recordedAtMs: number;
+    readonly descriptor: JournalDescriptorEvidence;
+}
+/**
+ * One journal line.
+ *
+ * The two members differ in SHAPE, not just in a label: a `started` entry has no
+ * `outcome` KEY at all. That is the same rule `observations/reading.ts` follows —
+ * a consumer cannot read an outcome off a phase that has none, so "in flight" can
+ * never be mistaken for "ended with an unset outcome".
+ */
+export type JournalEntry = (JournalEntryBase & {
+    readonly phase: 'started';
+}) | (JournalEntryBase & {
+    readonly phase: 'completed';
+    readonly outcome: JournalOutcome;
+});
+/** Flatten a descriptor down to the serializable evidence the journal keeps. */
+export declare function journalDescriptorEvidence<I, O>(descriptor: OperationDescriptor<I, O>): JournalDescriptorEvidence;
+/** Project a result onto its journalable outcome, dropping the value by design. */
+export declare function journalOutcome<O>(result: OperationResult<O>): JournalOutcome;
+/** True when an outcome leaves the device in a state nobody has read back. */
+export declare function outcomeRequiresReconciliation(outcome: JournalOutcome): boolean;
+export {};

package/dist/journal/entry.js

@@ -0,0 +1,56 @@
+// The transaction journal's ENTRY vocabulary.
+//
+// The journal exists to answer ONE question after an unclean restart: which
+// mutations were in flight, and which of them ended in an outcome nobody can
+// read off the device. `operations/operation-engine.ts` already closes a
+// per-modem gate when a write classifies `unknown-outcome`, but that gate lives
+// in a `Set` on the engine instance — a process death takes it with it. Writing
+// the same two facts down is what makes the gate survive the process.
+//
+// WHY AN EVENT LOG AND NOT A LATEST-STATE SNAPSHOT. A started event and its
+// completion are two facts separated by exactly the window a crash lands in, so
+// the shape has to be able to hold the first without the second. A document that
+// only ever carries "the current state" cannot distinguish "we never dispatched"
+// from "we dispatched and the reply never came" unless it spends a state name on
+// each — which is how CeraUI's own mutation journal does it (see
+// `legacy-ceraui.ts`, which reads that shape). Both are legitimate; this one is
+// append-only because appending is the only write that cannot lose a prior fact.
+//
+// WHAT IS DELIBERATELY NOT RECORDED: the operation's INPUT and the operation's
+// RETURNED VALUE. An input is routinely a PIN, a PUK, or a USSD command carrying
+// a voucher code, and a returned value is routinely a message body or a location
+// fix — all of them classes `../redact.ts` masks everywhere else. The journal
+// records THAT an operation ran and HOW it ended, never WHAT was sent or read.
+// A caller that needs a rollback payload owns persisting it beside the journal
+// under its own redaction decision.
+/** The current on-disk schema version for one journal line. */
+export const MODEM_CONTROL_JOURNAL_SCHEMA_VERSION = 1;
+/** Flatten a descriptor down to the serializable evidence the journal keeps. */
+export function journalDescriptorEvidence(descriptor) {
+    return {
+        descriptorId: descriptor.id,
+        provider: descriptor.provider,
+        authority: descriptor.authority,
+        mutationImpact: descriptor.mutationImpact,
+        profiles: [...descriptor.evidence.profiles],
+        firmware: [...descriptor.evidence.firmware],
+        confidence: descriptor.confidence,
+    };
+}
+/** Project a result onto its journalable outcome, dropping the value by design. */
+export function journalOutcome(result) {
+    switch (result.status) {
+        case 'applied':
+            return { status: 'applied' };
+        case 'refused':
+            return { status: 'refused', reason: result.reason };
+        case 'failed':
+            return { status: 'failed', reason: result.reason };
+        case 'unknown-outcome':
+            return { status: 'unknown-outcome', reason: result.reason };
+    }
+}
+/** True when an outcome leaves the device in a state nobody has read back. */
+export function outcomeRequiresReconciliation(outcome) {
+    return outcome.status === 'unknown-outcome';
+}

package/dist/journal/index.d.ts

@@ -0,0 +1,6 @@
+export * from './codec.js';
+export * from './engine.js';
+export * from './entry.js';
+export * from './legacy-ceraui.js';
+export * from './recovery.js';
+export * from './store.js';

package/dist/journal/index.js

@@ -0,0 +1,6 @@
+export * from './codec.js';
+export * from './engine.js';
+export * from './entry.js';
+export * from './legacy-ceraui.js';
+export * from './recovery.js';
+export * from './store.js';

package/dist/journal/legacy-ceraui.d.ts

@@ -0,0 +1,73 @@
+import { type JournalDecodeResult } from './codec.js';
+import type { JournalDescriptorEvidence } from './entry.js';
+import { type JournalOperationRecord, type JournalRecovery } from './recovery.js';
+/** The `version` literal CeraUI's schema pins. */
+export declare const LEGACY_CERAUI_JOURNAL_VERSION = 1;
+/** CeraUI's cap on retained history entries per slot. */
+export declare const LEGACY_CERAUI_HISTORY_CAP = 32;
+export declare const LEGACY_CERAUI_MUTATION_STATES: readonly ['armed', 'executing', 'completed', 'failed', 'acknowledged', 'device-absent-quarantine', 'decommissioned', 'recommission-pending'];
+export type LegacyCeraUiMutationState = (typeof LEGACY_CERAUI_MUTATION_STATES)[number];
+export declare const LEGACY_CERAUI_ACK_MODES: readonly ['verified-rollback', 'force-rebaseline'];
+export type LegacyCeraUiAckMode = (typeof LEGACY_CERAUI_ACK_MODES)[number];
+export interface LegacyCeraUiHistoryEntry {
+    readonly state: LegacyCeraUiMutationState;
+    readonly at: number;
+    readonly detail?: string;
+}
+/** One CeraUI slot document, decoded verbatim. `preState` is kept opaque. */
+export interface LegacyCeraUiMutationEntry {
+    readonly version: typeof LEGACY_CERAUI_JOURNAL_VERSION;
+    readonly stableKey: string;
+    readonly kind: string;
+    readonly state: LegacyCeraUiMutationState;
+    readonly attemptId: string;
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    /** The rollback target. Opaque by design — its shape is the mutation kind's. */
+    readonly preState: Readonly<Record<string, unknown>>;
+    readonly detail?: string;
+    readonly acknowledgedMode?: LegacyCeraUiAckMode;
+    readonly history: readonly LegacyCeraUiHistoryEntry[];
+}
+export interface LegacyCeraUiJournalRead {
+    /** The same recovery model `reconstructJournalRecovery` produces. */
+    readonly recovery: JournalRecovery;
+    /** The decoded slot documents, verbatim, so `preState` survives the read. */
+    readonly entries: readonly LegacyCeraUiMutationEntry[];
+}
+export interface LegacyCeraUiJournalOptions {
+    /** REQUIRED. The embedding process owns where CeraUI put its journal. */
+    readonly dir: string;
+}
+/**
+ * The slot filename CeraUI derives from a stable key.
+ *
+ * RULE-D MIRROR of CeraUI's own helper. It is a plain lowercase-hex SHA-256 of the
+ * key's UTF-8 bytes; the key itself never appears in the filename in plaintext.
+ */
+export declare function legacyMutationSlotName(stableKey: string): string;
+/** Validate one slot document. Throws the codec's metadata-only schema errors. */
+export declare function validateLegacyCeraUiEntry(raw: unknown): LegacyCeraUiMutationEntry;
+/** Decode one slot document's text. Never throws; returns a typed failure. */
+export declare function decodeLegacyCeraUiEntry(text: string): JournalDecodeResult<LegacyCeraUiMutationEntry>;
+/**
+ * The descriptor evidence a legacy entry can honestly supply.
+ *
+ * CeraUI's journal predates `OperationDescriptor`, so there is no descriptor to
+ * flatten. Every field below is either a fact the file actually carries (the
+ * mutation kind) or an explicit statement that the file carries nothing:
+ * `confidence: 'unknown'` rather than a borrowed default, and empty evidence
+ * arrays rather than invented profiles. `mutationImpact: 'write'` is a fact, not a
+ * guess — CeraUI's file is a MUTATION journal and records nothing else.
+ */
+export declare function legacyDescriptorEvidence(kind: string): JournalDescriptorEvidence;
+/** Project one decoded slot onto the shared recovery record model. */
+export declare function legacyOperationRecord(entry: LegacyCeraUiMutationEntry): JournalOperationRecord;
+/**
+ * Read a whole CeraUI journal directory.
+ *
+ * An unreadable or non-conforming slot is reported as damage and LEFT IN PLACE;
+ * every readable slot still comes back. That is the same non-truncating contract
+ * the native store makes, applied to a directory instead of a file.
+ */
+export declare function readLegacyCeraUiJournal(options: LegacyCeraUiJournalOptions): Promise<LegacyCeraUiJournalRead>;

package/dist/journal/legacy-ceraui.js

@@ -0,0 +1,227 @@
+// COMPATIBILITY READ PATH for the mutation journal CeraUI already writes.
+//
+// WHY THIS EXISTS AT ALL. CeraUI has kept a durable modem-mutation journal since
+// long before this package had one, and devices in the field have those files on
+// disk right now. The two shapes are genuinely different — this package's journal
+// is an append-only EVENT LOG in one file, CeraUI's is a directory of per-modem
+// LATEST-STATE SNAPSHOTS, one JSON document per modem, rewritten whole on every
+// transition. Neither can be re-labelled into the other, so the bridge is a READER:
+// it decodes CeraUI's shape into the SAME `JournalOperationRecord` model
+// `recovery.ts` produces, so a consumer enumerates pending and unknown-outcome work
+// across both without CeraUI having to change its file format first.
+//
+// NOTHING HERE WRITES. This module reads and decodes; it never rewrites, repairs,
+// migrates in place, or deletes a slot. CeraUI's own reader leaves an unreadable
+// slot on disk deliberately, and a second reader that "cleaned up" behind it would
+// destroy the evidence CeraUI kept on purpose.
+//
+// THE DIRECTORY IS INJECTED, exactly like the native store's path — this module
+// hardcodes no location, and the path-injection gate covers it.
+//
+// THE SLOT FILENAME IS A HASH, and `legacyMutationSlotName` mirrors that rule so a
+// consumer can address ONE modem's slot without scanning. It is a RULE-D MIRROR of
+// CeraUI's helper, never a shared import — the same relationship the support-claim
+// ladder and the redaction key sets already have with their CeraUI twins.
+//
+// TWO MAPPING DECISIONS CARRY WEIGHT:
+//
+//  * `armed` maps to `pending` and `executing` maps to `unknown-outcome`. They are
+//    not the same fact. `armed` says the pre-state was captured and the write had
+//    not been dispatched, so the device is untouched. `executing` says the write
+//    WAS dispatched and no terminal state was ever recorded — which is precisely
+//    what this package calls an unknown outcome. Collapsing them would either
+//    invent certainty about a dispatched write or manufacture doubt about one that
+//    never left.
+//
+//  * `kind` is validated as a NON-EMPTY STRING, not against a frozen enum.
+//    CeraUI's runtime enum spreads its capability-module mutation kinds into the
+//    list, so the vocabulary grows on CeraUI's release cycle. Freezing a copy here
+//    would make this reader reject a perfectly valid file the day CeraUI adds a
+//    capability module — a compatibility reader that fails closed on new-but-valid
+//    input is worse than no reader at all.
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { decodeJournalDocument, journalSchema } from './codec.js';
+import { summarizeJournalRecords, } from './recovery.js';
+/** The `version` literal CeraUI's schema pins. */
+export const LEGACY_CERAUI_JOURNAL_VERSION = 1;
+/** CeraUI's cap on retained history entries per slot. */
+export const LEGACY_CERAUI_HISTORY_CAP = 32;
+export const LEGACY_CERAUI_MUTATION_STATES = [
+    'armed',
+    'executing',
+    'completed',
+    'failed',
+    'acknowledged',
+    'device-absent-quarantine',
+    'decommissioned',
+    'recommission-pending',
+];
+export const LEGACY_CERAUI_ACK_MODES = ['verified-rollback', 'force-rebaseline'];
+/**
+ * The slot filename CeraUI derives from a stable key.
+ *
+ * RULE-D MIRROR of CeraUI's own helper. It is a plain lowercase-hex SHA-256 of the
+ * key's UTF-8 bytes; the key itself never appears in the filename in plaintext.
+ */
+export function legacyMutationSlotName(stableKey) {
+    return createHash('sha256').update(stableKey, 'utf8').digest('hex');
+}
+function parseHistoryEntry(raw) {
+    const source = journalSchema.record(raw, 'history[]');
+    const detail = journalSchema.optionalString(source, 'detail');
+    return {
+        state: journalSchema.member(source, 'state', LEGACY_CERAUI_MUTATION_STATES),
+        at: journalSchema.requiredNonNegativeInteger(source, 'at'),
+        ...(detail === undefined ? {} : { detail }),
+    };
+}
+/** Validate one slot document. Throws the codec's metadata-only schema errors. */
+export function validateLegacyCeraUiEntry(raw) {
+    const source = journalSchema.record(raw, 'entry');
+    if (source.version !== LEGACY_CERAUI_JOURNAL_VERSION)
+        throw journalSchema.schemaVersionError();
+    const history = source.history;
+    if (!Array.isArray(history) || history.length > LEGACY_CERAUI_HISTORY_CAP) {
+        throw journalSchema.schemaError('history');
+    }
+    const detail = journalSchema.optionalString(source, 'detail');
+    const acknowledgedMode = source.acknowledgedMode === undefined
+        ? undefined
+        : journalSchema.member(source, 'acknowledgedMode', LEGACY_CERAUI_ACK_MODES);
+    return {
+        version: LEGACY_CERAUI_JOURNAL_VERSION,
+        stableKey: journalSchema.requiredString(source, 'stableKey'),
+        kind: journalSchema.requiredString(source, 'kind'),
+        state: journalSchema.member(source, 'state', LEGACY_CERAUI_MUTATION_STATES),
+        attemptId: journalSchema.requiredString(source, 'attemptId'),
+        startedAt: journalSchema.requiredNonNegativeInteger(source, 'startedAt'),
+        updatedAt: journalSchema.requiredNonNegativeInteger(source, 'updatedAt'),
+        preState: journalSchema.record(source.preState, 'preState'),
+        ...(detail === undefined ? {} : { detail }),
+        ...(acknowledgedMode === undefined ? {} : { acknowledgedMode }),
+        history: history.map(parseHistoryEntry),
+    };
+}
+/** Decode one slot document's text. Never throws; returns a typed failure. */
+export function decodeLegacyCeraUiEntry(text) {
+    return decodeJournalDocument(text, validateLegacyCeraUiEntry);
+}
+const DISPOSITION_BY_STATE = {
+    // Pre-state captured, write never dispatched: the device is untouched.
+    armed: 'pending',
+    // Dispatched with no terminal record — this package's `unknown-outcome`.
+    executing: 'unknown-outcome',
+    completed: 'resolved',
+    // CeraUI's replay keeps these on disk and refuses further mutations until an
+    // operator acknowledges. That is a KNOWN bad ending, not an unknown one.
+    failed: 'blocked',
+    acknowledged: 'resolved',
+    'device-absent-quarantine': 'blocked',
+    decommissioned: 'blocked',
+    'recommission-pending': 'blocked',
+};
+/**
+ * The descriptor evidence a legacy entry can honestly supply.
+ *
+ * CeraUI's journal predates `OperationDescriptor`, so there is no descriptor to
+ * flatten. Every field below is either a fact the file actually carries (the
+ * mutation kind) or an explicit statement that the file carries nothing:
+ * `confidence: 'unknown'` rather than a borrowed default, and empty evidence
+ * arrays rather than invented profiles. `mutationImpact: 'write'` is a fact, not a
+ * guess — CeraUI's file is a MUTATION journal and records nothing else.
+ */
+export function legacyDescriptorEvidence(kind) {
+    return {
+        descriptorId: kind,
+        provider: 'ceraui-legacy',
+        authority: 'controller',
+        mutationImpact: 'write',
+        profiles: [],
+        firmware: [],
+        confidence: 'unknown',
+    };
+}
+/** Project one decoded slot onto the shared recovery record model. */
+export function legacyOperationRecord(entry) {
+    const disposition = DISPOSITION_BY_STATE[entry.state];
+    return {
+        operationId: entry.attemptId,
+        // CeraUI's `stableKey`, NOT a `PhysicalModemId` — see the note on the field.
+        physicalModemId: entry.stableKey,
+        // CeraUI's journal has no device-generation fence; 0 records "unfenced"
+        // rather than claiming a generation the file never carried.
+        generation: 0,
+        descriptor: legacyDescriptorEvidence(entry.kind),
+        disposition,
+        origin: 'legacy-ceraui',
+        startedAtMs: entry.startedAt,
+        updatedAtMs: entry.updatedAt,
+        // One slot is one attempt; CeraUI rewrites the slot rather than appending.
+        attempts: 1,
+        // `outcome` is deliberately ABSENT for every legacy record, including the
+        // `unknown-outcome` one. `JournalOutcome`'s unknown reason union is the
+        // frozen domain vocabulary — `stale-generation` / `write-reply-timed-out` /
+        // `write-reply-dropped` — and CeraUI's `executing` state asserts none of
+        // them: it says a write was dispatched and never concluded, not why. Naming
+        // one anyway would be the invented reading this package refuses everywhere
+        // else. The disposition carries the fact; the reason stays unclaimed.
+    };
+}
+/**
+ * Read a whole CeraUI journal directory.
+ *
+ * An unreadable or non-conforming slot is reported as damage and LEFT IN PLACE;
+ * every readable slot still comes back. That is the same non-truncating contract
+ * the native store makes, applied to a directory instead of a file.
+ */
+export async function readLegacyCeraUiJournal(options) {
+    let names;
+    try {
+        names = await readdir(options.dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { recovery: summarizeJournalRecords([], []), entries: [] };
+        }
+        return {
+            recovery: summarizeJournalRecords([], [{ location: { kind: 'file' }, bytes: 0, failure: { code: 'unreadable' } }]),
+            entries: [],
+        };
+    }
+    const entries = [];
+    const damage = [];
+    // Sorted so a recovery report is stable across filesystems that do not order
+    // `readdir`; the slot names are hashes, so the order carries no other meaning.
+    for (const name of [...names].sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        let text;
+        try {
+            text = await readFile(join(options.dir, name), 'utf8');
+        }
+        catch {
+            damage.push({
+                location: { kind: 'slot', slot: name },
+                bytes: 0,
+                failure: { code: 'unreadable' },
+            });
+            continue;
+        }
+        const decoded = decodeLegacyCeraUiEntry(text);
+        if (decoded.ok) {
+            entries.push(decoded.value);
+            continue;
+        }
+        damage.push({
+            location: { kind: 'slot', slot: name },
+            bytes: Buffer.byteLength(text, 'utf8'),
+            failure: decoded.failure,
+        });
+    }
+    return {
+        recovery: summarizeJournalRecords(entries.map(legacyOperationRecord), damage),
+        entries,
+    };
+}

package/dist/journal/recovery.d.ts

@@ -0,0 +1,58 @@
+import { DomainError } from '../domain/index.js';
+import type { JournalDescriptorEvidence, JournalOutcome } from './entry.js';
+import type { JournalDamageRecord, JournalReadResult } from './store.js';
+export type JournalRecoveryDisposition = 'pending' | 'unknown-outcome' | 'resolved' | 'blocked';
+/** Where a record came from. Also tells a consumer how to read `physicalModemId`. */
+export type JournalRecordOrigin = 'native' | 'legacy-ceraui';
+/**
+ * One operation reconstructed from the journal.
+ *
+ * `physicalModemId` is TEXT, not the branded `PhysicalModemId`, and that is
+ * deliberate: for a `legacy-ceraui` record it holds CeraUI's own `stableKey`,
+ * which is a different identity vocabulary and would be REFUSED by
+ * `physicalModemId()`'s constructor. Coercing it would either throw on a
+ * perfectly valid legacy file or launder a foreign identity into a branded type
+ * that promises it came from the serial / ID_PATH ladder. `origin` is what tells
+ * a consumer which vocabulary it is holding.
+ */
+export interface JournalOperationRecord {
+    readonly operationId: string;
+    readonly physicalModemId: string;
+    readonly generation: number;
+    readonly descriptor: JournalDescriptorEvidence;
+    readonly disposition: JournalRecoveryDisposition;
+    readonly origin: JournalRecordOrigin;
+    readonly startedAtMs: number;
+    readonly updatedAtMs: number;
+    readonly attempts: number;
+    readonly outcome?: JournalOutcome;
+}
+export interface JournalRecovery {
+    /** Every reconstructed operation, in first-appearance order. */
+    readonly records: readonly JournalOperationRecord[];
+    readonly pending: readonly JournalOperationRecord[];
+    readonly unknownOutcome: readonly JournalOperationRecord[];
+    readonly blocked: readonly JournalOperationRecord[];
+    /** Distinct modem identities that must be reconciled before the next mutation. */
+    readonly reconciliationRequired: readonly string[];
+    readonly damage: readonly JournalDamageRecord[];
+}
+/** Raised only by `assertJournalIntact`; recovery itself always returns a report. */
+export declare class JournalRecoveryError extends DomainError {
+    readonly name = "JournalRecoveryError";
+    readonly damage: readonly JournalDamageRecord[];
+    constructor(damage: readonly JournalDamageRecord[]);
+}
+/**
+ * Escalate a damaged journal to a throw, for a caller that wants fail-closed.
+ *
+ * Kept SEPARATE from `reconstructJournalRecovery` on purpose: recovery must be
+ * able to hand back the survivors even when part of the file is unreadable, so
+ * the decision to refuse to proceed belongs to the caller, after it has seen
+ * what did survive.
+ */
+export declare function assertJournalIntact(recovery: JournalRecovery): void;
+/** Fold decoded entries into per-operation records. Pure; no clock, no I/O. */
+export declare function reconstructJournalRecovery(read: JournalReadResult): JournalRecovery;
+/** Build the summary views over already-reconstructed records (native or legacy). */
+export declare function summarizeJournalRecords(records: readonly JournalOperationRecord[], damage: readonly JournalDamageRecord[]): JournalRecovery;

package/dist/journal/recovery.js

@@ -0,0 +1,117 @@
+// Replay: fold a journal back into "what was in flight when we died".
+//
+// This is the whole reason the journal exists. `operations/operation-engine.ts`
+// keeps its uncertainty fence in a `Set<PhysicalModemId>` on the engine instance,
+// so a process death drops it and the next mutation proceeds as if nothing were
+// outstanding. Folding the journal reconstructs that set from disk.
+//
+// THE FOLD IS ORDER-SENSITIVE AND LAST-WRITE-WINS PER OPERATION. Entries are
+// applied in file order, keyed by (physical modem, operation id, generation). A
+// second `started` on a live key is a re-run and re-opens the record rather than
+// being deduplicated away — the journal records attempts, and hiding a second
+// attempt would make a retry loop invisible in exactly the forensics the file is
+// kept for.
+//
+// FOUR DISPOSITIONS, AND TWO OF THEM MEAN "RECONCILE BEFORE MUTATING AGAIN":
+//
+//   pending          a start with no completion — the process died inside the
+//                    operation, so whether the device changed is unknown.
+//   unknown-outcome  a completion the engine itself classified unknown: a stale
+//                    generation, or a write reply that timed out or was dropped.
+//   resolved         a definite ending (applied / refused / failed). The engine
+//                    treats a definite failure as definite; so does this.
+//   blocked          a terminal state a human must clear. Native journals never
+//                    produce it today — it exists because CeraUI's own mutation
+//                    journal HAS such states (`failed`, quarantine, decommission)
+//                    and `legacy-ceraui.ts` maps onto this same model. Folding
+//                    those into `resolved` would report an operator-blocked device
+//                    as healthy; folding them into `unknown-outcome` would claim
+//                    uncertainty about an outcome that is actually known.
+//
+// `reconciliationRequired` deliberately covers `pending` + `unknown-outcome` only.
+// A blocked record is a KNOWN bad ending awaiting acknowledgement, and answering
+// it with a reconciliation pass would silently clear a state that exists precisely
+// so it cannot be cleared silently.
+import { DomainError } from '../domain/index.js';
+/** Raised only by `assertJournalIntact`; recovery itself always returns a report. */
+export class JournalRecoveryError extends DomainError {
+    name = 'JournalRecoveryError';
+    damage;
+    constructor(damage) {
+        super(`journal recovery found ${damage.length} damaged record(s)`);
+        this.damage = damage;
+    }
+}
+/**
+ * Escalate a damaged journal to a throw, for a caller that wants fail-closed.
+ *
+ * Kept SEPARATE from `reconstructJournalRecovery` on purpose: recovery must be
+ * able to hand back the survivors even when part of the file is unreadable, so
+ * the decision to refuse to proceed belongs to the caller, after it has seen
+ * what did survive.
+ */
+export function assertJournalIntact(recovery) {
+    if (recovery.damage.length > 0)
+        throw new JournalRecoveryError(recovery.damage);
+}
+function keyOf(entry) {
+    return `${entry.physicalModemId}\u0000${entry.operationId}\u0000${entry.generation}`;
+}
+function dispositionOf(outcome) {
+    return outcome.status === 'unknown-outcome' ? 'unknown-outcome' : 'resolved';
+}
+/** Fold decoded entries into per-operation records. Pure; no clock, no I/O. */
+export function reconstructJournalRecovery(read) {
+    const byKey = new Map();
+    const order = [];
+    for (const { entry } of read.entries) {
+        const key = keyOf(entry);
+        const previous = byKey.get(key);
+        if (previous === undefined)
+            order.push(key);
+        if (entry.phase === 'started') {
+            byKey.set(key, {
+                operationId: entry.operationId,
+                physicalModemId: entry.physicalModemId,
+                generation: entry.generation,
+                descriptor: entry.descriptor,
+                disposition: 'pending',
+                origin: 'native',
+                // The FIRST start is when this operation began; a re-run does not
+                // rewrite history, it increments the attempt count.
+                startedAtMs: previous?.startedAtMs ?? entry.recordedAtMs,
+                updatedAtMs: entry.recordedAtMs,
+                attempts: (previous?.attempts ?? 0) + 1,
+            });
+            continue;
+        }
+        byKey.set(key, {
+            operationId: entry.operationId,
+            physicalModemId: entry.physicalModemId,
+            generation: entry.generation,
+            descriptor: entry.descriptor,
+            disposition: dispositionOf(entry.outcome),
+            origin: 'native',
+            startedAtMs: previous?.startedAtMs ?? entry.recordedAtMs,
+            updatedAtMs: entry.recordedAtMs,
+            // A completion with no start is a journal whose head was never written;
+            // counting it as one attempt is more honest than reporting zero.
+            attempts: previous?.attempts ?? 1,
+            outcome: entry.outcome,
+        });
+    }
+    const records = order
+        .map((key) => byKey.get(key))
+        .filter((value) => value !== undefined);
+    return summarizeJournalRecords(records, read.damage);
+}
+/** Build the summary views over already-reconstructed records (native or legacy). */
+export function summarizeJournalRecords(records, damage) {
+    const pending = records.filter((record) => record.disposition === 'pending');
+    const unknownOutcome = records.filter((record) => record.disposition === 'unknown-outcome');
+    const blocked = records.filter((record) => record.disposition === 'blocked');
+    const reconciliationRequired = [
+        ...new Set([...pending, ...unknownOutcome].map((record) => record.physicalModemId)),
+    ].sort();
+    return { records, pending, unknownOutcome, blocked, reconciliationRequired, damage };
+}