@agfpd/iapeer 0.2.10 → 0.2.12

package/src/status/status.test.ts

@@ -0,0 +1,125 @@
+// Memory slot — the DECLARATIVE provider slot (docs/Слот памяти — контракт
+// memory provider.md): the core only READS the root declaration; absent /
+// unreadable / invalid → EMPTY slot (bare core, valid state, never an error).
+// Plus the host-status assembly + rendering (memory: <provider> | none).
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  formatHostStatus,
+  heartbeatAgeSecs,
+  hostStatus,
+  memoryProviderPath,
+  readMemoryProvider,
+  type HostStatus,
+  type MemoryProvider,
+} from './index.ts'
+
+const dirs: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-slot-'))
+  dirs.push(d)
+  return d
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string): NodeJS.ProcessEnv {
+  return { IAPEER_ROOT: root } as NodeJS.ProcessEnv
+}
+
+const VALID = {
+  provider: 'iapeer-memory',
+  package: '@agfpd/iapeer-memory',
+  version: '0.1.0',
+  registeredAt: '2026-06-10T00:00:00Z',
+}
+
+describe('readMemoryProvider (slot declaration, fail-open)', () => {
+  test('absent file → null (EMPTY slot — valid bare state)', () => {
+    expect(readMemoryProvider(envFor(mkTmp()))).toBeNull()
+  })
+
+  test('valid declaration → parsed provider; heartbeat optional', () => {
+    const root = mkTmp()
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify({ ...VALID, heartbeat: '/tmp/hb' }))
+    const p = readMemoryProvider(envFor(root))
+    expect(p).toMatchObject({ ...VALID, heartbeat: '/tmp/hb' })
+    // without heartbeat — field absent, not empty-string
+    writeFileSync(memoryProviderPath(envFor(root)), JSON.stringify(VALID))
+    expect(readMemoryProvider(envFor(root))?.heartbeat).toBeUndefined()
+  })
+
+  test('garbage / wrong shape / missing required fields → null, NEVER throws', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    for (const bad of ['NOT JSON {{{', '[]', '{}', JSON.stringify({ provider: 'x' }), JSON.stringify({ ...VALID, version: 42 })]) {
+      writeFileSync(memoryProviderPath(env), bad)
+      expect(readMemoryProvider(env)).toBeNull()
+    }
+  })
+})
+
+describe('heartbeatAgeSecs', () => {
+  test('no heartbeat declared → null; declared but absent file → null; present → age', () => {
+    const root = mkTmp()
+    expect(heartbeatAgeSecs({ ...VALID } as MemoryProvider)).toBeNull()
+    const hb = join(root, 'memoryd.heartbeat')
+    expect(heartbeatAgeSecs({ ...VALID, heartbeat: hb } as MemoryProvider)).toBeNull() // not running
+    writeFileSync(hb, '')
+    const old = (Date.now() - 45_000) / 1000
+    utimesSync(hb, old, old)
+    const age = heartbeatAgeSecs({ ...VALID, heartbeat: hb } as MemoryProvider)
+    expect(age).toBeGreaterThanOrEqual(44)
+    expect(age).toBeLessThanOrEqual(60)
+  })
+})
+
+describe('hostStatus + formatHostStatus', () => {
+  test('empty slot → memory: none; daemon health from the injected probe', async () => {
+    const root = mkTmp()
+    const s = await hostStatus({ env: envFor(root), probe: async () => true })
+    expect(s.daemon.healthy).toBe(true)
+    expect(s.memory.provider).toBeNull()
+    expect(formatHostStatus(s)).toContain('memory: none')
+  })
+
+  test('occupied slot + fresh heartbeat → provider line with age', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const hb = join(root, 'memoryd.heartbeat')
+    writeFileSync(hb, '')
+    writeFileSync(memoryProviderPath(env), JSON.stringify({ ...VALID, heartbeat: hb }))
+    const s = await hostStatus({ env, probe: async () => true })
+    expect(formatHostStatus(s)).toMatch(/memory: iapeer-memory 0\.1\.0 \(heartbeat \d+s ago\)/)
+  })
+
+  test('occupied slot, heartbeat declared but file ABSENT → "daemon not running" (graceful-shutdown semantics)', () => {
+    const s: HostStatus = {
+      version: '0.0.0',
+      daemon: { healthy: false, url: null, sock: null },
+      memory: {
+        provider: { ...VALID, heartbeat: '/nope/hb' } as MemoryProvider,
+        heartbeatAgeSecs: null,
+      },
+    }
+    const text = formatHostStatus(s)
+    expect(text).toContain('memory: iapeer-memory 0.1.0 (daemon not running — no heartbeat file)')
+    expect(text).toContain('daemon: NOT healthy')
+  })
+
+  test('discovery file addresses surface in the daemon line', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const stateDir = join(root, 'state', 'iapeer')
+    mkdirSync(stateDir, { recursive: true })
+    writeFileSync(join(stateDir, 'router.json'), JSON.stringify({ sock: '/x/router.sock', tcp: 'http://127.0.0.1:8765/mcp' }))
+    const s = await hostStatus({ env, probe: async () => true })
+    const text = formatHostStatus(s)
+    expect(text).toContain('@ http://127.0.0.1:8765/mcp')
+    expect(text).toContain('+ /x/router.sock')
+  })
+})

package/src/transport/index.ts

@@ -378,6 +378,14 @@ export interface RouteResult {
   delivered_to: { personality: string; runtime: string }
   woke: boolean
   ts: string
+  /** wake_policy:"ephemeral" M3 — true when the message was ENQUEUED for a
+   *  stateless worker rather than injected/woken synchronously: the daemon
+   *  drains the per-peer FIFO one task per fresh session (async). The
+   *  substantive result arrives as the worker's own reply (FaaS semantics);
+   *  `delivered_to` names the ACCEPTING queue identity, not a live session. */
+  queued?: boolean
+  /** Queue depth right after the enqueue (observability; only with queued). */
+  queueDepth?: number
 }
 
 // WakeFn — the lifecycle wake primitive, INJECTED (transport never imports
@@ -403,9 +411,29 @@ export interface WakeOutcome {
 }
 export type WakeFn = (req: WakeRequest) => Promise<WakeOutcome>
 
+/** wake_policy:"ephemeral" M3 — the injected serial-queue delivery seam. Like
+ *  WakeFn, transport never imports lifecycle: the daemon composition (main.ts)
+ *  wires the queue + drain behind this contract; absent → every target takes
+ *  the normal live/miss path (library/CLI/test callers unchanged). */
+export interface EphemeralRouteDeps {
+  /** Is the target peer (by its registry cwd) an ephemeral stateless worker? */
+  isEphemeral: (cwd: string) => boolean
+  /** Always-enqueue delivery: enqueue + async drain kick → fast `{queued:true}`
+   *  ack. MUST NOT block on the wake (the sender's content-level answer is the
+   *  worker's own reply, not this transport ack). */
+  deliver: (args: {
+    peer: PeerRecord
+    envelope: string
+    topic?: string
+    runtime?: string
+  }) => Promise<Result<RouteResult>>
+}
+
 export interface RouteDeps {
   /** On a miss, wake the dead peer instead of returning offline (Ф2). */
   wake?: WakeFn
+  /** Ephemeral-target serial-queue delivery (M3); absent → normal routing. */
+  ephemeral?: EphemeralRouteDeps
 }
 
 function truncateTopic(raw: string | undefined): string | undefined {
@@ -483,6 +511,17 @@ export async function routeSend(
     message,
   })
 
+  // M3 wake_policy:"ephemeral" — an ephemeral target is NEVER injected into a live
+  // session and never woken synchronously here: the delivery is ALWAYS enqueued
+  // (per-peer disk FIFO) and drained one task per fresh session, asynchronously.
+  // ONE delivery path by design: no live/miss race, strict FIFO, a clean context
+  // window per task. Self-send is refused up front (a worker enqueueing to itself
+  // would deadlock its own die-after-reply reap on a forever-non-empty queue).
+  if (deps.ephemeral?.isEphemeral(peer.cwd)) {
+    if (caller.personality === peer.personality) return err('cannot send to self')
+    return deps.ephemeral.deliver({ peer, envelope, topic, runtime })
+  }
+
   const target = resolvePeerDeliveryTarget(personality, runtime, peer)
   if (target.ok) {
     if (target.value.address === caller.address) return err('cannot send to self')