@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/core/schedule/schedulerStep.js

@@ -0,0 +1,144 @@
+export const INITIAL_SCHEDULER_STATE = { kind: 'idle' };
+/**
+ * The transitions of design 1.15, one function per state. Every event a
+ * state does not draw returns that state unchanged with no effects.
+ */
+export function schedulerStep(state, event, timing) {
+    switch (state.kind) {
+        case 'idle':
+            return fromIdle(state, event, timing);
+        case 'waiting':
+            return fromWaiting(state, event, timing);
+        case 'syncing':
+            return fromSyncing(state, event, timing);
+        case 'stopping':
+            return fromStopping(state, event);
+        case 'stopped':
+        case 'halted':
+            return unchanged(state);
+    }
+}
+function fromIdle(state, event, timing) {
+    switch (event.type) {
+        case 'started':
+            return runCycle(false);
+        case 'changed':
+            return {
+                state: {
+                    kind: 'waiting',
+                    firstChangeAt: event.at,
+                    lastChangeAt: event.at,
+                },
+                effects: [{ type: 'armQuietTimer', fireAt: event.at + timing.quietMs }],
+            };
+        case 'pollDue':
+            return runCycle(false);
+        case 'stopRequested':
+            return endNow('stopped');
+        case 'quietElapsed':
+        case 'cycleFinished':
+            return unchanged(state);
+    }
+}
+function fromWaiting(state, event, timing) {
+    switch (event.type) {
+        // The change that put us here becomes a follow-up change cycle, so it
+        // cannot swallow the startup cycle (D5, F14).
+        case 'started':
+            return runCycle(true);
+        case 'changed':
+            return {
+                state: {
+                    kind: 'waiting',
+                    firstChangeAt: state.firstChangeAt,
+                    lastChangeAt: event.at,
+                },
+                effects: [
+                    {
+                        type: 'armQuietTimer',
+                        // maxDelayMs bounds how long a continuous writer can postpone the
+                        // commit and, through the deferred poll, every incoming change.
+                        fireAt: Math.min(event.at + timing.quietMs, state.firstChangeAt + timing.maxDelayMs),
+                    },
+                ],
+            };
+        case 'pollDue':
+            return {
+                state,
+                effects: [{ type: 'armPollTimer', fireAt: event.at + timing.pollMs }],
+            };
+        case 'quietElapsed':
+            return runCycle(false);
+        case 'stopRequested':
+            return endNow('stopped');
+        case 'cycleFinished':
+            return unchanged(state);
+    }
+}
+function fromSyncing(state, event, timing) {
+    switch (event.type) {
+        case 'changed':
+            return {
+                state: { kind: 'syncing', changedDuringSync: true },
+                effects: [],
+            };
+        case 'cycleFinished':
+            return afterCycle(state, event.at, event.outcome, timing);
+        case 'stopRequested':
+            return {
+                state: { kind: 'stopping' },
+                effects: [{ type: 'cancelTimers' }],
+            };
+        case 'started':
+        case 'quietElapsed':
+        case 'pollDue':
+            return unchanged(state);
+    }
+}
+function afterCycle(state, at, outcome, timing) {
+    if (outcome === 'halted') {
+        return endNow('halted');
+    }
+    // A change seen during the cycle, or a commit deferred because git was
+    // busy, re-arms the quiet window instead of being dropped (D7).
+    if (state.changedDuringSync || outcome === 'busy') {
+        return {
+            state: { kind: 'waiting', firstChangeAt: at, lastChangeAt: at },
+            effects: [
+                { type: 'armQuietTimer', fireAt: at + timing.quietMs },
+                { type: 'armPollTimer', fireAt: at + timing.pollMs },
+            ],
+        };
+    }
+    return {
+        state: { kind: 'idle' },
+        effects: [{ type: 'armPollTimer', fireAt: at + timing.pollMs }],
+    };
+}
+function fromStopping(state, event) {
+    if (event.type === 'cycleFinished') {
+        // A halt set by the last cycle outranks the stop: the marker refuses the
+        // next start, so the run ends with the halt's exit code (Decision 54).
+        const reason = event.outcome === 'halted' ? 'halted' : 'stopped';
+        return {
+            state: { kind: reason },
+            effects: [{ type: 'end', reason }],
+        };
+    }
+    return unchanged(state);
+}
+function runCycle(changedDuringSync) {
+    return {
+        state: { kind: 'syncing', changedDuringSync },
+        effects: [{ type: 'runCycle' }],
+    };
+}
+function endNow(reason) {
+    return {
+        state: { kind: reason },
+        effects: [{ type: 'cancelTimers' }, { type: 'end', reason }],
+    };
+}
+function unchanged(state) {
+    return { state, effects: [] };
+}

package/dist/core/state/stateGuards.d.ts

@@ -0,0 +1,21 @@
+import type { HaltRecord } from '../../contracts/IHaltStore.js';
+import type { RebaseJournal } from '../../contracts/IOperationJournal.js';
+import type { QuarantineMemento } from '../../contracts/IPathQuarantine.js';
+import type { StateRecord } from '../../contracts/IStateStore.js';
+/** instance.lock content; the token identifies the writing process for release. */
+export interface LockRecord {
+    readonly pid: number;
+    readonly hostname: string;
+    readonly startedAt: string;
+    readonly token: string;
+}
+/** Each parser returns null for text that is not JSON or not the expected shape. */
+export declare function parseHaltRecord(text: string): HaltRecord | null;
+export declare function parseLockRecord(text: string): LockRecord | null;
+export declare function parseRebaseJournal(text: string): RebaseJournal | null;
+export declare function parseQuarantineMemento(text: string): QuarantineMemento | null;
+/**
+ * state.json (design 12.1): null unless every field has its type, version is
+ * 1, state and reason are known values and history holds valid transitions.
+ */
+export declare function parseStateRecord(text: string): StateRecord | null;

package/dist/core/state/stateGuards.js

@@ -0,0 +1,295 @@
+const HALT_CODES = [
+    'REBASE_ABORT_UNVERIFIED',
+    'UPSTREAM_REWRITTEN',
+    'QUARANTINE_RESTORE_FAILED',
+    'HALT_MARKER_UNREADABLE',
+];
+/** Each parser returns null for text that is not JSON or not the expected shape. */
+export function parseHaltRecord(text) {
+    const value = parseJsonObject(text);
+    if (value === null) {
+        return null;
+    }
+    const code = HALT_CODES.find((candidate) => candidate === value.code);
+    const { message, cycleId, at } = value;
+    if (code === undefined ||
+        typeof message !== 'string' ||
+        !(cycleId === null || typeof cycleId === 'string') ||
+        typeof at !== 'string') {
+        return null;
+    }
+    return { code, message, cycleId, at };
+}
+export function parseLockRecord(text) {
+    const value = parseJsonObject(text);
+    if (value === null) {
+        return null;
+    }
+    const { pid, hostname, startedAt, token } = value;
+    if (typeof pid !== 'number' ||
+        !Number.isInteger(pid) ||
+        pid <= 0 ||
+        typeof hostname !== 'string' ||
+        typeof startedAt !== 'string' ||
+        !isNonEmptyString(token)) {
+        return null;
+    }
+    return { pid, hostname, startedAt, token };
+}
+export function parseRebaseJournal(text) {
+    const value = parseJsonObject(text);
+    if (value === null) {
+        return null;
+    }
+    const { origHead, onto, cycleId, at } = value;
+    if (!isNonEmptyString(origHead) ||
+        !isNonEmptyString(onto) ||
+        typeof cycleId !== 'string' ||
+        typeof at !== 'string') {
+        return null;
+    }
+    return { origHead, onto, cycleId, at };
+}
+export function parseQuarantineMemento(text) {
+    const value = parseJsonObject(text);
+    if (value === null || value.version !== 1 || !Array.isArray(value.entries)) {
+        return null;
+    }
+    const items = value.entries;
+    const entries = [];
+    for (const item of items) {
+        const entry = toQuarantineEntry(item);
+        if (entry === null) {
+            return null;
+        }
+        entries.push(entry);
+    }
+    return { version: 1, entries };
+}
+/**
+ * state.json (design 12.1): null unless every field has its type, version is
+ * 1, state and reason are known values and history holds valid transitions.
+ */
+export function parseStateRecord(text) {
+    const value = parseJsonObject(text);
+    if (value === null || value.version !== 1) {
+        return null;
+    }
+    const instance = toStateInstance(value.instance);
+    const state = DAEMON_STATES.find((candidate) => candidate === value.state);
+    const reason = toStateReason(value.reason);
+    const lastCycle = toLastCycle(value.lastCycle);
+    const conflict = toConflictKey(value.conflict);
+    const history = toHistory(value.history);
+    const orphaned = toOrphaned(value.orphaned);
+    const { message, since, pushed, unpushed } = value;
+    if (instance === null ||
+        state === undefined ||
+        reason === undefined ||
+        typeof message !== 'string' ||
+        typeof since !== 'string' ||
+        !(pushed === null || isNonEmptyString(pushed)) ||
+        !(unpushed === null || isCount(unpushed)) ||
+        lastCycle === undefined ||
+        conflict === undefined ||
+        history === null ||
+        orphaned === null) {
+        return null;
+    }
+    return {
+        version: 1,
+        instance,
+        state,
+        reason,
+        message,
+        since,
+        pushed,
+        unpushed,
+        lastCycle,
+        conflict,
+        history,
+        orphaned,
+    };
+}
+/**
+ * null: malformed. Absent is [] (a file written before design 14.15 must
+ * keep its record, like heldOver in a memento).
+ */
+function toOrphaned(item) {
+    if (item === undefined) {
+        return [];
+    }
+    if (!Array.isArray(item)) {
+        return null;
+    }
+    const items = item;
+    const orphaned = [];
+    for (const entry of items) {
+        if (!isRecord(entry)) {
+            return null;
+        }
+        const { commit, base, subject, at } = entry;
+        if (!isObjectId(commit) ||
+            !isObjectId(base) ||
+            typeof subject !== 'string' ||
+            typeof at !== 'string') {
+            return null;
+        }
+        orphaned.push({ commit, base, subject, at });
+    }
+    return orphaned;
+}
+/**
+ * A full object id (SHA-1 or SHA-256): status hands it to git in a revision
+ * argument, so a hand-edited file cannot slip an option into the argv.
+ */
+function isObjectId(value) {
+    return (typeof value === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(value));
+}
+const DAEMON_STATES = [
+    'starting',
+    'synced',
+    'waiting',
+    'conflict',
+    'paused',
+    'busy',
+    'offline',
+    'push-failed',
+    'halted',
+    'stopped',
+];
+const STATE_REASONS = [
+    'FOREIGN_OPERATION',
+    'DETACHED_HEAD',
+    'NO_UPSTREAM',
+    'UPSTREAM_NOT_REMOTE',
+    'UPSTREAM_GONE',
+    'BRANCH_CHANGED',
+    'QUARANTINE_UNSUPPORTED',
+    'REBASE_REFUSED',
+    'PARTIAL_SELECTION_STAGED',
+    'COMMIT_HOOK_REJECTED',
+    ...HALT_CODES,
+];
+const OUTCOME_KINDS = [
+    'synced',
+    'paused',
+    'busy',
+    'offline',
+    'conflict',
+    'push-failed',
+    'halted',
+    'waiting',
+    'failed',
+];
+function toStateInstance(item) {
+    if (!isRecord(item)) {
+        return null;
+    }
+    const { pid, hostname, startedAt } = item;
+    // pid 0 is the instance of a record no started event began (stateRecordStep).
+    if (!isCount(pid) ||
+        typeof hostname !== 'string' ||
+        typeof startedAt !== 'string') {
+        return null;
+    }
+    return { pid, hostname, startedAt };
+}
+/** undefined: not a reason; null: no reason. */
+function toStateReason(item) {
+    if (item === null) {
+        return null;
+    }
+    return STATE_REASONS.find((candidate) => candidate === item);
+}
+/** undefined: malformed; null: no cycle yet. */
+function toLastCycle(item) {
+    if (item === null) {
+        return null;
+    }
+    if (!isRecord(item)) {
+        return undefined;
+    }
+    const { cycleId, at } = item;
+    const outcome = OUTCOME_KINDS.find((candidate) => candidate === item.outcome);
+    if (typeof cycleId !== 'string' ||
+        outcome === undefined ||
+        typeof at !== 'string') {
+        return undefined;
+    }
+    return { cycleId, outcome, at };
+}
+/** undefined: malformed; null: no conflict held. */
+function toConflictKey(item) {
+    if (item === null) {
+        return null;
+    }
+    if (!isRecord(item)) {
+        return undefined;
+    }
+    const { head, upstream } = item;
+    if (!isNonEmptyString(head) || !isNonEmptyString(upstream)) {
+        return undefined;
+    }
+    return { head, upstream };
+}
+function toHistory(item) {
+    if (!Array.isArray(item)) {
+        return null;
+    }
+    const items = item;
+    const history = [];
+    for (const entry of items) {
+        const transition = toTransition(entry);
+        if (transition === null) {
+            return null;
+        }
+        history.push(transition);
+    }
+    return history;
+}
+function toTransition(item) {
+    if (!isRecord(item)) {
+        return null;
+    }
+    const state = DAEMON_STATES.find((candidate) => candidate === item.state);
+    const reason = toStateReason(item.reason);
+    const { at } = item;
+    if (state === undefined || reason === undefined || typeof at !== 'string') {
+        return null;
+    }
+    return { state, reason, at };
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function toQuarantineEntry(item) {
+    if (!isRecord(item)) {
+        return null;
+    }
+    const { path, blobId, executable, heldOver } = item;
+    if (!isNonEmptyString(path) ||
+        !(blobId === null || isNonEmptyString(blobId)) ||
+        typeof executable !== 'boolean' ||
+        !(heldOver === undefined || heldOver === null || isNonEmptyString(heldOver))) {
+        return null;
+    }
+    // A memento written before heldOver existed may still be pending after an upgrade.
+    return { path, blobId, executable, heldOver: heldOver ?? null };
+}
+function parseJsonObject(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    return isRecord(parsed) ? parsed : null;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}

package/dist/core/state/stateLiveness.d.ts

@@ -0,0 +1,10 @@
+import type { LockHolder } from '../../contracts/IInstanceLock.js';
+import type { StateRecord } from '../../contracts/IStateStore.js';
+import type { StateLiveness } from '../../contracts/library.js';
+/**
+ * One rule for status and the library (design 12.1, Decision 64): the record
+ * is the live instance's when the lock's live holder has its pid and
+ * startedAt. The lock already judges liveness (a dead pid is no holder), so
+ * no heartbeat threshold is needed.
+ */
+export declare function stateLiveness(record: StateRecord | null, liveHolder: LockHolder | null): StateLiveness;

package/dist/core/state/stateLiveness.js

@@ -0,0 +1,21 @@
+/**
+ * One rule for status and the library (design 12.1, Decision 64): the record
+ * is the live instance's when the lock's live holder has its pid and
+ * startedAt. The lock already judges liveness (a dead pid is no holder), so
+ * no heartbeat threshold is needed.
+ */
+export function stateLiveness(record, liveHolder) {
+    if (liveHolder === null) {
+        if (record === null) {
+            return 'never';
+        }
+        return record.state === 'stopped' ? 'stopped' : 'crashed';
+    }
+    if (record === null ||
+        record.instance.pid !== liveHolder.pid ||
+        record.instance.startedAt !== liveHolder.startedAt) {
+        return 'unrecorded';
+    }
+    // The milliseconds between writing stopped and releasing the lock.
+    return record.state === 'stopped' ? 'stopped' : 'running';
+}

package/dist/core/state/stateRecordStep.d.ts

@@ -0,0 +1,28 @@
+import type { StateEvent } from '../../contracts/IStateRecorder.js';
+import type { StateRecord } from '../../contracts/IStateStore.js';
+/** The hard maximum of stateHistory: a typo or a library caller cannot make state.json large. */
+export declare const MAX_STATE_HISTORY = 100;
+/**
+ * A longer message (a halt's) is cut to this many characters and ends in
+ * "...". Characters are code points (Array.from), so an astral character is
+ * never split into a lone surrogate.
+ */
+export declare const MAX_STATE_MESSAGE_CHARACTERS = 300;
+/**
+ * How many orphaned commits the record keeps, newest last (design 14.15). An
+ * orphan needs a person's commit inside enmetu's stopped rebase, so five
+ * pending at once is already far beyond what the window produces; the cap
+ * keeps state.json bounded (Decision 63) whatever happens.
+ */
+export declare const MAX_ORPHANED_COMMITS = 5;
+/** An orphaned commit's subject is cut to this many characters, like a message (git's conventional subject width). */
+export declare const MAX_ORPHAN_SUBJECT_CHARACTERS = 72;
+/**
+ * Functional core of the state record (design 12.1): the record after an
+ * event. A transition is a change of (state, reason); it moves `since` and is
+ * appended to the history, which keeps the newest min(historyCap,
+ * MAX_STATE_HISTORY) entries. `started` begins a fresh record for the new
+ * instance and carries the previous history across the restart; any other
+ * event without a previous record applies to EMPTY_RECORD.
+ */
+export declare function stateRecordStep(previous: StateRecord | null, event: StateEvent, at: string, historyCap: number): StateRecord;