feat(mosaic): leaseEnforcementActivatable() capability probe (#869 C1)

Adds a real activation-capability probe so a downstream install-ordering guard (C2, out of scope here) can refuse to wire lease-broker enforcement (PreToolUse/Stop hooks) on a host that cannot actually activate it — the root cause of #828's version-skew brick, where the published CLI tarball lagged the enforcement reseed and every tool call denied with GATE_UNAVAILABLE. - LEASE_ACTIVATION_CAPABILITY {name, version}: versioned signal owned by the activation half (execLeaseGatedRuntime), independent of npm semver. - Hidden `mosaic __lease-capability` subcommand: prints that capability from the actually-resolvable built CLI artifact, not source-tree presence. - leaseEnforcementActivatable(): pure predicate, true iff a compatible capability is advertised AND the broker supervisor (launcher + daemon.py artifacts, socket path) resolves. Detection only — never starts the broker. Both inputs are injectable for testing. - C-REGRESS: added a vitest spec that runs the two test-locked fail-closed gate cases in runtime_tools_unittest.py directly, proving the gate's fail-closed-on-absent-identity behavior is unchanged by this card. Part of #869 (Point-1 C1). Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-07-22 13:36:29 -05:00
parent b79336a8c1
commit 763cecc381
5 changed files with 417 additions and 2 deletions
@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import {
+  LEASE_ACTIVATION_CAPABILITY,
+  LEASE_CAPABILITY_PROBE_COMMAND,
+  defaultCapabilityProbe,
+  defaultSupervisorProbe,
+  leaseEnforcementActivatable,
+  registerLeaseCapabilityProbe,
+  type LeaseActivationCapability,
+  type SupervisorProbeResult,
+} from './lease-activation-probe.js';
+
+/**
+ * Red-first tests for issue #869 Point-1 C1 — leaseEnforcementActivatable().
+ *
+ * Root cause under test: #828 shipped the lease broker's ENFORCEMENT half
+ * (hooks) and ACTIVATION half (execLeaseGatedRuntime + a running daemon.py
+ * broker) on different channels, and they drifted — the published CLI
+ * tarball lacked the activation half even though it existed in source. The
+ * predicate here must say NO when either half of activation is unavailable,
+ * and only YES when both are genuinely present — never based on "does the
+ * source file exist", but on a real capability signal + real supervisor
+ * detection.
+ */
+
+const compatibleCapability: LeaseActivationCapability = { ...LEASE_ACTIVATION_CAPABILITY };
+const presentSupervisor: SupervisorProbeResult = {
+  supervisorPresent: true,
+  socketPath: '/run/user/1000/mosaic-lease/broker.sock',
+};
+
+describe('leaseEnforcementActivatable', () => {
+  it('is false when the activation capability is absent (null)', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => null,
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the activation capability name does not match', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => ({
+        name: 'some-other-capability',
+        version: LEASE_ACTIVATION_CAPABILITY.version,
+      }),
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the activation capability version is incompatible (stale/newer build)', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => ({
+        name: LEASE_ACTIVATION_CAPABILITY.name,
+        version: LEASE_ACTIVATION_CAPABILITY.version + 1,
+      }),
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the supervisor artifacts (launcher/daemon) are not present', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => ({
+        supervisorPresent: false,
+        socketPath: presentSupervisor.socketPath,
+      }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when the supervisor socket path is not resolvable', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => ({ supervisorPresent: true, socketPath: null }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is false when BOTH capability and supervisor are absent', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => null,
+      probeSupervisor: () => ({ supervisorPresent: false, socketPath: null }),
+    });
+    expect(result).toBe(false);
+  });
+
+  it('is true when a compatible capability AND a resolvable supervisor are both present', () => {
+    const result = leaseEnforcementActivatable({
+      getCapability: () => compatibleCapability,
+      probeSupervisor: () => presentSupervisor,
+    });
+    expect(result).toBe(true);
+  });
+
+  it('uses the real default probes when no deps are injected (does not throw)', () => {
+    // No live broker / built CLI is guaranteed in a test environment, so this
+    // only asserts the predicate degrades to a safe boolean rather than
+    // throwing — the fail-closed behavior itself is covered by the injected
+    // cases above.
+    expect(() => leaseEnforcementActivatable()).not.toThrow();
+    expect(typeof leaseEnforcementActivatable()).toBe('boolean');
+  });
+});
+
+describe('defaultCapabilityProbe', () => {
+  it('returns null (fail-closed) when no built CLI artifact is resolvable', () => {
+    // This source checkout has no dist/cli.js built for @mosaicstack/mosaic,
+    // so the probe must report "no capability" rather than fabricate one
+    // from source-tree presence — this is the exact distinction #828's
+    // version skew needed: source existing is not the same as the published
+    // artifact advertising the capability.
+    expect(defaultCapabilityProbe()).toBeNull();
+  });
+});
+
+describe('defaultSupervisorProbe', () => {
+  it('returns a well-shaped result without starting or connecting to anything', () => {
+    const result = defaultSupervisorProbe({});
+    expect(typeof result.supervisorPresent).toBe('boolean');
+    expect(result.socketPath === null || typeof result.socketPath === 'string').toBe(true);
+  });
+
+  it('resolves a socket path from an explicit MOSAIC_LEASE_BROKER_SOCKET override', () => {
+    const result = defaultSupervisorProbe({ MOSAIC_LEASE_BROKER_SOCKET: '/tmp/explicit.sock' });
+    expect(result.socketPath).toBe('/tmp/explicit.sock');
+  });
+});
+
+describe('registerLeaseCapabilityProbe', () => {
+  it('registers a hidden subcommand named __lease-capability', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerLeaseCapabilityProbe(program);
+
+    const registered = program.commands.find((c) => c.name() === LEASE_CAPABILITY_PROBE_COMMAND);
+    expect(registered).toBeDefined();
+    // Commander exposes "hidden" only as help-output suppression (no public
+    // getter) — assert the observable behavior instead of a private field.
+    expect(program.helpInformation()).not.toContain(LEASE_CAPABILITY_PROBE_COMMAND);
+  });
+
+  it('prints the capability constant as JSON when invoked', () => {
+    const program = new Command();
+    program.exitOverride();
+    registerLeaseCapabilityProbe(program);
+
+    let written = '';
+    const originalWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = ((chunk: string) => {
+      written += chunk;
+      return true;
+    }) as typeof process.stdout.write;
+
+    try {
+      program.parse(['node', 'mosaic', LEASE_CAPABILITY_PROBE_COMMAND]);
+    } finally {
+      process.stdout.write = originalWrite;
+    }
+
+    expect(JSON.parse(written)).toEqual(LEASE_ACTIVATION_CAPABILITY);
+  });
+});