@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/layers/agent-base/scheduler/files/lib/scheduler/sweep.ts

@@ -0,0 +1,66 @@
+// agent-base:scheduler — sweep loop. The dispatcher process.
+//
+// The agent calls sweep() once at startup. The returned handle's stop()
+// is wired to graceful-shutdown so an unmounted agent doesn't leak the
+// timer. No background thread, no separate process — the in-sandbox
+// agent owns its own scheduler tick.
+
+import { fireDue } from './index.js'
+
+/** Handle returned by `sweep` — call `stop()` to halt further ticks. */
+export interface SweepHandle {
+  stop: () => void
+}
+
+export interface SweepOptions {
+  /** Tick interval in ms. Default 60_000 (one minute, matches cron resolution). */
+  intervalMs?: number
+  /** Optional logger override. Defaults to `console.error` for failures. */
+  onError?: (err: unknown, context: string) => void
+}
+
+/**
+ * Run the sweep loop. Each tick calls `fireDue()` and reports per-task
+ * failures via `onError` (default: `console.error`). The loop self-schedules
+ * via `setTimeout` so a long dispatch can't double-fire — the next tick
+ * starts only after the previous one resolves.
+ */
+export function sweep(options: SweepOptions = {}): SweepHandle {
+  const interval = options.intervalMs ?? 60_000
+  const onError = options.onError ?? ((err, context) => console.error(`[scheduler] ${context}:`, err))
+
+  let stopped = false
+  let timer: NodeJS.Timeout | null = null
+
+  const tick = async (): Promise<void> => {
+    if (stopped) return
+    try {
+      const results = await fireDue()
+      for (const r of results) {
+        if (!r.ok) onError(new Error(r.error ?? 'unknown error'), `task ${r.id} failed`)
+      }
+    } catch (err) {
+      onError(err, 'sweep error')
+    }
+    if (stopped) return
+    timer = setTimeout(() => {
+      void tick()
+    }, interval)
+    // Don't keep the event loop alive solely for the sweep — if the agent
+    // is otherwise idle, let it exit. The sandbox runtime restarts the
+    // process on the next inbound request.
+    if (typeof timer.unref === 'function') timer.unref()
+  }
+
+  void tick()
+
+  return {
+    stop: () => {
+      stopped = true
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+    },
+  }
+}

package/registry/layers/agent-base/scheduler/files/lib/scheduler/types.ts

@@ -0,0 +1,43 @@
+// agent-base:scheduler — type definitions for the in-sandbox cron
+// dispatcher. The dispatcher fires capabilities registered with the
+// agent-base:secure schedule registry; the registry owns identity +
+// audit, this layer owns *when* to fire.
+
+/** Persisted scheduled task. State lives at SCHEDULER_STATE_PATH. */
+export interface ScheduledTask {
+  /** Stable identifier; matches a row in the persisted state map. */
+  id: string
+  /** 5-field cron expression: minute hour dayOfMonth month dayOfWeek. */
+  cronExpr: string
+  /** Capability name registered with agent-base:secure schedule registry. */
+  capability: string
+  /** ISO timestamp of the most recent successful fire, or undefined. */
+  lastFiredAt?: string
+  /** ISO timestamp of the next scheduled fire (computed from cronExpr). */
+  nextFireAt: string
+  /** Optional payload merged into the dispatched ScheduledTrigger. */
+  payload?: Record<string, unknown>
+}
+
+/** Parsed cron expression — every field expanded to its concrete value list. */
+export interface CronFields {
+  /** 0-59 */
+  minute: number[]
+  /** 0-23 */
+  hour: number[]
+  /** 1-31 */
+  dayOfMonth: number[]
+  /** 1-12 */
+  month: number[]
+  /** 0-6, where 0 = Sunday. (Cron's `7` is normalized to `0`.) */
+  dayOfWeek: number[]
+  /** True if the expression had `*` for dayOfMonth (affects DOW/DOM matching). */
+  dayOfMonthStar: boolean
+  /** True if the expression had `*` for dayOfWeek. */
+  dayOfWeekStar: boolean
+}
+
+/** Persisted scheduler state on disk. */
+export interface SchedulerState {
+  tasks: Record<string, ScheduledTask>
+}

package/registry/layers/agent-base/scheduler/manifest.json

@@ -0,0 +1,119 @@
+{
+  "id": "scheduler",
+  "slot": "agent-base",
+  "description": "In-sandbox cron scheduler. Zero-dep cron parser + sweep loop dispatcher for the in-process schedule registry shipped by agent-base:secure. Persists task state at SCHEDULER_STATE_PATH (default /home/agent/scheduler/state.json). Bundles register cron-driven tasks; the agent itself owns the sweep tick (no external cron daemon, no cross-process trigger pipe). Composes with agent-base:secure \u2014 the registry there owns identity + audit; this layer owns when to fire.",
+  "appliesTo": [
+    "agent-runtime-account-executive-ts",
+    "agent-runtime-architect-ts",
+    "agent-runtime-auditor-ts",
+    "agent-runtime-biology-research-ts",
+    "agent-runtime-business-partner-ts",
+    "agent-runtime-career-coach-ts",
+    "agent-runtime-chef-ts",
+    "agent-runtime-chemistry-research-ts",
+    "agent-runtime-cmo-advisor-ts",
+    "agent-runtime-college-counselor-ts",
+    "agent-runtime-cs-research-ts",
+    "agent-runtime-cs-tutor-ts",
+    "agent-runtime-customer-success-ts",
+    "agent-runtime-data-analyst-ts",
+    "agent-runtime-designer-ts",
+    "agent-runtime-devops-ts",
+    "agent-runtime-doctor-ts",
+    "agent-runtime-engineering-manager-ts",
+    "agent-runtime-essay-coach-ts",
+    "agent-runtime-financial-analyst-ts",
+    "agent-runtime-fitness-coach-ts",
+    "agent-runtime-friend-ts",
+    "agent-runtime-game-designer-ts",
+    "agent-runtime-grant-writer-ts",
+    "agent-runtime-history-tutor-ts",
+    "agent-runtime-illustrator-ts",
+    "agent-runtime-language-tutor-ts",
+    "agent-runtime-legal-counsel-ts",
+    "agent-runtime-math-research-ts",
+    "agent-runtime-math-tutor-ts",
+    "agent-runtime-mediator-ts",
+    "agent-runtime-meditation-coach-ts",
+    "agent-runtime-ml-research-ts",
+    "agent-runtime-music-producer-ts",
+    "agent-runtime-novelist-coach-ts",
+    "agent-runtime-nutritionist-ts",
+    "agent-runtime-pentester-ts",
+    "agent-runtime-pharmacist-ts",
+    "agent-runtime-photographer-ts",
+    "agent-runtime-physics-research-ts",
+    "agent-runtime-product-manager-ts",
+    "agent-runtime-real-estate-ts",
+    "agent-runtime-recruiter-ts",
+    "agent-runtime-relationship-coach-ts",
+    "agent-runtime-research",
+    "agent-runtime-sales-engineer-ts",
+    "agent-runtime-screenwriter-ts",
+    "agent-runtime-security-engineer-ts",
+    "agent-runtime-tax-ts",
+    "agent-runtime-therapist-ts",
+    "agent-runtime-travel-planner-ts",
+    "agent-runtime-veterinarian-ts",
+    "agent-runtime-wealth-manager-ts",
+    "multi-agent-creative-studio-ts",
+    "multi-agent-legal-ops-ts",
+    "multi-agent-product-ops-ts",
+    "multi-agent-research-lab-ts",
+    "multi-agent-startup-team-ts"
+  ],
+  "provides": [
+    "scheduler:cron",
+    "scheduler:sweep"
+  ],
+  "requires": [
+    "secure:schedule"
+  ],
+  "defaults": {
+    "schedulerEnabled": true,
+    "schedulerStatePath": "/home/agent/scheduler/state.json",
+    "schedulerSweepIntervalMs": 60000
+  },
+  "files": [
+    {
+      "source": "files/lib/scheduler/index.ts",
+      "target": "lib/scheduler/index.ts"
+    },
+    {
+      "source": "files/lib/scheduler/cron-parse.ts",
+      "target": "lib/scheduler/cron-parse.ts"
+    },
+    {
+      "source": "files/lib/scheduler/sweep.ts",
+      "target": "lib/scheduler/sweep.ts"
+    },
+    {
+      "source": "files/lib/scheduler/types.ts",
+      "target": "lib/scheduler/types.ts"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/lib/scheduler/index.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/scheduler/cron-parse.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/scheduler/sweep.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/scheduler/types.ts"
+    }
+  ],
+  "contextHints": {
+    "extensionPoints": [
+      "src/lib/scheduler/"
+    ],
+    "commands": []
+  }
+}

package/registry/layers/agent-base/secure/files/lib/secure/README.md

@@ -0,0 +1,95 @@
+# `agent-base:secure`
+
+Security floor for every agent-runtime bundle. Composes `agent-base:tangle` and is included by every bundle in the catalog.
+
+## What you get for free
+
+By including `agent-base:secure` in your manifest's `includes[]`, your agent inherits:
+
+- **`secrets`** — dotenvx-backed encrypted secrets, loaded as `SecureString` (resists accidental leakage to logs)
+- **`workspace`** — sandboxed `/workspace/<agent-id>/` with path-traversal protection + sensitive-zone ACL
+- **`webhook-in`** — HMAC-signed inbound webhooks with replay-window + schema validation
+- **`webhook-out`** — HMAC-signed outbound posts with retry + circuit breaker + outbound URL whitelist
+- **`schedule`** — declarative scheduled triggers from `manifest.defaults.schedule[]`
+- **`identity`** — Ed25519 ephemeral signed identity (TTL ≤ 1h, auto-rotated)
+- **`audit`** — append-only signed audit log per agent
+
+## Usage from a bundle
+
+Bundles import via the `agent-base:secure` namespace; the layer composes the modules into `src/lib/secure/`.
+
+```ts
+import { secrets, workspace, schedule, defineWebhook, webhookOut } from '@/lib/secure'
+
+// Secret
+const apiKey = secrets.require('PHONY_API_KEY')
+await fetch('https://api.tangle.tools/...', {
+  headers: { authorization: `Bearer ${apiKey.unsafeReveal('phony API call')}` },
+})
+
+// Workspace
+workspace.write('drafts/draft-1.md', '# hello')
+const draft = workspace.read('drafts/draft-1.md')
+
+// Inbound webhook
+defineWebhook({
+  path: '/pt-session-ingest',
+  secretName: 'PT_INGEST_HMAC',
+  schema: (b) => (typeof (b as { patientId?: string }).patientId === 'string' ? null : 'patientId required'),
+  handler: async (body, ctx) => {
+    workspace.write(`sensitive/inbound/${(body as { patientId: string }).patientId}/${ctx.receivedAt}.json`, JSON.stringify(body))
+  },
+})
+
+// Outbound webhook
+const result = await webhookOut(
+  'https://doctor.tangle.tools/pt-session-ingest',
+  { patientId: 'p-123', notes: '...' },
+  { secretName: 'PT_INGEST_HMAC', allowedDomains: ['doctor.tangle.tools'] },
+)
+
+// Scheduled trigger (manifest declares the cron + capability)
+schedule.on('morning-summary', async () => {
+  // The runtime dispatches here when the cron fires
+})
+```
+
+## Manifest declarations the layer reads
+
+```json
+{
+  "includes": ["agent-base:tangle", "agent-base:secure", "agent-output:blocks"],
+  "defaults": {
+    "secrets":          ["PHONY_API_KEY", "PT_INGEST_HMAC"],
+    "outboundDomains":  ["api.tangle.tools", "doctor.tangle.tools"],
+    "schedule": [
+      { "id": "morning-summary", "cron": "0 8 * * *", "capability": "morning-summary" }
+    ],
+    "webhooks": {
+      "in": [{ "path": "/pt-session-ingest", "schema": "schemas/pt-session.json", "capability": "ingest-pt-session" }]
+    }
+  }
+}
+```
+
+## Operator responsibilities
+
+The layer is the floor — it is NOT the ceiling. The operator must:
+
+1. **Provision Ed25519 identity keypair** + populate `DOTENV_PRIVATE_KEY` for the runtime
+2. **Encrypt secrets** via `dotenvx encrypt .env --key <pubkey>` before checkin (never plaintext)
+3. **Configure gateway TLS + allowedDomains + quotas** — the layer trusts the gateway
+4. **Periodically export `/workspace/<agent-id>/.audit/`** to an off-host store for compliance retention
+5. **Verify the audit chain** post-export via `audit.verifyDay(date)`
+
+## Threat model + non-goals
+
+See `docs/specs/agent-base-secure.md` for the full threat model + the explicit list of attacks the layer does NOT defend against (compromised gateway, compromised host kernel, side-channel, malicious operator).
+
+## When you should NOT use this layer
+
+- A bundle that does not need any persistent state, secrets, scheduling, or external traffic. Rare.
+- A bundle that is the gateway/router itself (would create a circular trust assumption).
+- Test fixtures.
+
+For everything else, include it. The cost of inclusion is one line in `manifest.includes`. The cost of NOT including it is re-implementing security primitives 50 times.

package/registry/layers/agent-base/secure/files/lib/secure/audit.ts

@@ -0,0 +1,166 @@
+// audit — append-only signed audit log per agent. Each entry carries a
+// monotonic sequence + content-hash chained to the previous entry, so
+// tampering is detectable on export.
+//
+// Threat: an agent author writes code that "forgets" to log a secret
+// read. The audit module's API is the only documented way to log;
+// secrets/workspace/webhooks/identity all call audit.log() internally.
+// Bundles that bypass it are flagged by the secrets-declared validator
+// and operator review.
+
+import { createHash } from 'node:crypto'
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface AuditEntry {
+  /** Event type, dot-namespaced — secret.read, workspace.write, webhook.in, etc. */
+  event: string
+  /** What the event acted on — secret name, file path, webhook target. */
+  target?: string
+  /** Optional event-specific payload. Should NOT include raw secrets. */
+  payload?: Record<string, unknown>
+  /** Set automatically. */
+  ts?: string
+  /** Set automatically. */
+  seq?: number
+  /** Set automatically — sha256 of (prev.hash + this entry sans hash). */
+  hash?: string
+  /** Set automatically — actor agent id. */
+  actor?: string
+}
+
+// Read env at call time, not import time. Tests set AGENT_WORKSPACE_ROOT
+// per-test; production runtimes set it once at process start. Either way
+// the read happens when we actually need the path.
+function workspaceRoot(): string {
+  return process.env.AGENT_WORKSPACE_ROOT ?? '/workspace'
+}
+
+const AUDIT_DIR = '.audit'
+
+interface RotationState {
+  date: string
+  /** Workspace dir whose state this represents. Cache must invalidate when
+   * the dir changes — a different agent / different test fixture has its
+   * own chain. */
+  dir: string
+  seq: number
+  prevHash: string
+}
+
+let state: RotationState | null = null
+
+function dateStamp(): string {
+  return new Date().toISOString().slice(0, 10)
+}
+
+function loadState(_actor: string, dir: string, today: string): RotationState {
+  if (state && state.date === today && state.dir === dir) return state
+  const file = join(dir, `${today}.jsonl`)
+  if (existsSync(file)) {
+    const lines = readFileSync(file, 'utf8').trim().split('\n').filter(Boolean)
+    if (lines.length > 0) {
+      try {
+        const last = JSON.parse(lines[lines.length - 1]!) as AuditEntry
+        state = { date: today, dir, seq: (last.seq ?? 0) + 1, prevHash: last.hash ?? '' }
+        return state
+      } catch {
+        /* corrupt last line — start fresh but preserve file */
+      }
+    }
+  }
+  state = { date: today, dir, seq: 1, prevHash: '' }
+  return state
+}
+
+// Canonical-JSON serializer: sorts keys deterministically so the chain
+// hash is stable across V8 versions, structuredClone passes, and
+// runtime upgrades. Required for verifyDay() to be reliable across hosts.
+function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']'
+  const keys = Object.keys(value as Record<string, unknown>).sort()
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalize((value as Record<string, unknown>)[k])).join(',') + '}'
+}
+
+function hashEntry(entry: Omit<AuditEntry, 'hash'>, prevHash: string): string {
+  const canonical = canonicalize({ ...entry, prevHash })
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 32)
+}
+
+function loadActorAndDir(): { actor: string; dir: string } {
+  // Lazy-load identity to avoid import cycle (identity.ts imports audit).
+  // Fail-closed: missing identity is a hard error unless SF_DEV_IDENTITY_OPTIN=1.
+  // This closes M2 — silently attributing audit entries to 'dev-agent' in
+  // misconfigured prod was breaking attribution without anyone noticing.
+  const idEnv = process.env.TANGLE_AGENT_IDENTITY_JSON
+  let actor: string | undefined
+  if (idEnv) {
+    try {
+      actor = (JSON.parse(idEnv) as { agentId?: string }).agentId
+    } catch {
+      // Fall through; we'll throw below.
+    }
+  }
+  if (!actor) {
+    if (process.env.SF_DEV_IDENTITY_OPTIN === '1') {
+      actor = process.env.AGENT_NAME ?? 'dev-agent'
+    } else {
+      throw new Error(
+        'audit: cannot resolve actor — TANGLE_AGENT_IDENTITY_JSON missing or malformed and ' +
+          'SF_DEV_IDENTITY_OPTIN!=1. Audit attribution is non-negotiable; refuse to write a log line ' +
+          'we cannot attribute correctly.',
+      )
+    }
+  }
+  const dir = join(workspaceRoot(), actor, AUDIT_DIR)
+  mkdirSync(dir, { recursive: true })
+  return { actor, dir }
+}
+
+export const audit = {
+  log(input: Omit<AuditEntry, 'ts' | 'seq' | 'hash' | 'actor'>): void {
+    const { actor, dir } = loadActorAndDir()
+    const today = dateStamp()
+    const s = loadState(actor, dir, today)
+    const entry: AuditEntry = {
+      ts: new Date().toISOString(),
+      seq: s.seq,
+      actor,
+      ...input,
+    }
+    const hash = hashEntry(entry, s.prevHash)
+    entry.hash = hash
+    appendFileSync(join(dir, `${today}.jsonl`), JSON.stringify(entry) + '\n')
+    s.seq++
+    s.prevHash = hash
+  },
+
+  /** TEST-ONLY — reset internal rotation state so a new test fixture
+   * sees a fresh starting state. Production code MUST NOT call this; it
+   * would silently break chain continuity. */
+  _resetStateForTest(): void {
+    state = null
+  },
+
+  /** Verify chain integrity over a given day's log. Returns the first
+   * tampered entry's seq (or null if the chain is intact). */
+  verifyDay(date: string): { ok: boolean; tamperedAtSeq?: number } {
+    const { dir } = loadActorAndDir()
+    const file = join(dir, `${date}.jsonl`)
+    if (!existsSync(file)) return { ok: true }
+    const lines = readFileSync(file, 'utf8').trim().split('\n').filter(Boolean)
+    let prevHash = ''
+    for (const l of lines) {
+      const entry = JSON.parse(l) as AuditEntry
+      // Reconstruct exactly the shape log() hashed: take the entry, drop
+      // hash, hash the rest with prevHash. This matches the log path's
+      // spread semantics (undefined payload omitted, not explicit-undefined).
+      const { hash: storedHash, ...rest } = entry
+      const expected = hashEntry(rest, prevHash)
+      if (expected !== storedHash) return { ok: false, tamperedAtSeq: entry.seq }
+      prevHash = storedHash ?? ''
+    }
+    return { ok: true }
+  },
+}

package/registry/layers/agent-base/secure/files/lib/secure/identity.ts

@@ -0,0 +1,110 @@
+// identity — Ed25519 ephemeral signed identity for cross-agent calls.
+// TTL ≤ 1 hour, auto-rotated.
+//
+// Threat: agent A wants to call agent B claiming to be agent C. With
+// signed identity, A's call must include a valid signature from C's
+// private key. A doesn't have it, call fails. Agent B verifies via
+// the gateway's published pubkey directory.
+//
+// At runtime the agent receives its identity from the Tangle gateway
+// at session start (env: TANGLE_AGENT_IDENTITY_JSON). This module wraps
+// that handshake and exposes a typed surface.
+
+import { audit } from './audit.js'
+
+export interface AgentIdentity {
+  agentId: string
+  sessionId: string
+  deployerId: string
+  signedAt: number
+  expiresAt: number
+  capabilities?: string[]
+  publicKey: string
+  /** Signature is over { agentId, sessionId, signedAt, expiresAt, capabilities }. */
+  signature: string
+}
+
+let cached: AgentIdentity | null = null
+
+function fromEnv(): AgentIdentity {
+  const raw = process.env.TANGLE_AGENT_IDENTITY_JSON
+  if (raw) return JSON.parse(raw) as AgentIdentity
+
+  // Fail-closed: missing identity is a hard error in EVERY environment by
+  // default. Dev fallback requires explicit SF_DEV_IDENTITY_OPTIN=1 — that
+  // flag is the audit-trail of "yes, I deliberately ran without a real
+  // identity." This closes the H3 muffled-gate where misconfigured prod
+  // (forgot NODE_ENV=production) silently granted sensitive-fs.
+  if (process.env.SF_DEV_IDENTITY_OPTIN !== '1') {
+    throw new Error(
+      'TANGLE_AGENT_IDENTITY_JSON missing and SF_DEV_IDENTITY_OPTIN!=1 — ' +
+        'the gateway must inject a signed identity in any non-dev environment. ' +
+        'For local dev/test, set SF_DEV_IDENTITY_OPTIN=1 explicitly.',
+    )
+  }
+  // Explicit dev opt-in. Synthetic identity has NO sensitive-fs capability;
+  // tests that need it must set TANGLE_AGENT_IDENTITY_JSON to a synthetic
+  // envelope with the capability they need (which is itself an audit signal).
+  const now = Date.now()
+  return {
+    agentId: process.env.AGENT_NAME ?? 'dev-agent',
+    sessionId: `dev-${now}`,
+    deployerId: 'dev-deployer',
+    signedAt: now,
+    expiresAt: now + 3600_000,
+    capabilities: [],
+    publicKey: 'dev-pubkey',
+    signature: 'dev-signature',
+  }
+}
+
+function load(): AgentIdentity {
+  if (cached && cached.expiresAt > Date.now() + 60_000) return cached
+  const fresh = fromEnv()
+  if (fresh.expiresAt < Date.now()) {
+    throw new Error(`agent identity expired at ${new Date(fresh.expiresAt).toISOString()}`)
+  }
+  if (cached && cached.agentId !== fresh.agentId) {
+    audit.log({ event: 'identity.id-changed', payload: { previous: cached.agentId, current: fresh.agentId } })
+  } else if (!cached) {
+    audit.log({ event: 'identity.loaded', payload: { agentId: fresh.agentId, ttlSec: Math.floor((fresh.expiresAt - Date.now()) / 1000) } })
+  }
+  cached = fresh
+  return fresh
+}
+
+export const identity = {
+  current(): AgentIdentity {
+    return load()
+  },
+
+  /** Cryptographic verification of the identity envelope's signature
+   * against a deployer pubkey directory.
+   *
+   * NOT IMPLEMENTED. The pubkey directory + Ed25519 verify path is a
+   * separate piece of infrastructure (the Tangle gateway service)
+   * that does not yet exist as deployed code. Returning a stubbed
+   * boolean here would be worse than missing — callers would assume
+   * cryptographic verification happened when it did not.
+   *
+   * Throws so any caller that depends on real verification fails loud.
+   * When the gateway ships, replace this with the real Ed25519 path. */
+  verify(_envelope: AgentIdentity): boolean {
+    audit.log({ event: 'identity.verify-not-implemented' })
+    throw new Error(
+      'identity.verify() is not implemented — the Ed25519 deployer-pubkey ' +
+        'directory ships with the gateway service in a future release. ' +
+        'Do not call this method until that infrastructure is live; a stub ' +
+        'that returns true would silently pretend verification happened.',
+    )
+  },
+
+  /** Force a re-load on next .current() call. Use after operator notifies
+   * of a rotation event. */
+  invalidate(): void {
+    if (cached) {
+      audit.log({ event: 'identity.invalidate', payload: { agentId: cached.agentId } })
+      cached = null
+    }
+  },
+}