amalgm 0.1.158 → 0.1.159

package/runtime/scripts/amalgm-mcp/workspace/wall.js

@@ -0,0 +1,308 @@
+'use strict';
+
+/**
+ * The machine wall: every machine's repo cards, shared across the
+ * account's devices on the wave-3 rail.
+ *
+ * The wall is one shared live document per account — a jsonl file where
+ * each machine owns exactly one line, its full card set. Single-writer
+ * per line means concurrent publishes from different machines are
+ * disjoint edits the doc rail merges perfectly; the doc itself rides the
+ * exact journal → outbox → gateway-stamp → fanout → catch-up spine every
+ * shared document rides. No new transport, no new failure modes.
+ *
+ * The wall's resource id is derived from the account, so every machine
+ * finds it without a rendezvous service: attach first; if the cloud has
+ * never heard of it, promote it into existence; if two machines race,
+ * exactly one create wins and the loser attaches. Access is enforced by
+ * the gateway's membership check — another account attaching this id gets
+ * a flat 403, which is the cross-account gate this slice must prove.
+ *
+ * Publishing is gated on the replica binding: until the wall is attached,
+ * the local file stays empty (which is exactly what attachment requires)
+ * and nothing is written. Cards therefore never ride an unbound file.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { AMALGM_DIR } = require('../config');
+const { subscribeStateEvents } = require('../state/events');
+const { machineId, userId } = require('./identity');
+const { listRepoCards } = require('./cards');
+
+const WALL_CONTRACT = 'machine-cards@1';
+const WALL_FILE = path.join(AMALGM_DIR, 'state', 'machine-cards.jsonl');
+const PUBLISH_QUIET_MS = 300;
+const ENSURE_STEP_TIMEOUT_MS = 20_000;
+const ENSURE_RETRY_MS = 15_000;
+const ATTACH_REJECTED = /shared_resource_read_forbidden/;
+
+const service = {
+  started: false,
+  stopRequested: false,
+  publishTimer: null,
+  ensureTimer: null,
+  unsubscribe: null,
+  ensure: { state: 'idle', attempts: 0, lastError: null },
+  counters: { publishes: 0, publishSkips: 0, publishFailures: 0 },
+  lastPublishedAt: null,
+};
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/** The account's wall resource id — same on every machine of the account. */
+function wallResourceId(forUserId = userId()) {
+  if (!forUserId) return null;
+  const digest = crypto.createHash('sha256')
+    .update(`amalgm-machine-wall@1|${forUserId}`)
+    .digest('base64url');
+  return `shr_mw1${digest.slice(0, 40)}`;
+}
+
+function wallReplica() {
+  const resourceId = wallResourceId();
+  if (!resourceId) return null;
+  return require('../state/replicas').getReplicaByResourceId(resourceId);
+}
+
+function parseWallLine(line) {
+  try {
+    const entry = JSON.parse(line);
+    if (entry?.wall !== WALL_CONTRACT || !entry.machine || !Array.isArray(entry.cards)) return null;
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every machine's published line, keyed by machine — the wall as this
+ * machine currently sees it. Lines that do not parse as wall entries are
+ * ignored; the next publish from their machine replaces them.
+ */
+function readWall() {
+  if (!fs.existsSync(WALL_FILE)) return [];
+  const entries = new Map();
+  for (const line of require('../state/docs').getDocText(WALL_FILE).split('\n')) {
+    if (!line) continue;
+    const entry = parseWallLine(line);
+    if (entry) entries.set(entry.machine, entry);
+  }
+  return [...entries.values()];
+}
+
+/**
+ * Write this machine's line — and only this machine's line — into the
+ * wall. Other machines' lines are preserved byte-for-byte in place, so
+ * the resulting doc edit is exactly one line's splice and concurrent
+ * publishes from other machines never overlap it.
+ */
+function publishWall() {
+  const replica = wallReplica();
+  if (!replica) {
+    service.counters.publishSkips += 1;
+    return { published: false, reason: 'wall-not-bound' };
+  }
+
+  const docs = require('../state/docs');
+  const current = docs.getDocText(WALL_FILE);
+  const mine = JSON.stringify({
+    wall: WALL_CONTRACT,
+    machine: machineId(),
+    publishedAt: new Date().toISOString(),
+    cards: listRepoCards(),
+  });
+
+  const lines = current.split('\n').filter((line) => line.length > 0);
+  const index = lines.findIndex((line) => parseWallLine(line)?.machine === machineId());
+  const unchanged = index >= 0
+    && withoutPublishedAt(lines[index]) === withoutPublishedAt(mine);
+  if (unchanged) {
+    service.counters.publishSkips += 1;
+    return { published: false, reason: 'unchanged' };
+  }
+  if (index >= 0) lines[index] = mine;
+  else lines.push(mine);
+
+  const result = docs.writeDocText(WALL_FILE, `${lines.join('\n')}\n`, { baseHash: sha256(current) });
+  service.counters.publishes += 1;
+  service.lastPublishedAt = new Date().toISOString();
+  return { published: true, merge: result.merge, cards: listRepoCards().length };
+}
+
+function withoutPublishedAt(line) {
+  const entry = parseWallLine(line);
+  if (!entry) return line;
+  const { publishedAt, ...rest } = entry;
+  return JSON.stringify(rest);
+}
+
+// --- binding the wall to the rail -----------------------------------------
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+    service.ensureTimer = timer;
+  });
+}
+
+async function waitForSettled(read) {
+  const deadline = Date.now() + ENSURE_STEP_TIMEOUT_MS;
+  while (Date.now() < deadline && !service.stopRequested) {
+    if (wallReplica()) return read();
+    const row = read();
+    if (row && row.state !== 'pending' && row.state !== 'syncing') return row;
+    await sleep(500);
+  }
+  return read();
+}
+
+/**
+ * Bind this machine to the account wall, retrying for as long as the
+ * service runs. The attachment row is the one durable request per
+ * resource: create it if absent, cycle it back to pending after a
+ * refusal, and — when the refusal means the cloud has never heard of the
+ * wall — promote the empty file into existence exactly once. Two
+ * machines racing the creation resolve cleanly: one create wins, the
+ * loser's next attach retry finds the wall existing. The tunnel delivers
+ * queued requests whenever it connects, so an offline boot binds on
+ * reconnect.
+ */
+async function ensureWallBound() {
+  const resourceId = wallResourceId();
+  if (!resourceId) {
+    service.ensure.state = 'no-account';
+    return;
+  }
+  const shared = require('../state/shared-rest');
+  const attachments = require('../state/attachments');
+  const promotions = require('../state/promotions');
+
+  while (!service.stopRequested && !wallReplica()) {
+    service.ensure.attempts += 1;
+    try {
+      fs.mkdirSync(path.dirname(WALL_FILE), { recursive: true });
+      if (!fs.existsSync(WALL_FILE)) fs.writeFileSync(WALL_FILE, '');
+
+      let request = attachments.getAttachmentByResource(resourceId);
+      if (!request) {
+        service.ensure.state = 'attaching';
+        await callLocal(shared.handleAttachmentStart, { resourceId, path: WALL_FILE });
+      } else if (request.state === 'rejected') {
+        if (ATTACH_REJECTED.test(request.lastError || '') && !promotions.getPromotionByResource(resourceId)) {
+          // The cloud has never heard of this wall — or access is gone,
+          // and a create attempt on an existing id is refused, so trying
+          // is safe either way. Promote the empty file into existence.
+          service.ensure.state = 'creating';
+          await callLocal(shared.handlePromotionStart, { resourceId, path: WALL_FILE });
+          await waitForSettled(() => promotions.getPromotionByResource(resourceId));
+          if (wallReplica()) break;
+        }
+        service.ensure.state = 'attaching';
+        attachments.retryAttachment(resourceId);
+      }
+      const settled = await waitForSettled(() => attachments.getAttachmentByResource(resourceId));
+      service.ensure.lastError = settled?.lastError || null;
+    } catch (error) {
+      service.ensure.lastError = error.message;
+    }
+    if (wallReplica()) break;
+    service.ensure.state = 'waiting';
+    await sleep(ENSURE_RETRY_MS);
+  }
+
+  if (wallReplica()) {
+    service.ensure.state = 'bound';
+    service.ensure.lastError = null;
+    schedulePublish();
+  }
+}
+
+/** Adapt a shared-rest handler (which speaks sendJson) into a promise. */
+function callLocal(handler, body) {
+  return new Promise((resolve, reject) => {
+    handler(body, (status, payload) => {
+      if (status >= 400) reject(new Error(payload?.error || `local shared route failed with ${status}`));
+      else resolve(payload);
+    });
+  });
+}
+
+// --- service ---------------------------------------------------------------
+
+function schedulePublish() {
+  if (!service.started || service.publishTimer) return;
+  service.publishTimer = setTimeout(() => {
+    service.publishTimer = null;
+    try {
+      publishWall();
+    } catch (error) {
+      service.counters.publishFailures += 1;
+      console.warn('[MachineWall] publish failed:', error.message);
+    }
+  }, PUBLISH_QUIET_MS);
+  service.publishTimer.unref?.();
+}
+
+function startWallService() {
+  if (service.started) return;
+  service.started = true;
+  service.stopRequested = false;
+  service.unsubscribe = subscribeStateEvents((event) => {
+    if (event.resource === 'repo-cards') schedulePublish();
+  });
+  ensureWallBound().catch((error) => {
+    service.ensure.state = 'failed';
+    service.ensure.lastError = error.message;
+    console.warn('[MachineWall] binding failed:', error.message);
+  });
+}
+
+function stopWallService() {
+  if (!service.started) return;
+  service.started = false;
+  service.stopRequested = true;
+  service.unsubscribe?.();
+  service.unsubscribe = null;
+  if (service.publishTimer) clearTimeout(service.publishTimer);
+  service.publishTimer = null;
+  if (service.ensureTimer) clearTimeout(service.ensureTimer);
+  service.ensureTimer = null;
+}
+
+function wallStats() {
+  const replica = wallReplica();
+  return {
+    contract: WALL_CONTRACT,
+    resourceId: wallResourceId(),
+    path: WALL_FILE,
+    replica: replica && {
+      appliedVersion: replica.appliedVersion,
+      snapshotVersion: replica.snapshotVersion,
+      authorityEpoch: replica.authorityEpoch,
+      syncStatus: replica.syncStatus,
+      lastError: replica.lastError,
+      updatedAt: replica.updatedAt,
+    },
+    ensure: { ...service.ensure },
+    publishes: service.counters.publishes,
+    publishSkips: service.counters.publishSkips,
+    publishFailures: service.counters.publishFailures,
+    lastPublishedAt: service.lastPublishedAt,
+    machines: readWall().length,
+  };
+}
+
+module.exports = {
+  WALL_CONTRACT,
+  publishWall,
+  readWall,
+  startWallService,
+  stopWallService,
+  wallResourceId,
+  wallStats,
+};