@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export declare const PACKAGE_NAME = "@ceralive/modem-control";
+export * from './backend/index.js';
+export * from './band/index.js';
+export * from './capability/index.js';
+export * from './domain/index.js';
+export * from './fcc/index.js';
+export * from './hardware/router-parsers.js';
+export * from './journal/index.js';
+export * from './location/index.js';
+export * from './observations/index.js';
+export * from './operations/index.js';
+export * from './ports/index.js';
+export * from './providers/index.js';
+export * from './radio/index.js';
+export * from './redact.js';
+export * from './safety/index.js';
+export * from './sms/index.js';
+export * from './usb-mode/index.js';
+export * from './ussd/index.js';

package/dist/index.js

@@ -0,0 +1,26 @@
+// @ceralive/modem-control — package entry point.
+//
+// Phase A: the domain model (identity + orthogonal state + revisions) under
+// `./domain`, the MM / NM / Router port contracts + desired-state planner under
+// `./ports`, the redaction module (`./redact`), and the epoch-scoped ModemManager
+// D-Bus observer under `./backend`. The NetworkManager adapter, USB composition-mode
+// model, and data-usage sampler land in later waves.
+export const PACKAGE_NAME = '@ceralive/modem-control';
+export * from './backend/index.js';
+export * from './band/index.js';
+export * from './capability/index.js';
+export * from './domain/index.js';
+export * from './fcc/index.js';
+export * from './hardware/router-parsers.js';
+export * from './journal/index.js';
+export * from './location/index.js';
+export * from './observations/index.js';
+export * from './operations/index.js';
+export * from './ports/index.js';
+export * from './providers/index.js';
+export * from './radio/index.js';
+export * from './redact.js';
+export * from './safety/index.js';
+export * from './sms/index.js';
+export * from './usb-mode/index.js';
+export * from './ussd/index.js';

package/dist/journal/codec.d.ts

@@ -0,0 +1,44 @@
+import { type JournalEntry } from './entry.js';
+/** Why one record could not be read. `field` names the offending key, never its value. */
+export interface JournalDecodeFailure {
+    readonly code: 'empty' | 'invalid-json' | 'not-an-object' | 'unsupported-schema-version' | 'schema-mismatch' | 'unreadable';
+    readonly field?: string;
+    /** Byte offset for a JSON syntax error, when the runtime reported one. */
+    readonly offset?: number;
+}
+export type JournalDecodeResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly failure: JournalDecodeFailure;
+};
+declare function record(raw: unknown, field: string): Record<string, unknown>;
+declare function requiredString(source: Record<string, unknown>, field: string): string;
+declare function optionalString(source: Record<string, unknown>, field: string): string | undefined;
+declare function requiredNonNegativeInteger(source: Record<string, unknown>, field: string): number;
+declare function member<T extends string>(source: Record<string, unknown>, field: string, allowed: readonly T[]): T;
+/**
+ * Serialize one entry to a single line WITHOUT its terminator.
+ *
+ * Keys are emitted in a fixed order because the round-trip tests compare bytes,
+ * and byte comparison is the only assertion that catches a field a reader silently
+ * dropped (`JSON.parse` + a permissive validator will happily lose one and still
+ * report success — the same trap the srtla telemetry byte-parity suite exists for).
+ */
+export declare function encodeJournalEntry(entry: JournalEntry): string;
+/** Decode one line. An empty/whitespace-only line is reported, never silently dropped. */
+export declare function decodeJournalEntry(line: string): JournalDecodeResult<JournalEntry>;
+/** Decode an arbitrary JSON document with a caller-supplied validator. */
+export declare function decodeJournalDocument<T>(text: string, validate: (raw: unknown) => T): JournalDecodeResult<T>;
+/** The validator helpers the legacy reader reuses, so both shapes fail the same way. */
+export declare const journalSchema: {
+    readonly record: typeof record;
+    readonly requiredString: typeof requiredString;
+    readonly optionalString: typeof optionalString;
+    readonly requiredNonNegativeInteger: typeof requiredNonNegativeInteger;
+    readonly member: typeof member;
+    readonly schemaError: (field: string) => Error;
+    readonly schemaVersionError: () => Error;
+};
+export {};

package/dist/journal/codec.js

@@ -0,0 +1,198 @@
+// Line codec for the journal: exactly one entry per line, JSON, no wrapper.
+//
+// WHY DECODING RETURNS A RESULT INSTEAD OF THROWING. A journal is read at exactly
+// one moment — recovery after an unclean restart — and that is the moment a throw
+// is most expensive: it aborts the read at the first damaged byte and takes every
+// still-valid entry after it with it. The whole point of this module is that a
+// damaged record is DATA, reported alongside the records that survived, so nothing
+// earlier or later is discarded to make one bad line disappear.
+//
+// FAILURES NAME A FIELD, NEVER CONTENT. Same rule the two policy stores follow: a
+// classification carries the offending field name and a byte count, never the bytes
+// themselves, because a journal line can hold provider identifiers and refusal
+// reasons and a log line is the wrong place to reproduce them.
+import { MODEM_CONTROL_JOURNAL_SCHEMA_VERSION, } from './entry.js';
+class SchemaError extends Error {
+    field;
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+        this.field = field;
+    }
+}
+class SchemaVersionError extends Error {
+    constructor() {
+        super('unsupported-schema-version');
+    }
+}
+function record(raw, field) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new SchemaError(field);
+    return raw;
+}
+function requiredString(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string' || value.length === 0)
+        throw new SchemaError(field);
+    return value;
+}
+function optionalString(source, field) {
+    const value = source[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new SchemaError(field);
+    return value;
+}
+function requiredNonNegativeInteger(source, field) {
+    const value = source[field];
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+function requiredStringArray(source, field) {
+    const value = source[field];
+    if (!Array.isArray(value) || value.some((member) => typeof member !== 'string')) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+function member(source, field, allowed) {
+    const value = source[field];
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+const AUTHORITIES = ['provider', 'controller', 'hardware'];
+const IMPACTS = ['read', 'write', 'session', 'disruptive', 'recovery'];
+const CONFIDENCES = ['high', 'medium', 'low', 'unknown'];
+const UNKNOWN_OUTCOME_REASONS = [
+    'stale-generation',
+    'write-reply-timed-out',
+    'write-reply-dropped',
+];
+function parseDescriptor(raw) {
+    const source = record(raw, 'descriptor');
+    return {
+        descriptorId: requiredString(source, 'descriptorId'),
+        provider: requiredString(source, 'provider'),
+        authority: member(source, 'authority', AUTHORITIES),
+        mutationImpact: member(source, 'mutationImpact', IMPACTS),
+        profiles: requiredStringArray(source, 'profiles'),
+        firmware: requiredStringArray(source, 'firmware'),
+        confidence: member(source, 'confidence', CONFIDENCES),
+    };
+}
+function parseOutcome(raw) {
+    const source = record(raw, 'outcome');
+    switch (member(source, 'status', ['applied', 'refused', 'failed', 'unknown-outcome'])) {
+        case 'applied':
+            return { status: 'applied' };
+        case 'refused':
+            return { status: 'refused', reason: requiredString(source, 'reason') };
+        case 'failed':
+            return { status: 'failed', reason: requiredString(source, 'reason') };
+        case 'unknown-outcome':
+            return {
+                status: 'unknown-outcome',
+                reason: member(source, 'reason', UNKNOWN_OUTCOME_REASONS),
+            };
+    }
+}
+function parseEntry(raw) {
+    const source = record(raw, 'entry');
+    if (source.schemaVersion !== MODEM_CONTROL_JOURNAL_SCHEMA_VERSION)
+        throw new SchemaVersionError();
+    const base = {
+        schemaVersion: MODEM_CONTROL_JOURNAL_SCHEMA_VERSION,
+        operationId: requiredString(source, 'operationId'),
+        physicalModemId: requiredString(source, 'physicalModemId'),
+        generation: requiredNonNegativeInteger(source, 'generation'),
+        recordedAtMs: requiredNonNegativeInteger(source, 'recordedAtMs'),
+        descriptor: parseDescriptor(source.descriptor),
+    };
+    if (member(source, 'phase', ['started', 'completed']) === 'started') {
+        return { ...base, phase: 'started' };
+    }
+    return { ...base, phase: 'completed', outcome: parseOutcome(source.outcome) };
+}
+/** Classify a decode failure into a metadata-only result (never raw content). */
+function classify(error) {
+    if (error instanceof SchemaVersionError)
+        return { code: 'unsupported-schema-version' };
+    if (error instanceof SchemaError)
+        return { code: 'schema-mismatch', field: error.field };
+    if (error instanceof SyntaxError) {
+        const offset = /position (\d+)/.exec(error.message)?.[1];
+        return offset === undefined
+            ? { code: 'invalid-json' }
+            : { code: 'invalid-json', offset: Number(offset) };
+    }
+    return { code: 'unreadable' };
+}
+/**
+ * Serialize one entry to a single line WITHOUT its terminator.
+ *
+ * Keys are emitted in a fixed order because the round-trip tests compare bytes,
+ * and byte comparison is the only assertion that catches a field a reader silently
+ * dropped (`JSON.parse` + a permissive validator will happily lose one and still
+ * report success — the same trap the srtla telemetry byte-parity suite exists for).
+ */
+export function encodeJournalEntry(entry) {
+    const descriptor = {
+        descriptorId: entry.descriptor.descriptorId,
+        provider: entry.descriptor.provider,
+        authority: entry.descriptor.authority,
+        mutationImpact: entry.descriptor.mutationImpact,
+        profiles: entry.descriptor.profiles,
+        firmware: entry.descriptor.firmware,
+        confidence: entry.descriptor.confidence,
+    };
+    const base = {
+        schemaVersion: entry.schemaVersion,
+        phase: entry.phase,
+        operationId: entry.operationId,
+        physicalModemId: entry.physicalModemId,
+        generation: entry.generation,
+        recordedAtMs: entry.recordedAtMs,
+        descriptor,
+    };
+    return JSON.stringify(entry.phase === 'started' ? base : { ...base, outcome: entry.outcome });
+}
+/** Decode one line. An empty/whitespace-only line is reported, never silently dropped. */
+export function decodeJournalEntry(line) {
+    if (line.trim().length === 0)
+        return { ok: false, failure: { code: 'empty' } };
+    try {
+        return { ok: true, value: parseEntry(JSON.parse(line)) };
+    }
+    catch (error) {
+        return { ok: false, failure: classify(error) };
+    }
+}
+/** Decode an arbitrary JSON document with a caller-supplied validator. */
+export function decodeJournalDocument(text, validate) {
+    if (text.trim().length === 0)
+        return { ok: false, failure: { code: 'empty' } };
+    try {
+        return { ok: true, value: validate(JSON.parse(text)) };
+    }
+    catch (error) {
+        return { ok: false, failure: classify(error) };
+    }
+}
+/** The validator helpers the legacy reader reuses, so both shapes fail the same way. */
+export const journalSchema = {
+    record,
+    requiredString,
+    optionalString,
+    requiredNonNegativeInteger,
+    member,
+    schemaError(field) {
+        return new SchemaError(field);
+    },
+    schemaVersionError() {
+        return new SchemaVersionError();
+    },
+};

package/dist/journal/engine.d.ts

@@ -0,0 +1,28 @@
+import type { OperationJournalEvent, OperationJournalHook } from '../operations/contracts.js';
+import { type JournalRecovery } from './recovery.js';
+import type { JournalStore } from './store.js';
+export interface JournalEngineOptions {
+    /** The store — and therefore the path — is supplied by the composition root. */
+    readonly store: JournalStore;
+    readonly now?: () => number;
+}
+export declare class JournalEngine {
+    #private;
+    constructor(options: JournalEngineOptions);
+    /** Where this engine journals to; useful in a recovery log line. */
+    get path(): string;
+    /**
+     * The `OperationJournalHook` implementation.
+     *
+     * Generic per CALL rather than per instance, so one engine journals every
+     * descriptor in the process. A generic method satisfies the non-generic
+     * `OperationJournalHook<I, O>` member by instantiation, which is what lets an
+     * `OperationExecution` take the engine itself as its `journal`.
+     */
+    record<I, O>(event: OperationJournalEvent<I, O>): Promise<void>;
+    /** An explicitly typed hook, for a caller that prefers a narrow object. */
+    hook<I, O>(): OperationJournalHook<I, O>;
+    /** Read the journal back and reconstruct what was in flight. */
+    recover(): Promise<JournalRecovery>;
+}
+export declare function createJournalEngine(options: JournalEngineOptions): JournalEngine;

package/dist/journal/engine.js

@@ -0,0 +1,68 @@
+// The journal engine: the operation engine's journal hook, plus replay.
+//
+// `OperationExecution.journal` (todo 20's `OperationJournalHook`) is the seam the
+// operation engine already calls at `started` and at `completed`, and a descriptor
+// that declares `journal: { required: true }` is REFUSED outright when no hook is
+// supplied. This class is the durable implementation of that seam: it flattens the
+// event onto a journal entry and appends it, and it reads the same file back.
+//
+// THE ENGINE HOLDS NO PATH. It holds a `JournalStore`, and the store was handed a
+// path by whoever composed it. That is the same injection shape todo 19 used for
+// the ownership lock (`FlockResourceOwnershipOptions.lockPath` is REQUIRED and the
+// adapter substitutes nothing) and the same reason: an embedding process owns its
+// filesystem layout, and a library that guesses one is a library that writes to the
+// wrong disk on a device it has never seen.
+//
+// THE CLOCK IS INJECTED TOO. `now` defaults to `Date.now`, but a test that wants
+// deterministic timestamps supplies its own — the observation layer's rule that
+// this package never stamps data with a time it did not come from applies here as
+// well, and a replay assertion over timestamps must not be a race.
+import { journalDescriptorEvidence, journalOutcome } from './entry.js';
+import { reconstructJournalRecovery } from './recovery.js';
+export class JournalEngine {
+    #store;
+    #now;
+    constructor(options) {
+        this.#store = options.store;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    /** Where this engine journals to; useful in a recovery log line. */
+    get path() {
+        return this.#store.path;
+    }
+    /**
+     * The `OperationJournalHook` implementation.
+     *
+     * Generic per CALL rather than per instance, so one engine journals every
+     * descriptor in the process. A generic method satisfies the non-generic
+     * `OperationJournalHook<I, O>` member by instantiation, which is what lets an
+     * `OperationExecution` take the engine itself as its `journal`.
+     */
+    record(event) {
+        return this.#store.append(entryFor(event, this.#now()));
+    }
+    /** An explicitly typed hook, for a caller that prefers a narrow object. */
+    hook() {
+        return { record: (event) => this.record(event) };
+    }
+    /** Read the journal back and reconstruct what was in flight. */
+    async recover() {
+        return reconstructJournalRecovery(await this.#store.read());
+    }
+}
+function entryFor(event, recordedAtMs) {
+    const base = {
+        schemaVersion: 1,
+        operationId: event.operationId,
+        physicalModemId: event.physicalModemId,
+        generation: event.generation,
+        recordedAtMs,
+        descriptor: journalDescriptorEvidence(event.descriptor),
+    };
+    return event.phase === 'started'
+        ? { ...base, phase: 'started' }
+        : { ...base, phase: 'completed', outcome: journalOutcome(event.result) };
+}
+export function createJournalEngine(options) {
+    return new JournalEngine(options);
+}

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>;