melchizedek-agents 0.17.0 → 0.18.0

package/.env.example

@@ -129,6 +129,8 @@ A2A_SERVER_SECRET=
 # Used when compiling the AgentCard that advertises this agent to A2A clients.
 # Defaults to http://localhost:4000 if not set.
 # Only needed for cloud deployments where the server has a real public URL.
+# With it set, the server also refuses to start until A2A_AUTH,
+# A2A_SERVED_AGENTS and A2A_TRUST_PROXY are set explicitly (ADR 0039).
 PUBLIC_URL=
 
 # ── A2A server: identity and billing (all optional; ADR 0017, 0025) ─────────
@@ -141,6 +143,7 @@ PUBLIC_URL=
 #   jwt     a JWT from your identity provider; the scope comes from its claims.
 #   header  an authenticating gateway in front sets the user header; requires
 #           A2A_SERVER_SECRET, which only the gateway holds.
+# Required with PUBLIC_URL; prefer callers or jwt there.
 # A2A_AUTH=secret
 # callers: `name:sha256[:scope]` entries separated by ';'. The config holds only
 # each token's SHA-256. Mint one: npx melchizedek-serve --new-caller <name>
@@ -171,8 +174,8 @@ PUBLIC_URL=
 # The server refuses a database behind the migrations it ships (run
 # `npx melchizedek-db apply`); this starts it anyway.
 # ALLOW_SCHEMA_MISMATCH=false
-# Only these agent ids are served at /<agentId>/... (comma list). Unset = any
-# syndicate the loader can find.
+# Only these agent ids are served at /<agentId>/... (comma list). Unset, or *,
+# = any syndicate the loader can find. Required with PUBLIC_URL (* allowed).
 # A2A_SERVED_AGENTS=support_triage,research_brief
 # Per-task wall-clock budget (ms; 0 = none). Default 15 minutes.
 # A2A_TASK_TIMEOUT_MS=900000
@@ -191,11 +194,23 @@ PUBLIC_URL=
 # A2A_RATE_LIMIT_MAX=60
 # A2A_RATE_LIMIT_WINDOW_MS=900000
 # A2A_AUTH_FAILURE_MAX=30
-# Express trust-proxy: proxy hop count, true/false, or a subnet list. Default 1.
+# Express trust-proxy: proxy hop count, true/false, or a subnet list. Default
+# false (no proxy is trusted). Required with PUBLIC_URL: 1 behind one load
+# balancer, false when clients connect directly.
 # A2A_TRUST_PROXY=1
+# Concurrent tasks for one end user (scope), and for one caller. 0 = unlimited.
+# A2A_MAX_CONCURRENT_PER_SCOPE=4
+# A2A_MAX_CONCURRENT_PER_CALLER=0
+
+# OpenAPI tools: the exact environment variables an `auth:` may name. Unset, any
+# variable but the framework's own settings (this file's) is allowed.
+# OPENAPI_CREDENTIAL_ENVS=WEATHER_API_KEY,CRM_TOKEN
 # A2A_BODY_LIMIT=1mb
 # How long SIGTERM waits for running tasks before canceling them.
 # A2A_SHUTDOWN_GRACE_MS=25000
+# Of that, how long /readyz fails while requests are still served, so a load
+# balancer deregisters this instance before the listener closes.
+# A2A_SHUTDOWN_DELAY_MS=5000
 # Daily budgets per UTC day (ADR 0026), per caller and per scope (one end
 # user), on tasks, model calls and tokens. A task over budget ends `rejected`
 # with the reason. Counted in Postgres/Supabase (db/migrations/0004) when
@@ -279,6 +294,11 @@ WIKI_AGENT_MODEL=
 # retried with jittered backoff, honouring Retry-After up to 60 s, before any
 # output is produced. Total attempts per model call; 1 turns retries off.
 # MODEL_RETRY_MAX_ATTEMPTS=3
+# For agents with a fallback_model: after this many consecutive provider-side
+# failures a provider's circuit opens and those agents answer from their
+# fallback for the cooldown. 0 disables the breaker.
+# MODEL_BREAKER_THRESHOLD=5
+# MODEL_BREAKER_COOLDOWN_MS=30000
 # Per-attempt timeout for xAI (Grok) calls, ms; floor 120000.
 # XAI_TIMEOUT_MS=600000
 

package/AGENT_SETUP.md

@@ -193,7 +193,8 @@ user id.
 
 Deploying the server itself (Heroku, Fly, a VPS) needs `PUBLIC_URL` set
 — at which point the server refuses to start without the bearer secret,
-by design. Run `db/hardening.sql` before real user data arrives, and
+and until `A2A_AUTH`, `A2A_SERVED_AGENTS` and `A2A_TRUST_PROXY` are set
+explicitly, by design. Run `db/hardening.sql` before real user data arrives, and
 read the deployment notes in `lib/memory/README.md` end to end. The
 patient in module 2.02's specimen would expect no less of you.
 

package/CHANGELOG.md

@@ -4,6 +4,110 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 the starter pack and the templates), not the repo's full history.
 
+## 0.18.0 — 2026-10-06
+
+### Breaking — read before upgrading
+
+- **A public server states its posture (ADR 0039).** With `PUBLIC_URL` set,
+  the server refuses to start until all three are set explicitly; the boot
+  message names each one missing:
+  - `A2A_AUTH`: `callers` or `jwt` (recommended), `header`, or `secret`
+    (one shared secret: any holder can act as any user via `X-User-Id`).
+  - `A2A_SERVED_AGENTS`: the agent ids to serve, or `*` for every agent.
+  - `A2A_TRUST_PROXY`: proxies in front (`1` behind one load balancer), or
+    `false` when clients connect directly.
+- **`A2A_TRUST_PROXY` defaults to `false`** (was 1): a server reached
+  directly no longer takes the client's `X-Forwarded-For` as its address.
+- **A turn stops at 50 model calls** when the YAML sets no `max_steps`
+  (`DEFAULT_MAX_STEPS`). A syndicate that needs more sets `max_steps`.
+- **One end user runs at most 4 tasks at once** (`A2A_MAX_CONCURRENT_PER_SCOPE`,
+  `maxConcurrentPerScope`; 0 = unlimited). `A2A_MAX_CONCURRENT_PER_CALLER`
+  adds a per-caller cap, off by default. The refusal names the cap.
+
+- **The `@google/adk` peer range is `~2.2.0`** (was `^2.2.0`): the tested
+  minor. A new ADK minor can bring a second `@google/genai` copy, whose
+  response shapes the framework pins; the range widens when a release is
+  tested against it. ADK 2.2.0 is the latest published, so no install
+  changes today.
+
+- **An OpenAPI `auth` may not name one of the framework's own settings**
+  (the database URL, a provider key, an `A2A_` secret: anything under the
+  framework's prefixes). The YAML chooses the host too, so this was a way
+  to send a secret anywhere. `OPENAPI_CREDENTIAL_ENVS` makes the rule an
+  exact allowlist. ADR 0041.
+- **MCP tool descriptions are cut at 1,000 characters and results at
+  20,000**, each marked where it was cut.
+
+### Changes
+
+- **An append-only audit trail** (`melchizedek_audit`, migration
+  `0012_audit_log`; ADR 0042). Every failed authentication, task outcome
+  and erasure is recorded with the caller, the source address, the agent
+  and task ids and a scope hash, and no content. A trigger refuses UPDATE
+  and DELETE; `melchizedek_prune_audit(days)` is the retention path.
+  `postgresStorage` supplies the sink (`audit`), and `createA2AApp` takes
+  an `audit` option for any other. Run `npx melchizedek-db apply`.
+- **The server says where memory sends transcripts.** Long-term memory's
+  extraction and embedding providers default to Gemini whatever the agents
+  run on; a syndicate whose agents use other providers now gets one boot
+  warning naming the providers memory reaches and the variables that move
+  it (`memoryDestinations`, `memoryCrossesProviders`). DOCUMENTATION gains
+  "Where your data goes": every destination, its retention, and the setting
+  that changes it.
+- **A request can be followed across systems.** Every task record
+  (`onTaskEnd`, and the JSON log line) carries `taskId` and `traceId`; the
+  trace id is the one the spans and the ledger row carry. A request with a
+  W3C `traceparent` header is linked from the turn's root span
+  (`caller.trace_id`, and `callerTraceId` on the record); the turn keeps
+  its own trace id. `validTraceparent` and `callerSpanContext` are exported
+  from `melchizedek-agents/observability/tracer`. ADR 0043.
+- **`fallback_model:`, an agent key, and a per-provider circuit breaker.**
+  When an agent's model fails provider-side (5xx, 429, a reset, after its
+  retries) before producing output, its `fallback_model` answers; after
+  `MODEL_BREAKER_THRESHOLD` consecutive failures (default 5) the provider
+  is skipped for `MODEL_BREAKER_COOLDOWN_MS` (30 s) by agents that have a
+  fallback. A 4xx, a canceled turn and a half-finished stream are never
+  redirected. ADR 0044.
+- **`mcp_tools:`, an agent key**: the MCP server's tools the agent may use;
+  any other tool the server lists is not exposed. On a dispatch route,
+  `require_approval` may name a listed MCP tool, so a write waits for a
+  person. `closeMcpConnections()` closes every open MCP connection.
+- **`melchizedek-db apply` is one transaction under an advisory lock.** The
+  whole install (migrations, hardening, telemetry) runs as one psql
+  `--single-transaction` script that takes `pg_advisory_xact_lock` first: a
+  failure anywhere rolls everything back, and two applies started together
+  run one after the other. The output still names each file.
+- `TaskLimiter` takes per-scope and per-caller limits and says which one
+  refused (`refusal()`); `createA2AApp` takes `maxConcurrentPerScope` and
+  `maxConcurrentPerCaller`; `DEFAULT_MAX_CONCURRENT_PER_SCOPE` is exported
+  from `melchizedek-agents/a2a` and `DEFAULT_MAX_STEPS` from
+  `melchizedek-agents/config`.
+
+## 0.17.1 — 2026-10-06
+
+- **Fix: a rolling deploy no longer refuses requests.** On SIGTERM the
+  server closed its listener at once, while the load balancer was still
+  sending it traffic. It now fails `/readyz` first and keeps serving for
+  `A2A_SHUTDOWN_DELAY_MS` (default 5 s), then closes and drains. The delay
+  counts inside `A2A_SHUTDOWN_GRACE_MS`, so a stop takes no longer than
+  before. `A2AApp.markUnready()` does the same for an embedding app.
+  ADR 0038.
+- **`/readyz` fails while durable storage does not answer** (503,
+  `reason: 'storage'`), so an instance that lost its database leaves the
+  rotation instead of failing turns. The cause is logged once per outage;
+  the answer is cached for 2 s and concurrent probes share one read, so the
+  unauthenticated route cannot be used to flood the database.
+- **Fix: the MCP client no longer follows redirects past the SSRF guard.**
+  The SSE transport used the default fetch, which follows redirects; it now
+  uses `mcpFetch`, under the rule 0.17.0 gave OpenAPI tools: same-origin hops
+  get the server's check, cross-origin hops the full guard and no
+  credential header.
+- **Fix: a failed MCP connect closes its transport.** The SSE stream's
+  reconnect timer kept running after `createMcpTools` gave up, for the life
+  of the process.
+- **`MELCHIZEDEK_DOTENV=off`** makes every bin ignore `.env` files and run
+  on its environment alone.
+
 ## 0.17.0 — 2026-10-06
 
 ### Read before upgrading

package/DOCUMENTATION.md

@@ -110,6 +110,8 @@ Field reference:
 | `a2a_agent_url` | subagent | A REMOTE agent over A2A (§6): the orchestrator delegates to it with one `request` argument; in plan-dispatch it can be a route. No `model`/`instruction` — the remote agent has its own. Credentials come from `A2A_AGENT_TOKENS`, never YAML. |
 | `max_steps` | root | Cap on model calls per turn, counted across every agent the turn reaches (orchestrator, subagents, nested syndicates). Exceeding it fails the turn with `STEP_LIMIT`. |
 | `includeContents` / `outputKey` / `globalInstruction` / `disallowTransferToParent` / `disallowTransferToPeers` | agent | Passed through to ADK's LlmAgent. `includeContents: none` makes an agent see only the current message. |
+| `fallback_model` | any agent | A model, ideally on another provider, that answers when this agent's model fails provider-side (5xx, 429, a connection reset, after its own retries) before producing any output, or while that provider's circuit is open: after `MODEL_BREAKER_THRESHOLD` consecutive provider failures (default 5; 0 disables) the provider is skipped for `MODEL_BREAKER_COOLDOWN_MS` (default 30 s). A 4xx and a canceled turn are never redirected, and a stream that already produced text is never replayed elsewhere ([ADR 0044](./wiki/decisions/0044-fallback-model-and-circuit-breaker.md)). |
+| `mcp_tools` | subagent | The MCP server's tools this agent may use; any other tool the server lists is not exposed. On a dispatch route `require_approval` may name them ([ADR 0041](./wiki/decisions/0041-tool-vendors-get-least-privilege.md)). |
 | `mcp_server_url` | subagent | Discover this subagent's tools from a remote MCP server at load time (§3). SSRF-guarded; `ALLOW_PRIVATE_MCP=true` permits localhost for development. |
 | `openapi` | any agent | HTTP APIs as tools, each from an OpenAPI 3 spec file (§3, OpenAPI tools): `spec`, and optionally `operations` (default: the GET operations only), `auth` (from environment variables), `base_url`, `prefix`. |
 | `code_execution` | any Gemini agent | `"gemini"`: the model writes Python and Gemini runs it in Google's server-side sandbox, returning the output to the model; nothing runs on this host. For arithmetic, data and checks a model gets wrong in its head. Gemini models only ([ADR 0033](./wiki/decisions/0033-context-task-code.md)). |
@@ -180,7 +182,11 @@ writes is exposed only by naming it, and a named operation can be listed
 under `require_approval` (as written under `operations`) so a person
 approves each call. `auth` names an environment variable, never a value
 (`bearer_env`, or `api_key` with `in: header | query` and `name`); an unset
-variable fails the compile, and a static token is applied to the request,
+variable fails the compile, and so does one of the framework's own settings
+(the database URL, a provider key, an `A2A_` secret: anything `.env.example`
+documents), since the YAML chooses the host it goes to.
+`OPENAPI_CREDENTIAL_ENVS`, when set, is the exact list of variables an `auth`
+may name. A refused or unset variable fails the compile, and a static token is applied to the request,
 never stored in session state. Every server must be http(s) and pass the
 SSRF guard: its literal rules when the agent compiles, the full check with
 DNS before each call; `ALLOW_PRIVATE_OPENAPI=true` permits private hosts for
@@ -223,7 +229,11 @@ npx melchizedek-db status    # schema version, hardening, session counts
 
 That runs the migrations in [`db/migrations/`](./db/migrations/) and then
 [`db/hardening.sql`](./db/hardening.sql). Both are idempotent, so re-running
-them is also the upgrade path from any earlier layout.
+them is also the upgrade path from any earlier layout. `apply` runs the whole
+install as one transaction under an advisory lock: if any statement fails,
+nothing is changed, and two applies started together run one after the other.
+Rolling back a migration that succeeded is a restore from backup (§6), since
+the migrations only move forward.
 
 The tables go in the `public` schema by default. To keep them out of reach of
 a REST layer (Supabase exposes `public`), install into a private schema and
@@ -545,9 +555,28 @@ or pass your own `resolveRequest`.
   The counts live in the `melchizedek_usage` table (`db/migrations/0004_usage.sql`)
   when Postgres or Supabase is configured, else in process memory. A store
   that cannot be read refuses the task.
-- **One record per task** (option `onTaskEnd`): agent, caller, a hash of the
-  scope, status, reason, duration, model calls and tokens.
+- **One record per task** (option `onTaskEnd`): task id, trace id, agent,
+  caller, a hash of the scope, status, reason, duration, model calls and
+  tokens. The trace id is the one the turn's spans and its ledger row carry,
+  and the audit trail's `task.end` row names both ids, so one id joins the
+  log, the ledger, the audit trail and your tracing backend. A request
+  carrying a W3C `traceparent` header is linked, not joined: the turn's root
+  span links to the caller's span and records `caller.trace_id`, and the
+  record carries `callerTraceId`. The turn keeps a trace id of its own, since
+  ledger attribution and erasure key on it and a caller must not choose it.
   `A2A_LOG_FORMAT=json` prints every server line as JSON, this record included.
+- **The audit trail** (`melchizedek_audit`, `db/migrations/0012_audit_log.sql`;
+  option `audit`, supplied by `postgresStorage`): one row per failed
+  authentication (`auth.failure`), task outcome (`task.end`) and erasure
+  (`memory.erase`), with the caller's name, the source address, the agent and
+  task ids, and a hash of the scope. Never a scope key and never conversation
+  content. A trigger refuses UPDATE and DELETE; rows leave only through
+  `SELECT melchizedek_prune_audit(<days>)`, which you schedule (pg_cron, or a
+  job) for the retention your evidence needs, since the source address is
+  personal data. A failed write is logged once and each event is printed to
+  stderr as JSON until writes recover. A database owner can still alter the
+  table; ship the rows to a store you do not administer when the evidence must
+  survive that.
 - **Rate limit**: with an authenticator it counts per caller (an operator's
   backend) or per scope (an end user); under the shared secret, per IP.
 - **The telemetry ledger is redacted before it is written**:
@@ -556,6 +585,30 @@ or pass your own `resolveRequest`.
   `setTelemetryRedactor(fn)`. Sessions and memory are not redacted; use
   `DELETE /memory` there.
 
+#### Where your data goes
+
+What a deployment sends where, how long it is kept, and the setting that
+changes it. "Your Postgres" is the database `DATABASE_URL` (or Supabase)
+names; nothing is kept by the framework anywhere else.
+
+| Data | Goes to | Kept | Change it with |
+|---|---|---|---|
+| The prompt: the user's message, the conversation, tool results | The model provider of each agent that runs (the model-id prefix) | The provider's policy | The `model:` lines in the YAML; `ollama/` ids stay on your machine |
+| Tool calls (`web_search`, `web_extract`, OpenAPI, MCP) | The tool's own host | That host's policy | The agent's `tools:`, `openapi:`, `mcp_server_url` / `mcp_tools` |
+| Sessions (conversation history) | Your Postgres, `adk_sessions` | 7 days after the last message | `ttlDays` (`postgresStorage`) |
+| Long-term memory facts | Your Postgres, `adk_memory_facts`; **the transcript is also sent to the extraction and embedding providers, Gemini by default whatever the agents run on** (the server warns at boot when they differ) | Until erased, or `memory_retention_days` | `MEMORY_EXTRACTION_MODEL`, `MEMORY_EMBEDDING_PROVIDER`, `memory_retention_days` |
+| The ledger: each turn's input, output and tool results (key-shaped secrets redacted) | Your Postgres, `adk_turns`, `adk_telemetry` | **Until you prune it**: schedule `melchizedek_prune_telemetry(<days>)` | `TELEMETRY_REDACT`, the prune's `turn_days` |
+| Sampled full model requests | Your Postgres, `adk_payloads` | 30 days | `TELEMETRY_PAYLOADS`, `TELEMETRY_PAYLOAD_TTL_DAYS` |
+| Traces, when `OTEL_EXPORTER_OTLP_ENDPOINT` is set | Your OTLP collector, conversation content included with key-shaped secrets redacted (`off` drops it) | Your collector's policy | `OTEL_EXPORT_CONTENT` (`redacted`, `off`, `raw`) |
+| The audit trail (no content) | Your Postgres, `melchizedek_audit` | Until `melchizedek_prune_audit(<days>)` | The prune schedule |
+| The task record (no content) | stdout | Your log platform's policy | `A2A_LOG_FORMAT` |
+
+`DELETE /memory` erases a user from every Postgres store above except the
+audit trail, which holds no content, only a hash of the scope. It does not
+reach a provider's own retention: read each provider's data terms, and the
+business associate or data processing agreement you need with it, before
+sending it regulated data.
+
 #### Who pays
 
 `A2A_KEY_MODE` (option `keyMode`), whatever the authenticator:
@@ -687,9 +740,13 @@ subagent or a workflow node listing it is a load error. In code,
 | `A2A_AUTH_FAILURE_MAX` failed logins per IP per 15 min, then blocked | 30 |
 | `A2A_TASK_TIMEOUT_MS` per task | 15 min |
 | `A2A_MAX_CONCURRENT_TASKS` | unlimited |
-| `max_steps` (YAML): model calls per turn, subagents included | none |
+| `A2A_MAX_CONCURRENT_PER_SCOPE`: tasks at once for one end user | 4 |
+| `A2A_MAX_CONCURRENT_PER_CALLER`: tasks at once for one caller | unlimited |
+| `max_steps` (YAML): model calls per turn, subagents included | 50 |
+| `A2A_TRUST_PROXY`: proxies in front (required with `PUBLIC_URL`) | none trusted |
 | `A2A_BODY_LIMIT` | 1 MB |
 | `A2A_SHUTDOWN_GRACE_MS`: SIGTERM waits for running tasks | 25 s |
+| `A2A_SHUTDOWN_DELAY_MS`: of that, `/readyz` fails while requests are still served | 5 s |
 
 The rate limit and the failed-login limit count in the process by default,
 so each replica keeps its own window. With `A2A_REDIS_URL` set (and the
@@ -719,7 +776,11 @@ Without `A2A_SERVER_SECRET` the server binds `127.0.0.1` only; binding
 another `HOST` requires the secret or `ALLOW_UNAUTHENTICATED=true`. With
 `PUBLIC_URL` set it refuses to start without the secret, with the
 `.env.example` placeholder as the secret, or against an unhardened
-database (unless `ALLOW_UNHARDENED_DB=true`). With durable storage it reads
+database (unless `ALLOW_UNHARDENED_DB=true`), and until the deployment
+states its posture: `A2A_AUTH` (prefer `callers` or `jwt`; `secret` lets any
+holder of the secret act as any user), `A2A_SERVED_AGENTS` (a list, or `*`
+for every agent) and `A2A_TRUST_PROXY` (the number of proxies in front, or
+`false`). The refusal names each one missing. With durable storage it reads
 `melchizedek_schema_version` and refuses to start on a database behind the
 migrations it ships, naming `melchizedek-db apply` (or
 `ALLOW_SCHEMA_MISMATCH=true` to start anyway); a database ahead of it only
@@ -745,9 +806,14 @@ local conversation keeps talking to the same remote conversation.
 `Dockerfile` builds the compiled server and runs it as a non-root user with
 a health check; `compose.yaml` adds optional Ollama and Phoenix (traces).
 `npx melchizedek-db print|apply|status` installs and checks the database.
-Set `PUBLIC_URL`, `A2A_SERVER_SECRET` and the provider keys from your
-secret manager; give the orchestrator's stop timeout at least
-`A2A_SHUTDOWN_GRACE_MS`.
+Set `PUBLIC_URL`, `A2A_SERVER_SECRET`, `A2A_AUTH`, `A2A_SERVED_AGENTS`,
+`A2A_TRUST_PROXY` and the provider keys from your secret manager; give the orchestrator's stop timeout at least
+`A2A_SHUTDOWN_GRACE_MS`. On SIGTERM the server first fails `/readyz` and
+keeps serving for `A2A_SHUTDOWN_DELAY_MS` so the load balancer deregisters
+it, then closes the listener and drains running tasks for the rest of the
+grace period; point the readiness probe at `/readyz`, which also fails while
+durable storage does not answer. `MELCHIZEDEK_DOTENV=off` makes every bin
+ignore `.env` files and run on its environment alone.
 
 #### Backups
 

package/config/agents/syndicateSchema.yaml

@@ -185,6 +185,12 @@ orchestrator:
   # Subagents inherit this if not set on their own config.
   model: "gemini-3.5-flash-lite"
 
+  # [optional] A model that answers when `model` fails provider-side (5xx,
+  # 429, a connection reset) before producing anything, or while that
+  # provider's circuit is open (MODEL_BREAKER_THRESHOLD, ADR 0044). Put it
+  # on another provider. A 4xx is never redirected.
+  # fallback_model: "claude-haiku-4-5"
+
   # [required] The agent's system prompt / persona.
   # Maps to: instruction
   instruction: |
@@ -414,6 +420,13 @@ subagents:
     # See config/agents/librarian.yaml for the worked example.
     # mcp_server_url: "http://localhost:8931/sse"
 
+    # [optional] The MCP server's tools this agent may use, by name. Any
+    # other tool the server lists is not exposed (a server's list is its
+    # own to change). Without it, every listed tool is. On a dispatch
+    # route, require_approval may name these (ADR 0041). Descriptions are
+    # cut at 1,000 characters and results at 20,000.
+    # mcp_tools: [wiki_search, wiki_read]
+
     # [optional] Agent Skills for this subagent; same block as on the
     # orchestrator. `scripts: "local"` is allowed here only under
     # `dispatch:` (a delegated subagent cannot pause the turn, ADR 0028).

package/db/hardening.sql

@@ -51,7 +51,7 @@ DO $$
 DECLARE t text;
 BEGIN
   FOREACH t IN ARRAY ARRAY['adk_telemetry', 'adk_turns', 'adk_payloads', 'adk_verdicts', 'adk_labels',
-                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage'] LOOP
+                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit'] LOOP
     IF to_regclass('public.' || t) IS NOT NULL THEN
       EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', t);
       EXECUTE format('REVOKE ALL ON %I FROM anon, authenticated', t);
@@ -133,7 +133,7 @@ BEGIN
                         'melchizedek_registry_versions_immutable', 'melchizedek_registry_publish',
                         'melchizedek_registry_activate', 'melchizedek_memory_commit',
                         'melchizedek_memory_dimensions', 'melchizedek_prune_memory_ingest',
-                        'melchizedek_prune_memory')
+                        'melchizedek_prune_memory', 'melchizedek_prune_audit')
   LOOP
     EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC, anon, authenticated', fn);
     IF has_service_role THEN
@@ -160,7 +160,8 @@ AS $$
                       'adk_turns', 'adk_payloads', 'adk_verdicts', 'adk_labels',
                       'adk_agent_registry', 'adk_agent_registry_versions',
                       'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage',
-                      'melchizedek_memory_ingest', 'melchizedek_tasks', 'melchizedek_task_owners');
+                      'melchizedek_memory_ingest', 'melchizedek_tasks', 'melchizedek_task_owners',
+                      'melchizedek_audit');
 $$;
 
 REVOKE ALL ON FUNCTION melchizedek_rls_status() FROM PUBLIC, anon, authenticated;

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

@@ -32,6 +32,9 @@ 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';
@@ -75,6 +78,8 @@ export interface A2AAppOptions {
          * 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.
@@ -162,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;
@@ -232,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