@serfab/cadre-core 0.6.0 → 0.8.1

package/src/canonical-datetime.ts

@@ -0,0 +1,39 @@
+import type { Database } from '@quereus/quereus';
+
+/**
+ * Canonicalise an epoch-ms timestamp to the exact `datetime` string Quereus stores,
+ * by round-tripping through the engine's own `datetime(?)` scalar — the same parse
+ * the `datetime` column coercion uses.
+ *
+ * **Stored form:** a `datetime` column always stores and reads back values as
+ * `YYYY-MM-DDTHH:MM:SS[.frac]` (T-separated, no trailing Z). Any valid input —
+ * space-form (`YYYY-MM-DD HH:MM:SS`), T-form, or ISO-Z (`...T...000Z`) — is
+ * coerced to this form on read; ordering over a `datetime` column is therefore
+ * chronologically correct regardless of which input form was inserted.
+ *
+ * **Raw bound-parameter comparisons:** Quereus only coerces operands that carry
+ * `datetime` semantics (typed columns or explicit `cast(... as datetime)`). A raw,
+ * un-coerced bound parameter is compared lexically. To avoid mis-ordering, anything
+ * compared against a `datetime` column value via a raw `> ?` should be produced by
+ * this helper (or `datetime()` / an explicit cast), so both sides are T-form.
+ *
+ * This avoids a hand-rolled ISO formatter whose fractional-second handling could
+ * diverge from Temporal. Any signed payload segment that must byte-match a
+ * `datetime`-typed column value AFTER coercion (e.g. the control-layer
+ * `FormationInvite.ExpiresAt` or the strand-layer `Invite.Expiration`) must be
+ * produced this way, so the signer and the deferred CHECK verifier agree exactly.
+ *
+ * Pure scalar eval (no network) — safe to call on any composed Quereus database.
+ *
+ * @param db - The Quereus database to evaluate against.
+ * @param epochMs - The timestamp in epoch milliseconds.
+ * @returns The engine-canonical `datetime` string for that instant (T-separated ISO,
+ *   no trailing Z).
+ * @throws If the `datetime()` eval returns no row.
+ */
+export async function canonicalDatetime(db: Database, epochMs: number): Promise<string> {
+  for await (const row of db.eval('select datetime(?) as Canonical', [epochMs])) {
+    return row.Canonical as string;
+  }
+  throw new Error('datetime() canonicalisation returned no row');
+}

package/src/canonical-json.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical JSON serialization for signed payloads.
+ *
+ * Recursively sorts object keys, drops `undefined` values, emits no whitespace
+ * and no trailing newline. Arrays preserve their order. This is a tiny RFC 8785
+ * subset, sufficient for the fixed-shape payloads we sign (update manifests in
+ * cadre-host, control-network seeds here).
+ *
+ * Lives in cadre-core because cadre-host depends on cadre-core (not the
+ * reverse); cadre-host re-imports this rather than keeping its own copy.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error('cannot serialize non-finite number');
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string' || typeof value === 'boolean') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => canonicalJson(v)).join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') + '}';
+  }
+  throw new Error(`cannot serialize value of type ${typeof value}`);
+}

package/src/control-cohort.ts

@@ -0,0 +1,103 @@
+/**
+ * Control-cohort dial selection: the pure policy behind
+ * {@link CadreNode.reconcileControlCohort}. Decides WHICH known cadre siblings a
+ * node proactively dials each pass to keep the `CadreControl` collections' cohort
+ * connected (and thus replicating), without devolving into an N² mesh.
+ *
+ * FRET only needs a *connected* graph with the block clusters reachable, not a
+ * full mesh. Storage/authority nodes are the stable, publicly-dialable backbone
+ * that hold the control blocks, so the policy is **backbone-preferential with a
+ * bounded out-degree**:
+ *
+ * - **Always dial every backbone (authority) member** — the authority set is
+ *   small by design, and routing cohort formation through publicly-dialable
+ *   authority nodes keeps the cohort ≥2 where authority-signed writes originate.
+ * - **Fill the remainder** up to `targetDegree` with non-authority members,
+ *   ordered deterministically (peerId sort) so every node makes the same stable
+ *   choice across passes and load spreads predictably.
+ *
+ * For a small party (members ≤ degree) this degenerates to a full mesh, which is
+ * correct, cheap, and matches what the convergence tests do by hand; for a large
+ * party it bounds out-degree to `backbone + targetDegree`.
+ */
+
+import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+import type { CohortPeerRow } from './strand-cohort.js';
+
+/**
+ * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
+ * In the same spirit as the 5s strand-watch poll but lighter, since a control
+ * cohort changes far less often than strand activity.
+ */
+export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
+
+/**
+ * Default cap on the number of **non-authority** members a single reconcile pass
+ * proactively dials. Backbone (authority) members are always dialed and do NOT
+ * count against this cap.
+ */
+export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
+
+/** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
+export interface ControlCohortSelection {
+  /**
+   * Siblings to dial this pass, backbone first then the bounded non-authority
+   * fill. Already self-excluded (the caller must pass self-excluded `siblings`).
+   * Still includes peers that may turn out to be already-connected — the caller
+   * diffs against live connections separately.
+   */
+  dials: CohortPeerRow[];
+  /** Non-authority members dropped by the `targetDegree` cap (0 when none). */
+  cappedNonAuthority: number;
+}
+
+/** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
+function byPeerId(a: CohortPeerRow, b: CohortPeerRow): number {
+  if (a.peerId < b.peerId) return -1;
+  if (a.peerId > b.peerId) return 1;
+  return 0;
+}
+
+/**
+ * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
+ * to dial.
+ *
+ * A member is **backbone** iff the ed25519 key derived from its peerId
+ * (see {@link ed25519PublicKeyB64FromPeerId}) is in `authorityKeys`. All backbone
+ * members are selected; non-authority members fill up to `targetDegree` in
+ * deterministic peerId order.
+ *
+ * @param siblings - cadre members EXCLUDING self (the caller filters self out).
+ * @param authorityKeys - the converged `AuthorityKey` set; may be empty/partial
+ *   before authority convergence, in which case no member classifies as backbone
+ *   yet and the bounded fill still makes progress (preference sharpens later).
+ * @param targetDegree - cap on non-authority dials (negative is treated as 0).
+ */
+export function selectControlCohortDials(
+  siblings: CohortPeerRow[],
+  authorityKeys: ReadonlySet<string>,
+  targetDegree: number,
+): ControlCohortSelection {
+  const backbone: CohortPeerRow[] = [];
+  const rest: CohortPeerRow[] = [];
+
+  for (const peer of siblings) {
+    const pubKey = ed25519PublicKeyB64FromPeerId(peer.peerId);
+    if (pubKey !== null && authorityKeys.has(pubKey)) {
+      backbone.push(peer);
+    } else {
+      rest.push(peer);
+    }
+  }
+
+  backbone.sort(byPeerId);
+  rest.sort(byPeerId);
+
+  const cap = Math.max(0, targetDegree);
+  const fill = rest.slice(0, cap);
+
+  return {
+    dials: [...backbone, ...fill],
+    cappedNonAuthority: rest.length - fill.length,
+  };
+}