@medicine-wheel/infra 0.5.7 → 0.5.8

package/dist/reconcile.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Reconciliation — level-triggered, so `satisfied` cannot age into a lie.
+ *
+ * The outage this answers (jgwill/gaia#74) was not caused by a missing fact. It
+ * was caused by a fact that had been true. Something was recorded as running,
+ * the recording was never re-read, and every downstream decision was made
+ * against a snapshot.
+ *
+ * **Level-triggered** is the whole design: `reconcile()` compares the current
+ * declared set against the current observed set, every time, and remembers no
+ * transitions. There is no "it was converged a minute ago" state to go stale,
+ * because there is no state at all — only the two levels and the comparison.
+ *
+ * Four drift states, and the two asymmetric ones carry the most information:
+ *
+ * - `converged`  — declared and observed agree on every compared field.
+ * - `drifted`    — both sides exist and disagree. The differences are named.
+ * - `unrealized` — declared, not observed. Written down and not running.
+ * - `undeclared` — observed, not declared. **Running and nobody wrote it down**
+ *                  — the state that finds the service somebody started by hand
+ *                  at 2am, which is exactly the service holding the port the
+ *                  next tenant is about to be given.
+ *
+ * A pure function over plain data. No I/O, no clock: `now` is passed in, so two
+ * runs over the same input are identical.
+ *
+ * Spec: /opt/eury/rispecs/foundations/02-specifications.md §S6.
+ */
+import type { MetisHold, NodeId, PortConflict, ServiceFacet, TenantFacet } from './types';
+export type DriftState = 'converged' | 'drifted' | 'unrealized' | 'undeclared';
+/** Every drift state, in the order a report should read them: agreement, then disagreement, then the two absences. */
+export declare const DRIFT_STATES: readonly DriftState[];
+/**
+ * A reading of a host, taken at a moment, by someone.
+ *
+ * `observedBy` and `observedAt` are required rather than optional. An
+ * observation with no reader and no time is a rumour, and reconciling against a
+ * rumour is how the snapshot problem comes back wearing a different hat.
+ */
+export interface ObservedState {
+    /** → `HostFacet.nodeId` — the host this reading was taken on */
+    observedBy: NodeId;
+    /** ISO 8601 */
+    observedAt: string;
+    services: ServiceFacet[];
+    tenants?: TenantFacet[];
+}
+export interface FieldDifference {
+    field: string;
+    declared?: unknown;
+    observed?: unknown;
+}
+export interface DriftRow {
+    /** → `ServiceFacet.nodeId` */
+    nodeId: NodeId;
+    /** the unit name from whichever side has it, so a row is readable without a join */
+    unit: string;
+    state: DriftState;
+    /** present only when `state` is `drifted` */
+    differences?: FieldDifference[];
+    /**
+     * Métis from **both** sides, carried through untouched.
+     *
+     * An array, not a single hold, and not a merge. Two sides holding different
+     * tacit notes is not drift — it is two people knowing different things. Keeping
+     * only the declared side would delete the observing agent's note; merging the
+     * two into one `MetisHold` would concatenate two people into one `heldBy`
+     * string and lose attribution. Both are the same erasure in different shapes,
+     * and this field exists to refuse it.
+     *
+     * Ordered declared-first, so a reader sees the recorded knowledge before the
+     * observed knowledge.
+     */
+    metis?: MetisHold[];
+}
+export interface ReconcileResult {
+    observedBy: NodeId;
+    observedAt: string;
+    /**
+     * Milliseconds between `observedAt` and `now`, when `now` was given.
+     *
+     * Exposed so a caller can refuse to act on an old reading. Negative when the
+     * observation is stamped in the future — surfaced rather than clamped, because
+     * a future timestamp means clock skew and that is worth seeing.
+     */
+    observationAgeMs?: number;
+    rows: DriftRow[];
+    /** counts per drift state; every state present, including the zeroes */
+    summary: Record<DriftState, number>;
+    /**
+     * Port conflicts over declared ∪ observed — the §S3 traversal folded in here
+     * because this is the one place both sides are in hand at once.
+     */
+    conflicts: PortConflict[];
+    /** true when nothing drifted, nothing is unrealized, nothing is undeclared, and no port collides */
+    converged: boolean;
+}
+/**
+ * Compare what was declared against what was observed, right now.
+ *
+ * Rows are keyed by `nodeId` and sorted by it, so two runs over the same input
+ * are byte-identical and a caller can diff them.
+ *
+ * @param declared  desired state, authored by eury
+ * @param observed  a reading taken on a host by gaia, with its provenance
+ * @param opts.now  ISO 8601 — supplied by the caller so this stays clock-free
+ */
+export declare function reconcile(declared: ServiceFacet[], observed: ObservedState, opts?: {
+    now?: string;
+}): ReconcileResult;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAe,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvG,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CAAC;AAE/E,sHAAsH;AACtH,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAyD,CAAC;AAExG;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,oGAAoG;IACpG,SAAS,EAAE,OAAO,CAAC;CACpB;AA2CD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,YAAY,EAAE,EACxB,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1B,eAAe,CA+DjB"}

package/dist/reconcile.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Reconciliation — level-triggered, so `satisfied` cannot age into a lie.
+ *
+ * The outage this answers (jgwill/gaia#74) was not caused by a missing fact. It
+ * was caused by a fact that had been true. Something was recorded as running,
+ * the recording was never re-read, and every downstream decision was made
+ * against a snapshot.
+ *
+ * **Level-triggered** is the whole design: `reconcile()` compares the current
+ * declared set against the current observed set, every time, and remembers no
+ * transitions. There is no "it was converged a minute ago" state to go stale,
+ * because there is no state at all — only the two levels and the comparison.
+ *
+ * Four drift states, and the two asymmetric ones carry the most information:
+ *
+ * - `converged`  — declared and observed agree on every compared field.
+ * - `drifted`    — both sides exist and disagree. The differences are named.
+ * - `unrealized` — declared, not observed. Written down and not running.
+ * - `undeclared` — observed, not declared. **Running and nobody wrote it down**
+ *                  — the state that finds the service somebody started by hand
+ *                  at 2am, which is exactly the service holding the port the
+ *                  next tenant is about to be given.
+ *
+ * A pure function over plain data. No I/O, no clock: `now` is passed in, so two
+ * runs over the same input are identical.
+ *
+ * Spec: /opt/eury/rispecs/foundations/02-specifications.md §S6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRIFT_STATES = void 0;
+exports.reconcile = reconcile;
+const ports_1 = require("./ports");
+/** Every drift state, in the order a report should read them: agreement, then disagreement, then the two absences. */
+exports.DRIFT_STATES = ['converged', 'drifted', 'unrealized', 'undeclared'];
+/** Fields compared between a declared and an observed service. `metis` is deliberately absent. */
+const COMPARED_FIELDS = [
+    'unit',
+    'scope',
+    'ownedBy',
+    'workingDirectory',
+    'execStop',
+];
+/** `host|proto|port` — the identity of a claim, matching the slot key `detectPortConflicts` uses. */
+function portKey(binding) {
+    return `${binding.host} ${binding.proto ?? 'tcp'} ${binding.port}`;
+}
+/** Ports compared as sets of claims, so ordering differences between systemd and a manifest are not drift. */
+function portsDiffer(declared, observed) {
+    const a = [...new Set(declared.map(portKey))].sort();
+    const b = [...new Set(observed.map(portKey))].sort();
+    return a.length !== b.length || a.some((k, i) => k !== b[i]);
+}
+function diffService(declared, observed) {
+    const differences = [];
+    for (const field of COMPARED_FIELDS) {
+        if (declared[field] !== observed[field]) {
+            differences.push({ field, declared: declared[field], observed: observed[field] });
+        }
+    }
+    if (portsDiffer(declared.ports, observed.ports)) {
+        differences.push({
+            field: 'ports',
+            declared: [...declared.ports].map(portKey).sort(),
+            observed: [...observed.ports].map(portKey).sort(),
+        });
+    }
+    return differences;
+}
+/**
+ * Compare what was declared against what was observed, right now.
+ *
+ * Rows are keyed by `nodeId` and sorted by it, so two runs over the same input
+ * are byte-identical and a caller can diff them.
+ *
+ * @param declared  desired state, authored by eury
+ * @param observed  a reading taken on a host by gaia, with its provenance
+ * @param opts.now  ISO 8601 — supplied by the caller so this stays clock-free
+ */
+function reconcile(declared, observed, opts = {}) {
+    const declaredById = new Map(declared.map((s) => [s.nodeId, s]));
+    const observedById = new Map(observed.services.map((s) => [s.nodeId, s]));
+    const rows = [];
+    /** Both sides' holds, declared first, with the empty case left undefined. */
+    const heldBy = (...sides) => {
+        const held = sides.filter((m) => m !== undefined);
+        return held.length > 0 ? held : undefined;
+    };
+    for (const [nodeId, d] of declaredById) {
+        const o = observedById.get(nodeId);
+        if (!o) {
+            rows.push({ nodeId, unit: d.unit, state: 'unrealized', metis: heldBy(d.metis) });
+            continue;
+        }
+        const differences = diffService(d, o);
+        const metis = heldBy(d.metis, o.metis);
+        rows.push(differences.length === 0
+            ? { nodeId, unit: d.unit, state: 'converged', metis }
+            : { nodeId, unit: d.unit, state: 'drifted', differences, metis });
+    }
+    for (const [nodeId, o] of observedById) {
+        if (declaredById.has(nodeId))
+            continue;
+        rows.push({ nodeId, unit: o.unit, state: 'undeclared', metis: heldBy(o.metis) });
+    }
+    rows.sort((a, b) => a.nodeId.localeCompare(b.nodeId));
+    const summary = exports.DRIFT_STATES.reduce((acc, state) => ({ ...acc, [state]: rows.filter((r) => r.state === state).length }), {});
+    const conflicts = (0, ports_1.detectPortConflicts)([
+        ...declared.flatMap((s) => s.ports),
+        ...observed.services.flatMap((s) => s.ports),
+    ]);
+    const result = {
+        observedBy: observed.observedBy,
+        observedAt: observed.observedAt,
+        rows,
+        summary,
+        conflicts,
+        converged: summary.drifted === 0 &&
+            summary.unrealized === 0 &&
+            summary.undeclared === 0 &&
+            conflicts.length === 0,
+    };
+    if (opts.now) {
+        const age = Date.parse(opts.now) - Date.parse(observed.observedAt);
+        if (!Number.isNaN(age))
+            result.observationAgeMs = age;
+    }
+    return result;
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

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