melchizedek-agents 0.16.2 → 0.18.0

package/db/migrations/0011_erase_expired.sql

@@ -0,0 +1,198 @@
+-- ============================================================================
+-- 0011_erase_expired.sql — a namespace erase reaches expired conversations
+-- ============================================================================
+-- melchizedek_erase_scope (0010) found a namespace's conversations through
+-- its live adk_sessions rows and erased ledger turns and A2A tasks only for
+-- those. Sessions expire after seven idle days (0001) while the ledger keeps
+-- turns indefinitely, so a namespace erase (the default for DELETE /memory)
+-- left every expired conversation's input, output and tool results behind
+-- and reported success.
+--
+-- Turns and tasks do not record the memory namespace, so a namespace erase
+-- now keeps only what provably belongs to ANOTHER namespace: rows whose
+-- conversation is still live there. Everything else of the scope goes,
+-- including conversations whose sessions have expired, whichever namespace
+-- they were in. Erasure errs toward deleting, never toward keeping (0002).
+-- An erase without a namespace is unchanged. Idempotent.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION melchizedek_erase_scope(
+  p_scope_key      text,
+  p_namespace      text    DEFAULT NULL,
+  p_include_nested boolean DEFAULT false
+) RETURNS TABLE(store text, deleted bigint)
+LANGUAGE plpgsql
+SECURITY INVOKER
+SET search_path = public
+AS $$
+DECLARE
+  -- LIKE pattern for scopes nested beneath this one, with the scope's own
+  -- wildcard characters escaped.
+  nested_like text := replace(replace(replace(p_scope_key, '\', '\\'), '%', '\%'), '_', '\_') || '/%';
+  contexts    text[];
+  kept        text[];
+  traces      text[];
+  n           bigint;
+BEGIN
+  IF p_scope_key IS NULL OR btrim(p_scope_key) = '' THEN
+    RAISE EXCEPTION 'melchizedek_erase_scope: scope_key is required';
+  END IF;
+
+  -- The conversations (context ids) being erased. With a namespace, they are
+  -- the namespace's own session rows; without one, every row of the scope.
+  -- adk_sessions.id is '<app_name>:<user_id>:<context id>'.
+  SELECT coalesce(array_agg(DISTINCT substr(s.id, length(s.app_name) + length(s.user_id) + 3)), '{}')
+    INTO contexts
+  FROM adk_sessions s
+  WHERE (s.user_id = p_scope_key OR (p_include_nested AND s.user_id LIKE nested_like))
+    AND (p_namespace IS NULL OR s.app_name = p_namespace);
+
+  -- With a namespace: the conversations still live in another namespace,
+  -- which are the only ones a namespace erase keeps. Sub-agent rows share
+  -- their conversation's id, so excluding `contexts` keeps them with it.
+  SELECT coalesce(array_agg(DISTINCT substr(s.id, length(s.app_name) + length(s.user_id) + 3)), '{}')
+    INTO kept
+  FROM adk_sessions s
+  WHERE p_namespace IS NOT NULL
+    AND (s.user_id = p_scope_key OR (p_include_nested AND s.user_id LIKE nested_like))
+    AND s.app_name <> p_namespace
+    AND NOT (substr(s.id, length(s.app_name) + length(s.user_id) + 3) = ANY(contexts));
+
+  -- Ledger traces of the turns being erased, collected before anything is deleted.
+  IF to_regclass('public.adk_turns') IS NOT NULL THEN
+    EXECUTE $q$
+      SELECT coalesce(array_agg(DISTINCT trace_id), '{}') FROM adk_turns
+      WHERE (user_id = $1 OR ($2 AND user_id LIKE $3))
+        AND ($4 IS NULL OR session_id IS NULL OR NOT (session_id = ANY($5)))
+    $q$ INTO traces USING p_scope_key, p_include_nested, nested_like, p_namespace, kept;
+  ELSE
+    traces := '{}';
+  END IF;
+
+  -- Memory facts. user_key is '<namespace>/<scope>' and a namespace never
+  -- contains '/', so the scope is exactly what follows the first slash.
+  DELETE FROM adk_memory_facts f
+  WHERE (p_namespace IS NULL OR split_part(f.user_key, '/', 1) = p_namespace)
+    AND (substr(f.user_key, strpos(f.user_key, '/') + 1) = p_scope_key
+         OR (p_include_nested AND substr(f.user_key, strpos(f.user_key, '/') + 1) LIKE nested_like));
+  GET DIAGNOSTICS n = ROW_COUNT;
+  store := 'memory_facts'; deleted := n; RETURN NEXT;
+
+  -- Sessions: every row of the scope in those conversations, whatever app
+  -- name ADK gave it (subagents run under their own agent name).
+  DELETE FROM adk_sessions s
+  WHERE (s.user_id = p_scope_key OR (p_include_nested AND s.user_id LIKE nested_like))
+    AND substr(s.id, length(s.app_name) + length(s.user_id) + 3) = ANY(contexts);
+  GET DIAGNOSTICS n = ROW_COUNT;
+  store := 'sessions'; deleted := n; RETURN NEXT;
+
+  -- The ledger, when installed.
+  IF to_regclass('public.adk_turns') IS NOT NULL THEN
+    EXECUTE $q$
+      DELETE FROM adk_turns
+      WHERE (user_id = $1 OR ($2 AND user_id LIKE $3))
+        AND ($4 IS NULL OR session_id IS NULL OR NOT (session_id = ANY($5)))
+    $q$ USING p_scope_key, p_include_nested, nested_like, p_namespace, kept;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'turns'; deleted := n; RETURN NEXT;
+
+  IF to_regclass('public.adk_telemetry') IS NOT NULL THEN
+    EXECUTE 'DELETE FROM adk_telemetry WHERE trace_id = ANY($1)' USING traces;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'spans'; deleted := n; RETURN NEXT;
+
+  IF to_regclass('public.adk_payloads') IS NOT NULL THEN
+    EXECUTE 'DELETE FROM adk_payloads WHERE trace_id = ANY($1)' USING traces;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'payloads'; deleted := n; RETURN NEXT;
+
+  IF to_regclass('public.adk_verdicts') IS NOT NULL THEN
+    EXECUTE 'DELETE FROM adk_verdicts WHERE trace_id = ANY($1)' USING traces;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'verdicts'; deleted := n; RETURN NEXT;
+
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = 'adk_labels' AND column_name = 'trace_id'
+  ) THEN
+    EXECUTE 'DELETE FROM adk_labels WHERE trace_id = ANY($1)' USING traces;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'labels'; deleted := n; RETURN NEXT;
+
+  IF to_regclass('public.adk_a2a_tasks') IS NOT NULL THEN
+    EXECUTE $q$
+      DELETE FROM adk_a2a_tasks
+      WHERE (owner = $1 OR ($2 AND owner LIKE $3))
+        AND ($4 IS NULL OR context_id IS NULL OR NOT (context_id = ANY($5)))
+    $q$ USING p_scope_key, p_include_nested, nested_like, p_namespace, kept;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'tasks'; deleted := n; RETURN NEXT;
+
+  -- Memory ingestion markers (migration 0007): how far each conversation was
+  -- distilled. They carry the scope's key and its conversation ids.
+  IF to_regclass('public.melchizedek_memory_ingest') IS NOT NULL THEN
+    EXECUTE $q$
+      DELETE FROM melchizedek_memory_ingest m
+      WHERE ($1 IS NULL OR split_part(m.user_key, '/', 1) = $1)
+        AND (substr(m.user_key, strpos(m.user_key, '/') + 1) = $2
+             OR ($3 AND substr(m.user_key, strpos(m.user_key, '/') + 1) LIKE $4))
+    $q$ USING p_namespace, p_scope_key, p_include_nested, nested_like;
+    GET DIAGNOSTICS n = ROW_COUNT;
+  ELSE
+    n := 0;
+  END IF;
+  store := 'memory_markers'; deleted := n; RETURN NEXT;
+
+  -- The task tools' list and job queue (migration 0009), per caller across
+  -- every syndicate: erased with the whole scope, kept by a namespace erase.
+  n := 0;
+  IF p_namespace IS NULL AND to_regclass('public.melchizedek_tasks') IS NOT NULL THEN
+    EXECUTE $q$
+      DELETE FROM melchizedek_tasks WHERE owner = $1 OR ($2 AND owner LIKE $3)
+    $q$ USING p_scope_key, p_include_nested, nested_like;
+    GET DIAGNOSTICS n = ROW_COUNT;
+    EXECUTE $q$
+      DELETE FROM melchizedek_task_owners WHERE owner = $1 OR ($2 AND owner LIKE $3)
+    $q$ USING p_scope_key, p_include_nested, nested_like;
+  END IF;
+  store := 'task_tools'; deleted := n; RETURN NEXT;
+END;
+$$;
+
+-- No API role may execute it (db/hardening.sql repeats this for every
+-- melchizedek function); the server's role gets it back.
+DO $$
+BEGIN
+  REVOKE ALL ON FUNCTION melchizedek_erase_scope(text, text, boolean) FROM PUBLIC;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'anon') THEN
+    REVOKE ALL ON FUNCTION melchizedek_erase_scope(text, text, boolean) FROM anon;
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated') THEN
+    REVOKE ALL ON FUNCTION melchizedek_erase_scope(text, text, boolean) FROM authenticated;
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+    GRANT EXECUTE ON FUNCTION melchizedek_erase_scope(text, text, boolean) TO service_role;
+  END IF;
+END $$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (11, '0011_erase_expired')
+ON CONFLICT (version) DO NOTHING;

package/db/migrations/0012_audit_log.sql

@@ -0,0 +1,98 @@
+-- ============================================================================
+-- 0012_audit_log.sql — an append-only record of who did what, when (ADR 0042)
+-- ============================================================================
+-- One row per security-relevant event: a failed authentication, a task's
+-- outcome, an erasure. The ledger (adk_turns) records what a turn said;
+-- this records who asked, how they authenticated, from where, and what
+-- happened, which is what an auditor asks for.
+--
+-- What a row holds: the event, its outcome, the caller's name and auth
+-- method, a SHA-256 prefix of the scope (never the scope key itself), the
+-- source address, the agent and task ids, and a small detail object. No
+-- conversation content, ever.
+--
+-- Append-only: a trigger refuses UPDATE and DELETE. Rows leave only
+-- through melchizedek_prune_audit(days), which removes rows older than the
+-- retention period (the source address is personal data; keep it no longer
+-- than the evidence needs). TRUNCATE is revoked from every API role. A
+-- database superuser can still alter the table; ship the rows to a log
+-- store you do not administer when the evidence must survive that.
+-- Idempotent.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS melchizedek_audit (
+  id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+  event       TEXT NOT NULL,          -- auth.failure | task.end | memory.erase
+  outcome     TEXT,                   -- denied | completed | failed | rejected | canceled | input-required | ok
+  caller      TEXT,                   -- the authenticated caller's name ('shared-secret', a caller token's name, 'jwt')
+  scope_hash  TEXT,                   -- SHA-256 prefix of the scope key; joins rows without naming a user
+  source_ip   TEXT,
+  agent_id    TEXT,
+  task_id     TEXT,
+  detail      JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+CREATE INDEX IF NOT EXISTS melchizedek_audit_at_idx ON melchizedek_audit (at);
+CREATE INDEX IF NOT EXISTS melchizedek_audit_event_idx ON melchizedek_audit (event, at);
+
+CREATE OR REPLACE FUNCTION melchizedek_audit_append_only()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path = public
+AS $$
+BEGIN
+  -- The retention function sets this for its own transaction only.
+  IF TG_OP = 'DELETE' AND coalesce(current_setting('melchizedek.audit_prune', true), '') = 'on' THEN
+    RETURN OLD;
+  END IF;
+  RAISE EXCEPTION 'melchizedek_audit is append-only (% refused); rows leave only through melchizedek_prune_audit', TG_OP;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS melchizedek_audit_append_only ON melchizedek_audit;
+CREATE TRIGGER melchizedek_audit_append_only
+  BEFORE UPDATE OR DELETE ON melchizedek_audit
+  FOR EACH ROW EXECUTE FUNCTION melchizedek_audit_append_only();
+
+-- Retention: delete rows older than p_days (at least 1). Returns the count.
+-- SECURITY DEFINER: the API role holds SELECT and INSERT only, so pruning
+-- runs with the owner's rights, through this function and nothing else.
+CREATE OR REPLACE FUNCTION melchizedek_prune_audit(p_days integer)
+RETURNS bigint
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE n bigint;
+BEGIN
+  IF p_days IS NULL OR p_days < 1 THEN
+    RAISE EXCEPTION 'melchizedek_prune_audit: p_days must be at least 1';
+  END IF;
+  PERFORM set_config('melchizedek.audit_prune', 'on', true);
+  DELETE FROM melchizedek_audit WHERE at < now() - make_interval(days => p_days);
+  GET DIAGNOSTICS n = ROW_COUNT;
+  PERFORM set_config('melchizedek.audit_prune', '', true);
+  RETURN n;
+END;
+$$;
+
+DO $$
+BEGIN
+  REVOKE ALL ON melchizedek_audit FROM PUBLIC;
+  REVOKE ALL ON FUNCTION melchizedek_prune_audit(integer) FROM PUBLIC;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'anon') THEN
+    REVOKE ALL ON melchizedek_audit FROM anon;
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated') THEN
+    REVOKE ALL ON melchizedek_audit FROM authenticated;
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'service_role') THEN
+    -- The server appends and reads; nothing else, so no UPDATE, DELETE or TRUNCATE.
+    GRANT SELECT, INSERT ON melchizedek_audit TO service_role;
+    GRANT EXECUTE ON FUNCTION melchizedek_prune_audit(integer) TO service_role;
+  END IF;
+END $$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (12, '0012_audit_log')
+ON CONFLICT (version) DO NOTHING;

package/dist/lib/a2a/app.d.ts

@@ -31,6 +31,10 @@ import type { BaseLlm, BaseMemoryService, BaseSessionService } from '@google/adk
 import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
 import type { ProviderEndpoint, ProviderId } from '../models/registry.ts';
 import type { TurnLock } from './turnLock.ts';
+import type { RlsHardeningStatus } from '../storage/rlsStatus.ts';
+import type { AuditSink } from '../observability/audit.ts';
+/** One end user's concurrent tasks, unless maxConcurrentPerScope says otherwise (ADR 0039). */
+export declare const DEFAULT_MAX_CONCURRENT_PER_SCOPE = 4;
 import type { EraseCounts } from '../memory/erase.ts';
 import type { Embedder, MemoryExtractor } from '../memory/providers.ts';
 import type { A2AContext } from './executor.ts';
@@ -68,6 +72,14 @@ export interface A2AAppOptions {
          * migrations this package ships (ADR 0021).
          */
         schemaVersion?: () => Promise<number | null>;
+        /**
+         * Whether db/hardening.sql is in force (postgresStorage supplies it).
+         * When given, the server checks it at boot like the supabase-js path:
+         * fatal with `requireHardenedDb`, a warning otherwise.
+         */
+        rlsHardening?: () => Promise<RlsHardeningStatus>;
+        /** Appends audit events (postgresStorage supplies one; ADR 0042). */
+        audit?: AuditSink;
         /**
          * One turn at a time per conversation across instances (postgresStorage
          * supplies an advisory lock). Default: a lock in this process.
@@ -155,6 +167,15 @@ export interface A2AAppOptions {
     streamText?: boolean;
     /** Concurrent tasks across all agents. 0 = unlimited. */
     maxConcurrentTasks?: number;
+    /**
+     * Where audit events go: failed authentications, task outcomes, erasures
+     * (ADR 0042). Default: the storage's sink when it has one, else none.
+     */
+    audit?: AuditSink;
+    /** Concurrent tasks for one scope (one end user). Default 4; 0 = unlimited. */
+    maxConcurrentPerScope?: number;
+    /** Concurrent tasks for one authenticated caller. Default 0 (unlimited). */
+    maxConcurrentPerCaller?: number;
     /** Task submissions (POST) per window per client IP. */
     rateLimit?: {
         windowMs: number;
@@ -225,6 +246,12 @@ export interface A2AApp {
     /** Stop admitting tasks, wait up to `graceMs` for running ones, cancel the rest.
      *  Resolves with the number of tasks that had to be canceled. */
     shutdown(graceMs: number): Promise<number>;
+    /**
+     * Fail `/readyz` from now on while still serving every request, so a load
+     * balancer stops routing here before the listener closes. The first step of
+     * a graceful stop; `shutdown()` is the last.
+     */
+    markUnready(): void;
 }
 /**
  * Build the agent card for one syndicate at one route prefix, in the A2A 1.0

package/dist/lib/a2a/app.js

@@ -36,8 +36,13 @@ import { providerForModel, resolveModel } from '../models/registry.js';
 import { createSupabaseServices, hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
 import { inProcessTurnLock } from './turnLock.js';
 import { compareSchema, schemaBehindMessage, shippedSchemaVersion } from '../storage/schemaVersion.js';
+import { scopeHashOf } from '../observability/audit.js';
+import { validTraceparent } from '../observability/tracer.js';
+/** One end user's concurrent tasks, unless maxConcurrentPerScope says otherwise (ADR 0039). */
+export const DEFAULT_MAX_CONCURRENT_PER_SCOPE = 4;
 import { eraseScope } from '../memory/erase.js';
 import { namespacedMemoryService } from '../memory/namespace.js';
+import { memoryCrossesProviders, memoryDestinations } from '../memory/providers.js';
 import { A2A_APP_NAME, SyndicateExecutor, TaskLimiter, deriveUserId, requestContextStorage, } from './executor.js';
 import { HEADER_VALUE_PATTERN, SCOPE_KEY_PATTERN } from './identity.js';
 import { createMetrics } from '../observability/metrics.js';
@@ -187,11 +192,13 @@ export async function createA2AApp(options) {
     let memoryService;
     let erase;
     let readSchemaVersion;
+    let checkHardening;
     if (options.storage) {
         durableSessions = options.storage.sessionService;
         memoryService = options.storage.memoryService;
         erase = options.storage.erase;
         readSchemaVersion = options.storage.schemaVersion;
+        checkHardening = options.storage.rlsHardening;
     }
     else if (hasSupabaseCredentials()) {
         // ADR 0021 item 6: the supabase-js path stays for a transition period.
@@ -209,7 +216,11 @@ export async function createA2AApp(options) {
         memoryService = services.memoryService;
         erase = (scopeKey, eraseOpts) => eraseScope(services.rpcClient, scopeKey, eraseOpts);
         readSchemaVersion = services.schemaVersion;
-        const rls = await services.checkRlsHardening();
+        checkHardening = services.checkRlsHardening;
+    }
+    // Both storage paths: refuse a public deployment whose tables an API key can read.
+    if (checkHardening) {
+        const rls = await checkHardening();
         if (rls.applied) {
             log(`✓ DB hardening verified — ${rls.detail}.`);
         }
@@ -280,6 +291,22 @@ export async function createA2AApp(options) {
      * and only `long-term` syndicates get the memory service.
      */
     const internalSessions = new InMemorySessionService();
+    // Long-term memory sends transcripts to its extraction and embedding
+    // providers; say so once per syndicate when they are not the agents' own.
+    const memoryFlowWarned = new Set();
+    const warnMemoryFlow = (cfg) => {
+        if (memoryFlowWarned.has(cfg.syndicate_name))
+            return;
+        memoryFlowWarned.add(cfg.syndicate_name);
+        const dest = memoryDestinations(process.env, { extractor: options.memory?.extractor, embedder: options.memory?.embedder });
+        const models = [cfg.orchestrator?.model, ...(cfg.subagents ?? []).map((s) => s.model)];
+        const crossed = memoryCrossesProviders(models, dest);
+        if (crossed.length) {
+            warn(`'${cfg.syndicate_name}' keeps long-term memory, so its transcripts also go to ${crossed.join(' and ')} `
+                + `(extraction: ${dest.extraction}, embeddings: ${dest.embeddings}), which its agents do not use. `
+                + 'Set MEMORY_EXTRACTION_MODEL and MEMORY_EMBEDDING_PROVIDER to keep memory on an approved provider.');
+        }
+    };
     const servicesFor = (cfg) => {
         const mode = cfg.memory_system;
         const sessionService = mode === 'internal-only' || !durableSessions ? internalSessions : durableSessions;
@@ -287,6 +314,8 @@ export async function createA2AApp(options) {
         // turn reaches — including AgentTool children, which run under their own
         // ADK app name — recalls and stores in the root syndicate's memory.
         const memory = mode === 'long-term' && memoryService ? namespacedMemoryService(memoryService, memoryAppName(cfg)) : undefined;
+        if (memory)
+            warnMemoryFlow(cfg);
         if (mode === 'long-term' && !memoryService) {
             warn(`'${cfg.syndicate_name}' requests long-term memory but Supabase is not configured — memory disabled.`);
         }
@@ -295,7 +324,11 @@ export async function createA2AApp(options) {
         }
         return { sessionService, memoryService: memory, durable: sessionService !== internalSessions };
     };
-    const limiter = new TaskLimiter(options.maxConcurrentTasks ?? 0);
+    const audit = options.audit ?? options.storage?.audit;
+    const limiter = new TaskLimiter(options.maxConcurrentTasks ?? 0, {
+        perScope: options.maxConcurrentPerScope ?? DEFAULT_MAX_CONCURRENT_PER_SCOPE,
+        perCaller: options.maxConcurrentPerCaller ?? 0,
+    });
     const metrics = options.metricsToken ? createMetrics() : undefined;
     const onTaskEnd = (record) => {
         metrics?.observeTask(record);
@@ -357,6 +390,7 @@ export async function createA2AApp(options) {
             agentId,
             policy: options.policy,
             onTaskEnd,
+            onAudit: audit,
             log,
             warn,
         });
@@ -409,11 +443,60 @@ export async function createA2AApp(options) {
             res.type('text/plain; version=0.0.4').send(metrics.render(limiter.inFlight));
         });
     }
-    app.get('/readyz', (_req, res) => {
-        if (limiter.isDraining) {
+    // Readiness: not while stopping, and not while durable storage is
+    // unreachable (a turn there would fail). The reason is logged once per
+    // change of state, never per probe, and the answer names no host.
+    let unready = false;
+    let storageDown = false;
+    // /readyz is unauthenticated, so the database is asked at most once per
+    // READY_CACHE_MS however often it is probed; concurrent probes share the
+    // one check in flight.
+    const READY_CACHE_MS = 2_000;
+    let lastCheck;
+    let checking;
+    const checkStorage = async () => {
+        let timer;
+        try {
+            await Promise.race([
+                readSchemaVersion(),
+                new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('no answer within 2 s')), 2_000); }),
+            ]);
+            if (storageDown)
+                log('readyz: the database answers again.');
+            storageDown = false;
+            return true;
+        }
+        catch (err) {
+            if (!storageDown)
+                warn(`readyz: the database is unreachable (${err instanceof Error ? err.message : String(err)}); reporting not ready.`);
+            storageDown = true;
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const storageReachable = async () => {
+        if (!readSchemaVersion)
+            return true;
+        if (lastCheck && Date.now() - lastCheck.at < READY_CACHE_MS)
+            return lastCheck.ok;
+        checking ??= checkStorage().then((ok) => {
+            lastCheck = { at: Date.now(), ok };
+            checking = undefined;
+            return ok;
+        });
+        return checking;
+    };
+    app.get('/readyz', async (_req, res) => {
+        if (unready || limiter.isDraining) {
             res.status(503).json({ status: 'draining' });
             return;
         }
+        if (!(await storageReachable())) {
+            res.status(503).json({ status: 'unavailable', reason: 'storage' });
+            return;
+        }
         res.json({ status: 'ready', sessions: sessionBackend, inFlight: limiter.inFlight });
     });
     // ── 2–3. Authentication ───────────────────────────────────────────────────
@@ -431,6 +514,12 @@ export async function createA2AApp(options) {
     }));
     const rejectAuth = (req, res, error) => {
         warn(`401 ${req.method} ${req.path} from ${req.ip}: ${error}`);
+        try {
+            audit?.({ event: 'auth.failure', outcome: 'denied', sourceIp: req.ip, detail: { method: req.method, path: req.path, reason: error } });
+        }
+        catch {
+            /* the refusal stands whatever the sink does */
+        }
         res.status(401).json({ error });
     };
     if (options.serverSecret) {
@@ -538,6 +627,7 @@ export async function createA2AApp(options) {
                 caller: identity.caller,
                 ownsNested: identity.ownsNested ?? false,
                 operator: identity.operator ?? false,
+                sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
             }, () => next());
             return;
         }
@@ -562,7 +652,7 @@ export async function createA2AApp(options) {
             // The caller's key funds its provider, and its hash prefixes the scope
             // so no key holder can reach another's data.
             const scopeKey = deriveUserId({ apiKey, siteUserId });
-            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret }, () => next());
+            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret, sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent) }, () => next());
             return;
         }
         // Server mode: the server's credentials pay; X-API-Key is not used.
@@ -579,6 +669,7 @@ export async function createA2AApp(options) {
             // Everyone holding the secret is one caller; without a secret (loopback) the caller is local.
             caller: options.serverSecret ? 'shared-secret' : 'local',
             operator: !!options.serverSecret,
+            sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
         }, () => next());
     });
     // ── 6. Task rate limit ────────────────────────────────────────────────────
@@ -634,11 +725,13 @@ export async function createA2AApp(options) {
                 includeNested: !!ctx.ownsNested,
             });
             log(`Erasure for scope ${ctx.scopeKey}${all ? ' (all namespaces)' : ''}: ${JSON.stringify(counts)}`);
+            audit?.({ event: 'memory.erase', outcome: 'ok', caller: ctx.caller, scopeHash: scopeHashOf(ctx.scopeKey), sourceIp: ctx.sourceIp, detail: { allNamespaces: all, deleted: counts } });
             res.json({ deleted: counts });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             warn(`Erasure failed: ${msg}`);
+            audit?.({ event: 'memory.erase', outcome: 'failed', caller: ctx.caller, scopeHash: scopeHashOf(ctx.scopeKey), sourceIp: ctx.sourceIp, detail: { allNamespaces: all } });
             res.status(503).json({ error: msg });
         }
     });
@@ -739,6 +832,9 @@ export async function createA2AApp(options) {
         app,
         config,
         sessionBackend,
+        markUnready: () => {
+            unready = true;
+        },
         shutdown: async (graceMs) => {
             const left = await limiter.drain(graceMs);
             for (const t of leaseTimers)

package/dist/lib/a2a/executor.d.ts

@@ -18,6 +18,7 @@ import type { TurnLock } from './turnLock.ts';
 import type { PendingApproval } from '../runtime/approvals.ts';
 import type { MessagePart, SyndicateTurnResult } from '../runtime/syndicateTurn.ts';
 import type { TaskRecord } from '../observability/metrics.ts';
+import type { AuditSink } from '../observability/audit.ts';
 import type { Policy } from './policy.ts';
 /** Per-request caller context, set by the server's identity middleware. */
 export interface A2AContext {
@@ -44,6 +45,10 @@ export interface A2AContext {
      *  server secret), as opposed to an end user (a JWT, a gateway header).
      *  Operator-only adopter routes check it. */
     operator?: boolean;
+    /** The request's source address (behind A2A_TRUST_PROXY), for the audit trail only. */
+    sourceIp?: string;
+    /** The caller's W3C traceparent, when well formed: the turn's root span links to it. */
+    traceparent?: string;
 }
 export interface SurfaceContext {
     name: string;
@@ -103,6 +108,8 @@ export interface ExecutorOptions {
     policy?: Policy;
     /** One record per task, however it ended: the task log and metrics. */
     onTaskEnd?: (record: TaskRecord) => void;
+    /** Receives one `task.end` audit event per task (ADR 0042). */
+    onAudit?: AuditSink;
     /**
      * Stream the answer as the model writes it, as `answer` artifact chunks
      * (see answerStream). Off by default; never for a syndicate with guards.
@@ -115,16 +122,39 @@ export interface ExecutorOptions {
     log: (message: string) => void;
     warn: (message: string) => void;
 }
-/** Concurrency cap and in-flight registry shared by all executors. */
+/** Per-key caps beside the global one: 0 or absent means no cap. */
+export interface TaskLimits {
+    /** Concurrent tasks for one scope (one end user's data). */
+    perScope?: number;
+    /** Concurrent tasks for one authenticated caller (a backend, a token). */
+    perCaller?: number;
+}
+/** Concurrency caps and in-flight registry shared by all executors. */
 export declare class TaskLimiter {
     readonly max: number;
+    readonly perScope: number;
+    readonly perCaller: number;
     private readonly running;
+    /** taskId → the keys it counts against, so release frees exactly those. */
+    private readonly keysOf;
+    private readonly counts;
     private draining;
     private idleWaiters;
-    constructor(max: number);
+    constructor(max: number, limits?: TaskLimits);
+    /**
+     * Why a task for this scope and caller may not start now, or undefined.
+     * Checked before acquire() so the refusal can name the cap that was hit.
+     */
+    refusal(who?: {
+        scopeKey?: string;
+        caller?: string;
+    }): string | undefined;
     get inFlight(): number;
-    /** Reserve a slot. Returns undefined when saturated or shutting down. */
-    acquire(taskId: string): AbortController | undefined;
+    /** Reserve a slot. Returns undefined when any cap is reached or the server is shutting down. */
+    acquire(taskId: string, who?: {
+        scopeKey?: string;
+        caller?: string;
+    }): AbortController | undefined;
     release(taskId: string): void;
     cancel(taskId: string): boolean;
     /** Stop admitting tasks; resolve when all running ones finish or `graceMs` passes,