@celilo/cli 0.11.0 → 0.12.1

package/src/db/schema.ts

@@ -318,7 +318,7 @@ export const machines = sqliteTable('machines', {
    * Appliance machines (e.g., greenwave = ISP modem) where celilo
    * has no shell-level access — only API calls. Base-module aspects
    * cannot Ansible to these systems, so the aspect runner skips
-   * them. See v2/CELILO_BASE.md D8.
+   * them. See openspec/specs/base-module-aspects/spec.md D8.
    */
   apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
@@ -345,7 +345,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
    * driver registers an entry that has no SSH surface (rare today,
    * but exists for future API-only providers). Aspect runner reads
    * this to decide whether the system is reachable via Ansible.
-   * See v2/CELILO_BASE.md D8.
+   * See openspec/specs/base-module-aspects/spec.md D8.
    */
   apiOnly: integer('api_only', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
@@ -358,7 +358,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
  * deployment-STATE counterpart to module_configs (declared inputs): it records,
  * per deployed system, the hostname + IPv4 + zone + where it lives. Replaces the
  * old scalar `target_ip`/`vmid` rows in module_configs, which baked in the
- * one-module-one-host assumption. See v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * one-module-one-host assumption. See openspec/specs/module-systems-addressing/spec.md.
  *
  *   - 0 rows: API-only modules (e.g. namecheap — no host).
  *   - 1 row:  the common case (technitium, homebridge, …).
@@ -368,7 +368,7 @@ export const moduleInfrastructure = sqliteTable('module_infrastructure', {
  * the manifest's `requires.systems[].name` — what templates reference via
  * `$infra:<name>.…`. `hostname` is the runtime DNS hostname (often == name, but
  * user/well-known-assignable), used by DNS and events. See
- * v2/MODULE_SYSTEMS_ADDRESSING.md.
+ * openspec/specs/module-systems-addressing/spec.md.
  */
 export const moduleSystems = sqliteTable(
   'module_systems',
@@ -443,6 +443,49 @@ export const webRoutes = sqliteTable(
   }),
 );
 
+/**
+ * Port-forward registry — the desired-state store for the `firewall` capability
+ * (openspec/changes/unified-management-no-ssh/proposal.md). One row per exposed forward. `exposeService`
+ * upserts, `unexposeService` deletes, and the firewall provider's converge
+ * renders the COMPLETE ruleset for a firewall from these rows and applies it
+ * atomically via `iptables-restore` — replacing the old per-rule `iptables -A`
+ * (non-idempotent) + the "read the box back with iptables -L" source of truth.
+ *
+ * Keyed by `firewall_ip` (the converge target) so multiple firewalls each render
+ * their own set. Shared-core (not a per-module JSON file) so any firewall
+ * provider reconciles against the one canonical store.
+ */
+export const portForwards = sqliteTable(
+  'port_forwards',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** The firewall host this forward is installed on (config.firewallIp). */
+    firewallIp: text('firewall_ip').notNull(),
+    /** Backend IP the forward targets. */
+    internalIp: text('internal_ip').notNull(),
+    /** Port — external == internal (no translation today). */
+    port: integer('port').notNull(),
+    protocol: text('protocol').$type<'TCP' | 'UDP'>().notNull(),
+    /** Dedicated INTERNAL ingress IP (ISS-0156); NULL for the normal public path. */
+    ingressIp: text('ingress_ip'),
+    description: text('description').notNull().default(''),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    // One row per (firewall, backend, port, protocol, ingress). The store also
+    // delete-then-inserts on this tuple so a re-expose is an idempotent upsert
+    // (NULL ingress_ip is compared with `is null` there, since SQLite treats
+    // NULLs as distinct in a unique index).
+    forwardUnique: uniqueIndex('port_forwards_unique_idx').on(
+      table.firewallIp,
+      table.internalIp,
+      table.port,
+      table.protocol,
+      table.ingressIp,
+    ),
+  }),
+);
+
 /**
  * DNS registration ledger — one row per (provider, fqdn) the framework
  * has successfully registered via dns_registrar.registerHost. Written
@@ -509,7 +552,7 @@ export const dnsInternalRecords = sqliteTable(
     /**
      * In-zone split-horizon answer (caddy's zone-routable IP), when this is a
      * caddy-fronted hostname that needs source-based views (ISS-0156,
-     * v2/INTERNAL_DNS_ZONE_VIEWS.md). NULL for records with no zone override
+     * openspec/specs/internal-dns-zone-views/spec.md). NULL for records with no zone override
      * (per-system identity, plain A records). This column is the durable
      * desired-state the resolver's view config is reconciled from.
      */
@@ -621,7 +664,7 @@ export const moduleOperations = sqliteTable('module_operations', {
  * per module version. Cascade delete on module removal so stale
  * approvals don't linger.
  *
- * See v2/CELILO_BASE.md D2 + D7.
+ * See openspec/specs/base-module-aspects/spec.md D2 + D7.
  */
 export const aspectApprovals = sqliteTable(
   'aspect_approvals',
@@ -655,7 +698,7 @@ export const aspectApprovals = sqliteTable(
 );
 
 /**
- * Remote API principals (see v2/API_COMMUNICATION.md).
+ * Remote API principals (see openspec/changes/replace-ssh-cli-api/proposal.md).
  *
  * Each row is one API identity: a name, one SSH public key, and the set of
  * operations it may run. celilo renders these into the API account's

package/src/hooks/capability-loader-firewall.test.ts

@@ -47,12 +47,13 @@ export default defineCapabilityFunction({
 `;
 
 // Mock iptables firewall factory — kept on the legacy
-// `createFirewall(config, upstreamFirewall)` shape because its
+// `createFirewall(config, store, upstreamFirewall, logger)` shape because its
 // upstream-injection signature doesn't fit the
 // defineCapabilityFunction `{ config, secrets, logger }` context.
-// buildFirewallChain detects this and wires the upstream manually.
+// buildFirewallChain injects the port-forward store (2nd arg) and wires the
+// upstream (3rd arg) manually. The mock ignores store (no converge here).
 const MOCK_IPTABLES_MODULE = `
-export function createFirewall(config, upstreamFirewall) {
+export function createFirewall(config, store, upstreamFirewall, logger) {
   return {
     exposeService: async (opts) => {
       if (!upstreamFirewall) {

package/src/hooks/capability-loader.ts

@@ -21,18 +21,20 @@ import type {
   DnsInternalCapability,
   DnsRegistrarCapability,
   HookLogger,
+  PortForwardStore,
   RouteOps,
   RouteReadView,
 } from '@celilo/capabilities';
 import { and, eq } from 'drizzle-orm';
 import type { DbClient } from '../db/client';
-import { capabilities, modules, secrets, webRoutes } from '../db/schema';
+import { capabilities, modules, secrets, systemConfig, webRoutes } from '../db/schema';
 import { decryptSecret } from '../secrets/encryption';
 import { getOrCreateMasterKey } from '../secrets/master-key';
 import { emitWebRoutesChangedAndWait } from '../services/celilo-events';
 import { getModuleSystems } from '../services/deployed-systems';
 import { withDnsInternalLedger } from '../services/dns-internal-records';
 import { withDnsRegistrationLedger } from '../services/dns-registrations';
+import { buildPortForwardStore } from '../services/port-forwards';
 import { resolveComputedFields } from '../variables/computed/evaluate';
 import { containsComputedMarker } from '../variables/computed/marker';
 import { buildProviderLookup } from '../variables/computed/provider-lookup';
@@ -288,6 +290,10 @@ export async function loadCapabilityFunctions(
         exported,
         providerConfig,
         providerSecrets,
+        // Single firewall provider (no upstream chain) still needs the injected
+        // port-forward store — the chain path isn't taken when there's one provider.
+        capName === 'firewall' ? buildPortForwardStore(db) : undefined,
+        capName === 'firewall' ? loadFirewallZones(db) : undefined,
       );
 
       if (capabilityInterface) {
@@ -326,6 +332,17 @@ export async function loadCapabilityFunctions(
       debugLog(`public_web: using firewall natIp ${firewallNatIp} for internal DNS`);
     }
 
+    // Caddy's external (WAN) IP for the D1 public A record (M1 / #328). Caddy
+    // learns it from its own firewall.exposeService at install and persists it
+    // as the `public_ip` hook output (stored as a caddy secret). register_route
+    // points a new hostname's PUBLIC record here, so it's reachable from one
+    // deploy — no per-hostname DNAT (shared :443 ingress).
+    const caddyExternalIp =
+      typeof providerSecrets.public_ip === 'string' ? providerSecrets.public_ip : undefined;
+    if (caddyExternalIp) {
+      debugLog(`public_web: using caddy externalIp ${caddyExternalIp} for public DNS`);
+    }
+
     // Caddy's configured hostnames — public_web rejects routes for any
     // hostname not in this list, throwing a structured error that runs
     // caddy's `managed_hostname` ensure interview. Empty list means
@@ -437,6 +454,8 @@ export async function loadCapabilityFunctions(
         routeOps,
         dnsInternal: result.dns_internal as DnsInternalCapability | undefined,
         firewallNatIp,
+        dnsRegistrar: result.dns_registrar as DnsRegistrarCapability | undefined,
+        externalIp: caddyExternalIp,
         hostnames: caddyHostnames,
         caddyModuleId: provider.moduleId,
         dnsManagedDomains,
@@ -525,16 +544,28 @@ function buildCapabilityInterface(
   factory: (...args: unknown[]) => unknown,
   config: Record<string, unknown>,
   _secrets: Record<string, string>,
+  store?: PortForwardStore,
+  zones?: FirewallZones,
 ): unknown {
   if (capabilityName === 'firewall') {
-    // iptables firewall factory: SSH access + NAT config (upstream is
-    // injected by buildFirewallChain when this module is downstream of
-    // another firewall provider).
+    // iptables firewall factory: NAT config + the injected port-forward store
+    // (createFirewall(config, store, upstream?, logger?)). Upstream is injected
+    // by buildFirewallChain when this module is downstream of another provider.
+    // The firewall is only built through buildFirewallChain, which always passes
+    // a store — guard so a mis-route surfaces loudly rather than as store=undefined.
     if (config.firewall_ip && config.nat_ip) {
-      return factory({
-        firewallIp: config.firewall_ip as string,
-        natIp: config.nat_ip as string,
-      });
+      if (!store) {
+        throw new Error('firewall capability requires an injected port-forward store');
+      }
+      return factory(
+        {
+          firewallIp: config.firewall_ip as string,
+          natIp: config.nat_ip as string,
+          zoneTiers: zones?.zoneTiers ?? [],
+          trustedSubnets: zones?.trustedSubnets ?? [],
+        },
+        store,
+      );
     }
     return null;
   }
@@ -624,6 +655,40 @@ async function resolveRegistrarDomainList(
  * on the legacy `createFirewall(config, upstream)` path because its
  * upstream-injection signature doesn't fit the new shape.
  */
+/** Most-exposed → most-protected SEGMENTED tiers for the firewall default-DROP matrix. */
+const ZONE_TIER_ORDER = ['dmz', 'app', 'secure'] as const;
+
+interface FirewallZones {
+  /** Ordered segmented tiers (dmz→app→secure adjacency) for the data-plane matrix. */
+  zoneTiers: Array<{ name: string; subnet: string }>;
+  /** Trusted LAN subnets (internal) that reach every tier — celilo's control plane. */
+  trustedSubnets: string[];
+}
+
+function readZoneSubnet(db: DbClient, zone: string): string | undefined {
+  const row = db
+    .select()
+    .from(systemConfig)
+    .where(eq(systemConfig.key, `network.${zone}.subnet`))
+    .get();
+  return row?.value ?? undefined;
+}
+
+/**
+ * Read the firewall zone matrix inputs from system config (network.<zone>.subnet):
+ * the segmented tiers [dmz, app, secure] and the trusted internal LAN. Zones with
+ * no configured subnet are omitted — their traffic stays denied (fail-closed).
+ */
+function loadFirewallZones(db: DbClient): FirewallZones {
+  const zoneTiers: Array<{ name: string; subnet: string }> = [];
+  for (const zone of ZONE_TIER_ORDER) {
+    const subnet = readZoneSubnet(db, zone);
+    if (subnet) zoneTiers.push({ name: zone, subnet });
+  }
+  const internal = readZoneSubnet(db, 'internal');
+  return { zoneTiers, trustedSubnets: internal ? [internal] : [] };
+}
+
 async function buildFirewallChain(
   allProviders: Array<{
     id: number;
@@ -638,6 +703,13 @@ async function buildFirewallChain(
   logger: HookLogger,
   debugLog: (msg: string) => void,
 ): Promise<unknown> {
+  // The shared-core port-forward registry, injected into every firewall provider
+  // in the chain so exposeService/converge reconcile against the one canonical
+  // store (openspec/changes/unified-management-no-ssh/proposal.md).
+  const store = buildPortForwardStore(db);
+  // Zone matrix for the default-DROP posture — same set for every layer in the chain.
+  const zones = loadFirewallZones(db);
+
   // Find the provider with has_external (the leaf — has direct internet access)
   const hasExternal = allProviders.find((p) => {
     const data = (typeof p.data === 'string' ? JSON.parse(p.data) : p.data) as Record<
@@ -686,7 +758,14 @@ async function buildFirewallChain(
     );
   } else {
     // Legacy factory path
-    leafFirewall = buildCapabilityInterface('firewall', leafExported, leafConfig, leafSecrets);
+    leafFirewall = buildCapabilityInterface(
+      'firewall',
+      leafExported,
+      leafConfig,
+      leafSecrets,
+      store,
+      zones,
+    );
     if (leafFirewall) {
       leafFirewall = wrapWithLogging(leafFirewall as object, logger, 'firewall');
     }
@@ -741,7 +820,18 @@ async function buildFirewallChain(
     // celilo's ProgressDisplay instead of dumping to stderr. Older
     // iptables modules ignore it — the factory's signature is
     // backward-compatible.
-    const downstreamFirewall = provFactory({ firewallIp, natIp, dryRun }, currentUpstream, logger);
+    const downstreamFirewall = provFactory(
+      {
+        firewallIp,
+        natIp,
+        dryRun,
+        zoneTiers: zones.zoneTiers,
+        trustedSubnets: zones.trustedSubnets,
+      },
+      store,
+      currentUpstream,
+      logger,
+    );
 
     debugLog(`firewall chain: wired ${provider.moduleId} → ${hasExternal.moduleId}`);
     // Wrap each downstream layer with auto-logging.

package/src/hooks/define-hook.test.ts

@@ -95,6 +95,12 @@ const fakeIdp: IdpCapability = {
   async create_token() {
     return { token: 'fake-token', created: true };
   },
+  async list_tokens() {
+    return [];
+  },
+  async revoke_token() {
+    return { revoked: true };
+  },
 };
 
 describe('defineHook', () => {
@@ -260,6 +266,12 @@ describe('defineCapabilityFunction', () => {
         async create_token() {
           return { token: 'fake-token', created: true };
         },
+        async list_tokens() {
+          return [];
+        },
+        async revoke_token() {
+          return { revoked: true };
+        },
       }),
     });
 
@@ -323,6 +335,12 @@ describe('defineCapabilityFunction', () => {
           async create_token(): Promise<{ token: string; created: boolean }> {
             return { token: 'tok', created: true };
           },
+          async list_tokens() {
+            return [];
+          },
+          async revoke_token(): Promise<{ revoked: boolean }> {
+            return { revoked: true };
+          },
         };
       },
     });
@@ -459,6 +477,12 @@ void defineCapabilityFunction({
     async create_token() {
       return { token: 'x', created: true };
     },
+    async list_tokens() {
+      return [];
+    },
+    async revoke_token() {
+      return { revoked: true };
+    },
   }),
 });
 

package/src/hooks/executor.test.ts

@@ -469,7 +469,7 @@ describe('Hook Executor', () => {
       // cross_module_read is a privilege granted by the framework to the
       // hooks that use it (backup/restore), not a provider-loaded
       // capability. It must not block other hooks like on_install
-      // (regression: celilo-mgmt deploy, v2/NETWORK_CONFIG_TO_FIREWALL.md).
+      // (regression: celilo-mgmt deploy, openspec/specs/progressive-zone-disclosure/spec.md).
       expect(checkRequiredCapabilities('on_install', ['cross_module_read'], {})).toBeNull();
       // Real missing providers still flagged alongside a privilege.
       const mixed = checkRequiredCapabilities('on_install', ['cross_module_read', 'idp'], {});

package/src/hooks/executor.ts

@@ -202,7 +202,7 @@ async function runScript(
 
   if (!isCompiledHook(module.default)) {
     throw new Error(
-      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See design/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
+      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See reference/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
     );
   }
 
@@ -263,7 +263,7 @@ export interface InvokeHookOptions {
   capabilities?: Record<string, unknown>;
   /**
    * The module's 0..N deployed systems, injected as `ctx.systems`
-   * (v2/MODULE_SYSTEMS_ADDRESSING.md). Callers load these from the DB via
+   * (openspec/specs/module-systems-addressing/spec.md). Callers load these from the DB via
    * `getModuleSystems` — the executor stays decoupled from the database, the
    * same way `capabilities` is loaded by the caller. Defaults to `[]`.
    */

package/src/hooks/types.ts

@@ -55,7 +55,7 @@ export interface HookContext {
   /** Module secret values (decrypted) */
   secrets: Record<string, string>;
   /**
-   * The 0..N systems this module has deployed onto (v2/MODULE_SYSTEMS_ADDRESSING.md).
+   * The 0..N systems this module has deployed onto (openspec/specs/module-systems-addressing/spec.md).
    * Always an array — no singular convenience, so the 0/1/N reality stays visible.
    */
   systems: DeployedSystem[];

package/src/manifest/contracts/v1.ts

@@ -145,7 +145,7 @@ export const V1_HOOKS: ContractHooks = {
     },
   },
   /**
-   * Per-system DNS lifecycle hook (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D5).
+   * Per-system DNS lifecycle hook (openspec/specs/internal-dns-split-horizon/spec.md D5).
    *
    * A dns_internal provider declares this hook; celilo's internal-dns bridge
    * invokes it once per host when a system.created/destroyed event fires,
@@ -198,7 +198,7 @@ export const V1_HOOKS: ContractHooks = {
    * Build-bus upstream publish hook. The executor passes the
    * PublishEvent fields as env vars (CELILO_EVENT_PAYLOAD,
    * CELILO_EVENT_PACKAGE_NAME, etc.) rather than as named inputs
-   * here — see v2/BUILD_BUS.md Phase 4 + the hook-dispatch executor.
+   * here — see openspec/changes/build-bus-poll-cd/proposal.md Phase 4 + the hook-dispatch executor.
    * No structured outputs; hook reports success via exit code.
    */
   on_upstream_publish: {

package/src/manifest/schema.ts

@@ -214,7 +214,7 @@ export const EnsureSchema = z.object({
 export type Ensure = z.infer<typeof EnsureSchema>;
 
 /**
- * A computed capability field (v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md D1).
+ * A computed capability field (openspec/specs/internal-dns-split-horizon/spec.md D1).
  *
  * Declared alongside `data`, but derived ON ACCESS from other values via the
  * `value:` DSL (see src/variables/computed/) and never persisted. The result
@@ -275,7 +275,7 @@ export const LifecycleHookSchema = z.object({
 /**
  * Build-bus upstream-publish hook. Fires when a publish event lands
  * on the local event bus from the receiver daemon
- * ([[v2/BUILD_BUS.md]] Phase 4). Each module can declare multiple
+ * ([[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4). Each module can declare multiple
  * entries, each with its own match rule + action script.
  *
  * The action script runs with `CELILO_EVENT_PAYLOAD` in its env (the
@@ -326,7 +326,7 @@ export const SystemResourceSchema = z.object({
 });
 
 /**
- * One system a module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md). A module
+ * One system a module deploys (openspec/specs/module-systems-addressing/spec.md). A module
  * declares 0..N of these under `requires.systems`. `name` is the stable
  * authoring-time handle — referenced in templates via `$infra:<name>.…` and the
  * per-system key in `module_systems`. `resources` carries the per-system machine
@@ -390,7 +390,7 @@ export const ModuleSubscriptionSchema = z
     handler: z.string().min(1).optional(),
     /**
      * Name of one of THIS module's own hooks to invoke when a matching event
-     * fires (v2/EVENT_DRIVEN_HOOK_SUBSCRIPTIONS.md). The framework synthesizes
+     * fires (openspec/specs/event-driven-hook-subscriptions/spec.md). The framework synthesizes
      * a `celilo events run-hook` handler that runs the hook in a
      * fault-isolated subprocess with backend access (DB, capabilities,
      * secrets). Mutually exclusive with `handler`.
@@ -445,7 +445,7 @@ export const ModuleManifestSchema = z
 
     /**
      * How `manifest.yml#version` (the PAYLOAD version) is determined — see
-     * v2/MODULE_VERSIONING.md / ISS-0151. The capability *contract* version
+     * openspec/changes/module-version-semantics/proposal.md / ISS-0151. The capability *contract* version
      * lives in `provides.capabilities[].version` and is unrelated to this.
      *
      * - `changeset` — first-party apps/content (lunacycle): the version is
@@ -471,7 +471,7 @@ export const ModuleManifestSchema = z
       .object({
         capabilities: z.array(CapabilityRequirementSchema).default([]),
         /**
-         * The 0..N systems this module deploys (v2/MODULE_SYSTEMS_ADDRESSING.md).
+         * The 0..N systems this module deploys (openspec/specs/module-systems-addressing/spec.md).
          * Preferred over the singular `system`. A module declaring
          * `systems` gets one host per entry, each addressable as `$infra:<name>`.
          */
@@ -545,7 +545,7 @@ export const ModuleManifestSchema = z
          * to (de)register a single host's A records when celilo's bridge
          * delivers a system.created/destroyed event. Inputs (hostname,
          * target_ip, op) come from the contract — see contracts/v1.ts and
-         * [[v2/INTERNAL_DNS_DHCP_AND_SPLIT_HORIZON.md]] D5.
+         * [[openspec/specs/internal-dns-split-horizon/spec.md]] D5.
          */
         on_system_event: LifecycleHookSchema.optional(),
         /**
@@ -553,7 +553,7 @@ export const ModuleManifestSchema = z
          * change event. The caddy `public_web` provider declares this to
          * re-render its Caddyfile from web_routes when a consumer registers or
          * unregisters a route (ISS-0035). See
-         * [[v2/PUBLIC_WEB_PROVIDER_RECONCILE.md]].
+         * [[openspec/specs/public-web-provider-reconcile/spec.md]].
          */
         reconcile_routes: LifecycleHookSchema.optional(),
         /**
@@ -569,7 +569,7 @@ export const ModuleManifestSchema = z
         /**
          * Build-bus upstream publish hooks. Array (a module can react
          * to multiple upstream packages with different actions). See
-         * [[v2/BUILD_BUS.md]] Phase 4.
+         * [[openspec/changes/build-bus-poll-cd/proposal.md]] Phase 4.
          */
         on_upstream_publish: z.array(UpstreamPublishHookSchema).optional(),
       })
@@ -645,7 +645,7 @@ export const ModuleManifestSchema = z
 
     /**
      * Event-bus subscriptions this module wants registered. See
-     * `infra/design/SQLITE_EVENT_BUS.md`. Truly optional so existing
+     * `infra/openspec/specs/event-bus/spec.md`. Truly optional so existing
      * test fixtures and manifests don't need a churn-pass; readers
      * use `manifest.subscriptions ?? []`.
      */
@@ -654,7 +654,7 @@ export const ModuleManifestSchema = z
     /**
      * Optional base-module aspect — lightweight fleet-configuration
      * code applied to OTHER systems in declared zones, on top of
-     * the module's primary deployment. See v2/CELILO_BASE.md.
+     * the module's primary deployment. See openspec/specs/base-module-aspects/spec.md.
      *
      * Modules without this block work exactly as today. When
      * declared, the operator approves the aspect's scope at
@@ -723,7 +723,7 @@ export const ModuleManifestSchema = z
         ansible_vars: z.record(z.string(), z.string()).optional(),
 
         /**
-         * Optional Proxmox reconciliation (v2/CELILO_BASE.md D5).
+         * Optional Proxmox reconciliation (openspec/specs/base-module-aspects/spec.md D5).
          *
          * When an aspect manages a setting that Proxmox also owns
          * authoritatively (DNS resolver via `proxmox_lxc.nameserver`
@@ -779,7 +779,7 @@ export type BaseModuleAspect = NonNullable<ModuleManifest['base_module_aspect']>
 export type BaseModuleAspectTrigger = BaseModuleAspect['triggers'][number];
 
 /**
- * Normalize a manifest's declared systems (v2/MODULE_SYSTEMS_ADDRESSING.md).
+ * Normalize a manifest's declared systems (openspec/specs/module-systems-addressing/spec.md).
  * Returns `requires.systems` if present; else the singular `requires.system`
  * as one entry named `main`; else `[]` (config-only module like namecheap).
  * This is the single place the system→systems sugar lives, so the rest of the

package/src/manifest/template-validator.ts

@@ -72,7 +72,7 @@ const AUTO_ALLOCATED_VARIABLES = new Set([
   'vlan', // Auto-derived from zone configuration
   'gateway', // Auto-derived from zone configuration
   'target_node', // Can be auto-derived from system config
-  'lxc_nameserver', // Composed at generate time from dns_internal + dns.primary (v2/LXC_INTERNAL_DNS.md)
+  'lxc_nameserver', // Composed at generate time from dns_internal + dns.primary (openspec/specs/lxc-dns-at-birth/spec.md)
   // Instance sizing (ISS-0150): the instance Terraform reads $self:{cores,memory,
   // disk,storage}, which are injected during resolution from the module_systems
   // table (falling back to requires.system.*) — see variables/context.ts. Like

package/src/module/packaging/build.ts

@@ -10,6 +10,7 @@ import { validateModuleDirectory } from '../import';
 import { computeFileChecksum } from './checksum';
 import { includeNodeModulesPath } from './package-rules';
 import { signChecksums } from './signature';
+import { rewriteWorkspaceDeps } from './workspace-deps';
 
 /**
  * Checksums data structure
@@ -222,6 +223,24 @@ export async function buildModule(options: ModuleBuildOptions): Promise<ModuleBu
     const manifest = parseYaml(manifestContent);
     if (manifest.build?.command || manifest.build?.script) {
       log.info(`Building module (${manifest.build.command ? 'command' : 'script'})...`);
+
+      // Resolve `workspace:` build deps (ISS-0147 / celilo#216). The staged
+      // buildDir has no workspace root, so a sibling monorepo package pulled in
+      // via `workspace:^` won't resolve during the build's `bun install`.
+      // Rewrite those specs to `file:` paths pointing at the live monorepo
+      // members — always-fresh, no npm-pin lag, no hand-rolled
+      // CELILO_MODULE_SOURCE_DIR dance. Fails loudly naming any unresolvable dep.
+      try {
+        for (const rewrite of rewriteWorkspaceDeps(buildDir, sourceDir)) {
+          log.info(`Resolved workspace dep: ${rewrite}`);
+        }
+      } catch (rewriteError) {
+        return {
+          success: false,
+          error: rewriteError instanceof Error ? rewriteError.message : String(rewriteError),
+        };
+      }
+
       // The build runs in a staged copy of the module (buildDir), so
       // relative paths that reach outside the module (e.g. sibling packages
       // in a monorepo) don't resolve. Expose the ORIGINAL unstaged source