@celilo/cli 0.3.30 → 0.4.0-alpha.1

package/src/services/backup-manifest.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  IncompatibleManifestError,
+  MANIFEST_SCHEMA_VERSION,
+  ManifestParseError,
+  assertCompatibleSchema,
+  buildManifest,
+  parseManifest,
+} from './backup-manifest';
+
+describe('backup-manifest', () => {
+  describe('buildManifest', () => {
+    it('produces a system manifest with the current schemaVersion', () => {
+      const m = buildManifest({ kind: 'system' });
+      expect(m.kind).toBe('system');
+      expect(m.schemaVersion).toBe(MANIFEST_SCHEMA_VERSION);
+      expect(m.moduleId).toBeUndefined();
+      expect(m.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+
+    it('produces a module manifest with moduleId/version', () => {
+      const m = buildManifest({
+        kind: 'module',
+        moduleId: 'homebridge',
+        moduleVersion: '1.2.3',
+        dataSchemaVersion: '2.0',
+      });
+      expect(m.kind).toBe('module');
+      expect(m.moduleId).toBe('homebridge');
+      expect(m.moduleVersion).toBe('1.2.3');
+      expect(m.dataSchemaVersion).toBe('2.0');
+    });
+
+    it('honors overrides for testability', () => {
+      const m = buildManifest({
+        kind: 'system',
+        now: new Date('2020-01-01T00:00:00Z'),
+        hostnameOverride: 'test-box',
+        celiloVersion: '9.9.9',
+      });
+      expect(m.createdAt).toBe('2020-01-01T00:00:00.000Z');
+      expect(m.hostname).toBe('test-box');
+      expect(m.celiloVersion).toBe('9.9.9');
+    });
+  });
+
+  describe('parseManifest', () => {
+    it('round-trips a built manifest', () => {
+      const built = buildManifest({ kind: 'system' });
+      const parsed = parseManifest(JSON.stringify(built));
+      expect(parsed).toEqual(built);
+    });
+
+    it('throws ManifestParseError on malformed JSON', () => {
+      expect(() => parseManifest('{not json')).toThrow(ManifestParseError);
+    });
+
+    it('throws ManifestParseError on missing required fields', () => {
+      expect(() => parseManifest(JSON.stringify({ kind: 'system' }))).toThrow(ManifestParseError);
+    });
+
+    it('throws ManifestParseError on bad schemaVersion format', () => {
+      expect(() =>
+        parseManifest(
+          JSON.stringify({
+            schemaVersion: 'not-a-version',
+            createdAt: '2020-01-01T00:00:00Z',
+            celiloVersion: '0.0.0',
+            hostname: 'h',
+            kind: 'system',
+          }),
+        ),
+      ).toThrow(ManifestParseError);
+    });
+
+    it('error message names the cause for operator triage', () => {
+      try {
+        parseManifest('not json');
+      } catch (err) {
+        expect((err as Error).message).toContain('not valid JSON');
+        return;
+      }
+      throw new Error('expected throw');
+    });
+  });
+
+  describe('assertCompatibleSchema', () => {
+    it('accepts the current schemaVersion', () => {
+      const m = buildManifest({ kind: 'system' });
+      expect(() => assertCompatibleSchema(m)).not.toThrow();
+    });
+
+    it('accepts the same major, different minor', () => {
+      const m = buildManifest({ kind: 'system' });
+      // Fudge the version to a higher minor of the same major.
+      m.schemaVersion = `${MANIFEST_SCHEMA_VERSION.split('.')[0]}.99`;
+      expect(() => assertCompatibleSchema(m)).not.toThrow();
+    });
+
+    it('rejects a different major with an actionable error', () => {
+      const m = buildManifest({ kind: 'system' });
+      const otherMajor = String(Number(MANIFEST_SCHEMA_VERSION.split('.')[0]) + 1);
+      m.schemaVersion = `${otherMajor}.0`;
+      try {
+        assertCompatibleSchema(m);
+      } catch (err) {
+        expect(err).toBeInstanceOf(IncompatibleManifestError);
+        expect((err as Error).message).toContain('envelope schema');
+        expect((err as Error).message).toContain('this celilo supports');
+        return;
+      }
+      throw new Error('expected throw');
+    });
+  });
+});

package/src/services/backup-manifest.ts

@@ -0,0 +1,163 @@
+/**
+ * Backup-artifact manifest — a single `manifest.json` file embedded at the
+ * root of every encrypted backup envelope (alongside the actual data). The
+ * manifest makes artifacts self-describing: an operator can hand a backup
+ * file to a different celilo install and the restore code can validate
+ * schemaVersion compatibility + dispatch to the right restore path
+ * without needing the source celilo's DB.
+ *
+ * The DB's `backups` table stays as the queryable index ("show me my
+ * backups") but is no longer authoritative — the artifact itself is.
+ *
+ * Schema versioning:
+ *  - Bump the major when the file layout changes (e.g. renaming `data/`).
+ *  - Bump the minor for additive fields.
+ *  - Restore refuses an artifact whose major doesn't match.
+ */
+
+import { hostname } from 'node:os';
+import { z } from 'zod';
+
+/** Current envelope-schema version. Bump the major on breaking changes. */
+export const MANIFEST_SCHEMA_VERSION = '1.0' as const;
+
+export const BackupManifestSchema = z.object({
+  schemaVersion: z.string().regex(/^\d+\.\d+$/),
+  createdAt: z.string(), // ISO 8601
+  celiloVersion: z.string(),
+  hostname: z.string(),
+  kind: z.enum(['system', 'module']),
+  /** Only present when kind='module'. */
+  moduleId: z.string().optional(),
+  /** Only present when kind='module'. */
+  moduleVersion: z.string().optional(),
+  /**
+   * Schema version of the on_backup hook's own data shape. Reported back
+   * by the module's hook output (`outputs.schema_version`) and threaded
+   * through to on_restore so the hook can migrate its own data. Distinct
+   * from `schemaVersion` (which versions the envelope, not the data).
+   */
+  dataSchemaVersion: z.string().optional(),
+});
+
+export type BackupManifest = z.infer<typeof BackupManifestSchema>;
+
+interface BuildOptions {
+  kind: 'system' | 'module';
+  moduleId?: string;
+  moduleVersion?: string;
+  dataSchemaVersion?: string;
+  /**
+   * Override the timestamp / hostname / celiloVersion for tests. Production
+   * callers leave these at their defaults.
+   */
+  now?: Date;
+  hostnameOverride?: string;
+  celiloVersion?: string;
+}
+
+/**
+ * Construct a manifest object. Pure function — no I/O, no DB reads. The
+ * caller decides where to serialize it (`writeManifest()` below).
+ */
+export function buildManifest(options: BuildOptions): BackupManifest {
+  const manifest: BackupManifest = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    createdAt: (options.now ?? new Date()).toISOString(),
+    celiloVersion: options.celiloVersion ?? getCeliloVersion(),
+    hostname: options.hostnameOverride ?? hostname(),
+    kind: options.kind,
+  };
+  if (options.moduleId) manifest.moduleId = options.moduleId;
+  if (options.moduleVersion) manifest.moduleVersion = options.moduleVersion;
+  if (options.dataSchemaVersion) manifest.dataSchemaVersion = options.dataSchemaVersion;
+  return manifest;
+}
+
+let cachedCeliloVersion: string | null = null;
+function getCeliloVersion(): string {
+  if (cachedCeliloVersion !== null) return cachedCeliloVersion;
+  try {
+    // Read our own package.json. Walking up from __dirname keeps this
+    // robust to the test directory layout (tests run from repo root).
+    const { readFileSync } = require('node:fs');
+    const { dirname, join } = require('node:path');
+    let dir: string = __dirname;
+    for (let i = 0; i < 8; i++) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        if (pkg.name === '@celilo/cli' || pkg.name === 'celilo') {
+          cachedCeliloVersion = String(pkg.version);
+          return cachedCeliloVersion;
+        }
+      } catch {
+        /* package.json doesn't exist in this dir or isn't ours */
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    /* fall through to unknown */
+  }
+  cachedCeliloVersion = 'unknown';
+  return cachedCeliloVersion;
+}
+
+/**
+ * Parse + validate a manifest from a JSON string. Throws ManifestParseError
+ * with an actionable message on failure.
+ */
+export function parseManifest(json: string): BackupManifest {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ManifestParseError(
+      `Backup artifact manifest.json is not valid JSON: ${detail}. The artifact may be corrupted or produced by an incompatible celilo version.`,
+    );
+  }
+  const parsed = BackupManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ManifestParseError(
+      `Backup artifact manifest.json is malformed: ${parsed.error.message}. The artifact may be corrupted or produced by an incompatible celilo version.`,
+    );
+  }
+  return parsed.data;
+}
+
+/**
+ * Verify that a backup artifact's schemaVersion is compatible with this
+ * celilo build. Throws with an operator-readable message on mismatch.
+ *
+ * Today the only check is "major version matches." A v1.x restorer will
+ * load v1.0, v1.1, ... but refuse v2.x.
+ */
+export function assertCompatibleSchema(manifest: BackupManifest): void {
+  const expectedMajor = MANIFEST_SCHEMA_VERSION.split('.')[0];
+  const actualMajor = manifest.schemaVersion.split('.')[0];
+  if (expectedMajor !== actualMajor) {
+    throw new IncompatibleManifestError(
+      `Cannot restore backup: artifact was created with envelope schema ${manifest.schemaVersion}, this celilo supports ${MANIFEST_SCHEMA_VERSION}. Use a celilo build whose major version matches the artifact (or re-create the backup with this celilo).`,
+      manifest,
+    );
+  }
+}
+
+export class ManifestParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ManifestParseError';
+  }
+}
+
+export class IncompatibleManifestError extends Error {
+  constructor(
+    message: string,
+    public readonly manifest: BackupManifest,
+  ) {
+    super(message);
+    this.name = 'IncompatibleManifestError';
+  }
+}

package/src/services/backup-restore.ts

@@ -5,7 +5,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { eq } from 'drizzle-orm';
@@ -19,7 +19,16 @@ import type { ModuleManifest } from '../manifest/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { shellEscape } from '../utils/shell';
+import { assertCompatibleSchema, parseManifest } from './backup-manifest';
 import { createStorageProvider } from './backup-storage';
+import { applyCrossModuleWriteRoot, moduleHasCrossModuleRead } from './cross-module-read';
+import { getModuleSystems } from './deployed-systems';
+import {
+  completeOperation,
+  failOperation,
+  refuseIfInFlight,
+  startOperation,
+} from './module-operations';
 
 export interface RestoreResult {
   success: boolean;
@@ -31,6 +40,17 @@ export interface RestoreResult {
  * Restore a system state backup (replaces the Celilo database)
  */
 export async function restoreSystemStateBackup(backup: Backup): Promise<RestoreResult> {
+  // Refuse if any module operation is in flight (deploy/uninstall/backup/
+  // restore). Caller surfaces the InFlightError to the operator.
+  refuseIfInFlight();
+
+  // Start an operation row so concurrent attempts in another process see
+  // this restore as in-flight. The row's value is short-lived: once we
+  // replace the DB file below, the new DB won't have this row. That's
+  // acceptable — a system restore is a single-process operation by design,
+  // and a parallel CLI invocation would be a foot-gun in any case.
+  startOperation('__system__', 'restore');
+
   const provider = await createStorageProvider(backup.storageId);
   const tempDir = join(tmpdir(), `celilo-restore-${backup.id}`);
 
@@ -41,17 +61,50 @@ export async function restoreSystemStateBackup(backup: Backup): Promise<RestoreR
     const encryptedPath = join(tempDir, 'system.enc');
     await provider.download(backup.storagePath, encryptedPath);
 
-    // Decrypt
+    // Decrypt → tar
     const encryptedData = JSON.parse(readFileSync(encryptedPath, 'utf-8'));
     const masterKey = await getOrCreateMasterKey();
     const base64Data = decryptSecret(encryptedData, masterKey);
-    const dbData = Buffer.from(base64Data, 'base64');
+    const tarData = Buffer.from(base64Data, 'base64');
+
+    // Extract the envelope tar (manifest.json + celilo.db [+celilo.db-wal])
+    const envelopeDir = join(tempDir, 'envelope');
+    mkdirSync(envelopeDir, { recursive: true });
+    const tarPath = join(tempDir, 'envelope.tar');
+    writeFileSync(tarPath, tarData);
+    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
 
-    // Write restored database to temp file first
-    const restoredDbPath = join(tempDir, 'celilo.db');
-    writeFileSync(restoredDbPath, dbData);
+    // Read + validate manifest BEFORE touching the live DB. An
+    // incompatible artifact must not get past this point.
+    const manifestPath = join(envelopeDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      return {
+        success: false,
+        error:
+          'System restore failed: artifact has no manifest.json. It may be from an older celilo (pre-envelope format) or corrupted.',
+      };
+    }
+    const manifest = parseManifest(readFileSync(manifestPath, 'utf-8'));
+    assertCompatibleSchema(manifest);
+    if (manifest.kind !== 'system') {
+      return {
+        success: false,
+        error: `System restore failed: artifact kind is '${manifest.kind}', expected 'system'.`,
+      };
+    }
+
+    const restoredDbPath = join(envelopeDir, 'celilo.db');
+    if (!existsSync(restoredDbPath)) {
+      return {
+        success: false,
+        error: 'System restore failed: artifact has no celilo.db.',
+      };
+    }
 
-    // Close current database connection
+    // Close current database connection. After this point, the operation
+    // row from startOperation() above is unreachable (replaced by the
+    // restored DB's content) and we cannot meaningfully complete/fail it
+    // — but the restore IS the completion.
     closeDb();
 
     // Replace the database file
@@ -145,57 +198,137 @@ export async function restoreModuleBackup(
     };
   }
 
+  // Refuse if any module operation is in flight. Checked after we've
+  // validated the backup + module, so the operator gets the more useful
+  // error first.
+  refuseIfInFlight();
+
+  const opId = startOperation(backup.moduleId, 'restore');
   const provider = await createStorageProvider(backup.storageId);
   const tempDir = join(tmpdir(), `celilo-restore-${backup.id}`);
-  const restoreDir = join(tempDir, 'artifacts');
+  const envelopeDir = join(tempDir, 'envelope');
 
   try {
-    mkdirSync(restoreDir, { recursive: true });
+    mkdirSync(envelopeDir, { recursive: true });
 
     // Download encrypted archive
     const encryptedPath = join(tempDir, 'backup.tar.enc');
     await provider.download(backup.storagePath, encryptedPath);
 
-    // Decrypt
+    // Decrypt → tar
     const encryptedData = JSON.parse(readFileSync(encryptedPath, 'utf-8'));
     const masterKey = await getOrCreateMasterKey();
     const base64Data = decryptSecret(encryptedData, masterKey);
     const tarData = Buffer.from(base64Data, 'base64');
 
-    // Write tar and extract
-    const tarPath = join(tempDir, 'backup.tar');
+    // Write tar and extract into envelopeDir. The envelope contains:
+    //   manifest.json - validated below
+    //   data/         - on_backup hook artifacts (passed to on_restore)
+    const tarPath = join(tempDir, 'envelope.tar');
     writeFileSync(tarPath, tarData);
-    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(restoreDir)}`);
+    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
+
+    // Read + validate envelope manifest BEFORE invoking the hook.
+    const manifestPath = join(envelopeDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      const err =
+        'Module restore failed: artifact has no manifest.json. It may be from an older celilo (pre-envelope format) or corrupted.';
+      failOperation(opId, err);
+      return { success: false, error: err };
+    }
+    const envelopeManifest = parseManifest(readFileSync(manifestPath, 'utf-8'));
+    assertCompatibleSchema(envelopeManifest);
+    if (envelopeManifest.kind !== 'module') {
+      const err = `Module restore failed: artifact kind is '${envelopeManifest.kind}', expected 'module'.`;
+      failOperation(opId, err);
+      return { success: false, error: err };
+    }
+    if (envelopeManifest.moduleId && envelopeManifest.moduleId !== backup.moduleId) {
+      const err = `Module restore failed: artifact was created for module '${envelopeManifest.moduleId}', not '${backup.moduleId}'.`;
+      failOperation(opId, err);
+      return { success: false, error: err };
+    }
+
+    // The on_restore hook reads its data from envelope/data/ — that's
+    // where on_backup wrote it.
+    const restoreDataDir = join(envelopeDir, 'data');
+    if (!existsSync(restoreDataDir)) {
+      const err = 'Module restore failed: artifact has no data/ directory.';
+      failOperation(opId, err);
+      return { success: false, error: err };
+    }
 
     // Build context for hook execution
     const { configMap, secretMap } = await buildModuleContext(mod.id);
     const logger = createConsoleLogger(mod.id, 'on_restore');
 
-    // Execute on_restore hook
+    // Cross-module-write privilege: if the manifest declares
+    // cross_module_read, hand the hook a writable staging dir. After
+    // a successful hook return, applyCrossModuleWriteRoot atomically
+    // moves each module's subtree into live storage. If the hook
+    // crashes/fails, the staging dir is discarded with no side effects.
+    const hookInputs: Record<string, unknown> = {
+      restore_dir: restoreDataDir,
+      schema_version: envelopeManifest.dataSchemaVersion ?? backup.schemaVersion ?? '',
+    };
+    let crossModuleWriteRoot: string | undefined;
+    if (moduleHasCrossModuleRead(manifest)) {
+      crossModuleWriteRoot = join(tempDir, 'cross-module-write');
+      mkdirSync(crossModuleWriteRoot, { recursive: true });
+      hookInputs.cross_module_write_root = crossModuleWriteRoot;
+    }
+
+    // Execute on_restore hook. Pass the data dir + the data-schema-version
+    // from the envelope manifest so the hook can migrate its own data if
+    // needed. Fall back to the backup record's stored value (kept for
+    // backups created before the envelope landed in this celilo build).
     const hookResult = await invokeHook(
       mod.sourcePath,
       'on_restore',
       manifest.celilo_contract,
       hookDef,
-      {
-        restore_dir: restoreDir,
-        schema_version: backup.schemaVersion ?? '',
-      },
+      hookInputs,
       configMap,
       secretMap,
       logger,
       {
         debug: false,
+        systems: getModuleSystems(backup.moduleId, db),
       },
     );
 
     if (!hookResult.success) {
+      const errMsg = hookResult.error ?? 'on_restore hook failed';
+      failOperation(opId, errMsg);
       return {
         success: false,
-        error: hookResult.error ?? 'on_restore hook failed',
+        error: errMsg,
       };
     }
 
+    // Hook succeeded — apply the cross-module staging dir back onto
+    // live storage. Atomic per module (rename live → live.old + rename
+    // staged → live, with rollback on mid-loop failure). If the apply
+    // itself fails, fail the operation but leave the artifact intact —
+    // the operator can investigate and re-run.
+    if (crossModuleWriteRoot) {
+      try {
+        const applyResult = applyCrossModuleWriteRoot(crossModuleWriteRoot);
+        if (applyResult.applied.length > 0) {
+          logger.info(`Cross-module restore applied for: ${applyResult.applied.join(', ')}`);
+        }
+        if (applyResult.skipped.length > 0) {
+          logger.warn(
+            `Cross-module restore skipped (no staged data) for: ${applyResult.skipped.join(', ')}`,
+          );
+        }
+      } catch (applyErr) {
+        const errMsg = `cross_module_write_root apply failed: ${applyErr instanceof Error ? applyErr.message : String(applyErr)}`;
+        failOperation(opId, errMsg);
+        return { success: false, error: errMsg };
+      }
+    }
+
     // Run health check if requested and the module has one
     let healthCheckPassed: boolean | undefined;
     if (options.runHealthCheck && manifest.hooks?.health_check) {
@@ -210,11 +343,13 @@ export async function restoreModuleBackup(
       }
     }
 
+    completeOperation(opId);
     return {
       success: true,
       healthCheckPassed,
     };
   } catch (error) {
+    failOperation(opId, error);
     return {
       success: false,
       error: `Restore failed: ${error instanceof Error ? error.message : String(error)}`,

package/src/services/build-bus/delivery-events.ts

@@ -0,0 +1,92 @@
+/**
+ * Local-bus event emitters for build-bus delivery outcomes.
+ *
+ * Phase 6 of [[v2/BUILD_BUS.md]] wants `celilo subscribers status`
+ * to show last-delivery state + recent failures per subscriber. The
+ * data source for that view is the local SQLite event bus — every
+ * publisher-side fan-out call emits one `webhook.delivered` or
+ * `webhook.failed` event here, and the status command queries them
+ * back.
+ *
+ * Two event types instead of one (`webhook.delivery` with ok bool):
+ *   - `webhook.failed`     filters cleanly for "show me what's broken"
+ *   - `webhook.delivered`  filters cleanly for "show me success rate"
+ * Either query is one indexed lookup against the events.type index
+ * on the bus.
+ */
+
+import { defineEvents, openBus } from '@celilo/event-bus';
+import type { DeliveryResult, PublishEvent } from '@celilo/event-bus/build-bus';
+import { getEventBusPath } from '../../config/paths';
+
+const NO_SCHEMAS = defineEvents({});
+
+export const WEBHOOK_DELIVERED_EVENT = 'webhook.delivered';
+export const WEBHOOK_FAILED_EVENT = 'webhook.failed';
+
+/**
+ * Payload shape for `webhook.delivered` / `webhook.failed` events.
+ * Stored verbatim on the local bus; the status command queries with
+ * `recentEvents({ type, limit })` and aggregates.
+ */
+export interface WebhookDeliveryPayload {
+  /** Subscriber display label (or URL if no name was set). */
+  subscriberLabel: string;
+  /** Subscriber webhook URL. Used as the aggregation key. */
+  subscriberUrl: string;
+  /** UUID of the event we attempted to deliver. */
+  eventId: string;
+  /** Package this event was about — convenience for status output. */
+  packageName: string;
+  packageVersion: string;
+  /** Dist-tag (e.g. 'latest', 'alpha'). */
+  tag: string;
+  /** Attempts spent (1 + retries). */
+  attempts: number;
+  /** Total ms spent including retries. */
+  durationMs: number;
+  /** HTTP status, if a response came back. Absent on network errors. */
+  status?: number;
+  /** Error message; only present on failed deliveries. */
+  error?: string;
+}
+
+function buildPayload(event: PublishEvent, result: DeliveryResult): WebhookDeliveryPayload {
+  return {
+    subscriberLabel: result.subscriber.name ?? result.subscriber.url,
+    subscriberUrl: result.subscriber.url,
+    eventId: event.eventId,
+    packageName: event.package.name,
+    packageVersion: event.package.version,
+    tag: event.tag,
+    attempts: result.attempts,
+    durationMs: result.durationMs,
+    status: result.status,
+    error: result.error,
+  };
+}
+
+/**
+ * Best-effort emit. Failures here (DB locked, disk full) get logged
+ * to stderr but never propagate — the actual webhook ALREADY
+ * succeeded (or failed) on the wire; recording the outcome is
+ * housekeeping.
+ */
+function emitBest(type: string, payload: WebhookDeliveryPayload): void {
+  let bus: ReturnType<typeof openBus> | undefined;
+  try {
+    bus = openBus({ dbPath: getEventBusPath(), events: NO_SCHEMAS });
+    bus.emitRaw(type, payload);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[build-bus] failed to record ${type}: ${msg}`);
+  } finally {
+    bus?.close();
+  }
+}
+
+/** Record one delivery outcome on the local bus. */
+export function recordDeliveryOutcome(event: PublishEvent, result: DeliveryResult): void {
+  const type = result.ok ? WEBHOOK_DELIVERED_EVENT : WEBHOOK_FAILED_EVENT;
+  emitBest(type, buildPayload(event, result));
+}

package/src/services/build-bus/event-factory.ts

@@ -0,0 +1,54 @@
+/**
+ * Build PublishEvent payloads from the publish-flow output.
+ *
+ * `executePlan` returns a list of `{name, version}` for each
+ * published package. Each entry becomes a PublishEvent. The event's
+ * `registry` and `tag` flow from the publish mode (alpha/normal/
+ * promote) so subscribers can filter accurately — an alpha
+ * subscriber doesn't fire on real publishes.
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { PublishEvent } from '@celilo/event-bus/build-bus';
+
+export interface PublishedItem {
+  name: string;
+  version: string;
+}
+
+export interface EventFactoryInput {
+  published: PublishedItem[];
+  /** Per the publish mode: `latest` for normal, `alpha` for alpha. Promote ships under `latest`. */
+  tag: 'latest' | 'alpha';
+  /** Current git HEAD at publish time. Optional. */
+  gitHead?: string;
+  /** Defaults to "npm". The cross-machine event flow doesn't care. */
+  registry?: string;
+  /**
+   * Time + UUID injection for deterministic tests. Production
+   * omits, uses Date.now + crypto.randomUUID.
+   */
+  now?: () => Date;
+  newId?: () => string;
+}
+
+/**
+ * Build one PublishEvent per published package. Pure given the
+ * injectables — same input + same `now`/`newId` produces the same
+ * events.
+ */
+export function eventsForPublished(input: EventFactoryInput): PublishEvent[] {
+  const tag = input.tag;
+  const registry = input.registry ?? 'npm';
+  const now = input.now ?? (() => new Date());
+  const newId = input.newId ?? (() => randomUUID());
+
+  return input.published.map(({ name, version }) => ({
+    eventId: newId(),
+    timestamp: now().toISOString(),
+    registry,
+    tag,
+    package: { name, version },
+    gitHead: input.gitHead,
+  }));
+}