feat(mcp): SaaS tenant-identity spine — authenticated tenant, no header override, default-deny#66
Open
Basheirkh wants to merge 83 commits into
Open
feat(mcp): SaaS tenant-identity spine — authenticated tenant, no header override, default-deny#66Basheirkh wants to merge 83 commits into
Basheirkh wants to merge 83 commits into
Conversation
…er override, default-deny Phase 1 of multi-tenant SaaS (PLAN-saas-multitenant): close the isolation hole where the tenant came from a FREE x-nil-workspace header (anyone could read any workspace). resolve_tenant gains a saas mode: the tenant is the AUTHENTICATED identity via an injected claim_resolver (verified JWT workspace claim); the workspace header may NOT override it; a BYO adapter-url is rejected (identity routes to the tenant's registered active adapter); a missing claim is default-deny. Header-trust remains only for self-hosted/dev (multi_tenant without saas). build_remote_app/TenantToolsProvider thread saas + claim_resolver (env NIL_MCP_SAAS); SaaS FAILS CLOSED without a claim_resolver — it can never silently fall back to header-trust. Isolation conformance tests: tenant A and B route to different adapters; a header naming B under an A token is refused; BYO adapter-url refused; missing claim default-denied; unknown workspace has no adapter. 25 mcp/tenant tests green. Remaining (follow-up): wire the production claim_resolver = keycloak JWKS JWT verifier; then tenant-scope the newer surfaces (intent router providers, export, automation, Hermes) + per-tenant quotas (Phases 2-3), and the encrypted per-tenant secret vault.
…quotas Builds on the identity spine (#66). Three self-contained, TDD'd kernel keystones for tenant management: - SecretVault (nilscript/secrets/vault.py): per-tenant secrets (adapter creds + LLM key) encrypted at rest (Fernet); read BY TENANT only; storage-agnostic (injectable store); wrong key can't decrypt; tenants isolated. This is "save your secrets once" done securely. - JWT claim verifier (nilscript/mcp/auth.py): the production claim_resolver for SaaS mode — verifies the bearer JWT (sig/exp/iss/aud) and reads the workspace claim; forged/expired/missing → None → default-deny. Completes the spine's prod wiring (keycloak JWKS layers on top). - Per-tenant quotas + rate limit (nilscript/governance_quota.py): token-bucket + daily volume caps per (tenant, kind); a noisy tenant is throttled without starving others (the 429 fairness lesson). Pure, injected clock, resume-safe. 32 tests green (vault roundtrip/encryption/isolation/wrong-key; JWT verify/forge/expiry/no-claim; rate-limit fairness; quota caps).
…ault
Onboarding for SaaS: a company is stood up in a single privileged call.
- store: tenant_secrets table + put/get/delete_secrets using the SecretVault (encrypted at rest,
Fernet, NIL_VAULT_KEY); vault disabled (fail-closed) when no key. Secrets keyed by workspace.
- app: POST /tenants/provision (workspace + secrets + adapter → store secrets encrypted, register +
activate adapter); GET /tenants/{ws}/secret/{name} (registry-token-gated server-to-server fetch of a
tenant's decrypted secret for the platform — never the browser, never logged).
Tests: one-call provision activates the adapter + stores secrets; secret read is token-gated; secrets
are ciphertext at rest (no plaintext key on disk); tenants isolated; auth + workspace required. 164
cp/registry/tenant/saas tests green.
…oped durable layer Closes the remaining SaaS items (kernel side): - JWKS claim resolver (mcp/auth.py): production keycloak path — PyJWKClient fetches + caches signing keys, selects by kid (rotation-safe); fail-closed on any verify error. jwt_claim_resolver_from_env precedence: NIL_JWT_JWKS_URL > NIL_JWT_PUBLIC_KEY > NIL_JWT_HS_SECRET. - Surface tenant-scoping: store.recent(workspace=) and store.pending(workspace=) (pending joins to its events' workspace, since approvals carries none); /api/events and /api/pending take ?workspace=. Conformance: tenant A's events/pending never include B's; operator view (no ws) sees all. - Tenant-scoped durable layer (durable.py, Temporal-ready): tenant-prefixed deterministic workflow ids (idempotent + no cross-tenant collision), per-tenant Temporal namespace, TenantDurablePolicy (per-tenant rate + concurrency admission — the 429 fairness, durable edition). Worker integration is the separate Temporal build; this is the isolation layer it plugs into. 42 SaaS tests green (JWKS verify/forge, durable id/namespace isolation + per-tenant throttle, events/ pending workspace scoping); 161 across cp/registry/tenant/mcp.
…layer (Phase 6) durable_temporal.py (optional — temporalio imported lazily): heavy/bulk governed writes run as DURABLE workflows, tenant-isolated and crash-safe: - per-tenant Temporal namespace + deterministic tenant-scoped workflow id (idempotent, no cross-tenant collision); - the NIL gate runs in an activity with a RetryPolicy → a throttled (429)/transient backend is retried durably, not dropped (the 429 fairness lesson, durable edition); - register_executor injects the NIL propose→commit (real SDK in prod, a fake in tests); - run_worker starts a worker on the tenant's namespace + task queue. Verified END-TO-END with temporalio's in-process time-skipping server (no external infra): a backend throttled twice is retried and commits on attempt 3; workflow id is tenant-scoped + idempotent. pyproject: [saas] (pyjwt[crypto] + cryptography) and [temporal] (temporalio) extras, wired into [dev]. 148 durable/saas/tenant/cp/mcp tests green.
De-Salla'd Evolution API client (EvolutionClient) + deterministic per-tenant naming + error/QR/state extractors + config-from-env. 34 tests passing.
The canonical protocol object. Cycle embeds today's kernel Node union as its Flow (execution AST reused verbatim) and adds intent/roles/policies/resources/outcomes. compile_cycle lowers Cycle -> WosoolProgram IR and runs the UNCHANGED V1-V6 validator (governance invariant preserved); an undeclared verb is refused through the lowering (V4). cycle_content_hash locks the version over the AST, not the derived IR. policies.raises_tier=HIGH escalates a node to a human-approval gate (floor only rises). 14 tests; full suite 527 green — governed core untouched.
…egisters THROUGH the kernel) draft_cycle/register_cycle persist a drawn cycle the same way an automation is stored: compile (lower -> V1-V6 -> AST content-hash) then append to the automations SSOT with kind='cycle' and the canonical Cycle AST in a new nullable source column (lowered WosoolProgram stays in plan, derived). Runs reuse fire_manual unchanged - no second executor. Control-plane gains POST /cycles/draft, POST /cycles/register (pending_approval, never auto-armed, idempotent on hash), GET /cycles. 11 new tests; full suite 538 green - store schema change backward-compatible.
…teps over a hidden IR The Cycle is now the canonical protocol with its OWN richer step model, not an embed of the execution IR: NAMED position-independent steps (CreateLead, not step_1), named outputs + variable bindings, role-bound context actors, first-class approval nodes, decisions, tags. compile_cycle LOWERS named steps -> step_N and named-output/variable refs (lead.id, payload.name) -> $.step_N.output / $.input data references, then runs the UNCHANGED V1-V6 validator; WosoolProgram stays the hidden IR (governed core byte-for-byte intact). Approval steps ARE the gates. CompileResult exposes step_ids (name->IR id) for other projections. Worked SalesLeadLifecycle from the .nil mockup. 16 protocol tests; full suite 540 green. (Deferred: parallel/foreach/wait/call steps, imports, contracts, metrics, Protocol Registry — YAGNI for v0.2.)
…hases 4-5) Three projections over the frozen Cycle AST v0.2, all pure, no new deps: - nil_printer/nil_parser: the .nil text surface. print_nil (canonical) + parse_nil (hand-written tokenizer + recursive descent, NilSyntaxError with line/col). Provable BOTH ways: parse_nil(print_nil(ast))==ast and print_nil(parse_nil(text))==text. Bilingual bijection. - registry.ProtocolRegistry: the symbol layer (steps/variables/outputs/context/roles/policies/ outcomes + verb catalog) -> resolve (go-to-def), references (find-refs), completions, dead_references. Reuses compile.py's literal-vs-reference discipline. - projections/: to_mermaid, to_markdown, simulate (happy-path dry-run, propose-only), governance_report (gates/approvals/reversibility-from-compensate). Kernel suite 590 green.
cycle/lsp.py: diagnostics (parse + V1-V6, IR step_N reverse-mapped to protocol names for
line-accurate errors, + dead-references), context-aware completions (verbs after use, step names
after next/->, entities after approver:), hover, semantic_tokens. Pure, total (never raises).
CP: POST /cycles/{parse,print,lsp/diagnostics,lsp/completions,lsp/hover,lsp/semantic-tokens,
projections}. 12 LSP tests; kernel suite 602 green.
…ace column
The approvals table had NO workspace column; per-tenant /pending was faked by JOINing each hold to
its proposed event by proposal_id — a join that broke (proposal_ids in the ledger never matched the
approvals rows), so the owner's Decisions screen showed nothing while holds piled up globally.
Root fix: a held proposal now CARRIES its own workspace, recorded by the gate at hold-time
(mcp/tools.py -> /proposals/{id}/await -> store.await_approval(workspace=...)). store.pending(ws)
filters on that column DIRECTLY; the fragile events-join remains only as a legacy fallback for
pre-migration rows. Idempotent ALTER + best-effort backfill on boot. 602 tests green.
…isite mechanism - control-plane: approvals carry resolved+modifiable; approve-with-edits re-proposes the amended args before commit (commit still executes exactly what was previewed) - mcp gate: thread resolved+modifiable to the control plane at hold-time - demo: pocketbase adapter gains the intent-contract + prerequisite gate (nil.* reads, flat resource.create, curated to_native delegation, tier inheritance, reference-existence refusal at propose) - demo: point Odoo shim at the renamed odoo_nil_adapter package - deploy: controlplane Dockerfile
…tion, materialize-on-commit
Control plane + store:
- register_planned_step: a dependent step whose handoff ref cannot resolve until
its prerequisite commits is registered PLANNED (idempotent synthetic id), not
proposed — it appears as a blocked card, never as an executable proposal
- record_committed + next_planned_steps + promote_planned_step: on a
prerequisite's commit, resolve $.steps[N].result handoffs to the real backend
id and materialize the dependents as HELD approvals ('propose only after the
prerequisite commit')
- _shape_pending: expose resolved/modifiable JSON for the editable card and the
computed plan blocked flag; cancel_plan rejects every un-decided step so
rejecting any step leaves no orphans
MCP:
- nil_plan wiring for the planned/blocked lifecycle (+ tests)
Adapter (pocketbase reference):
- universal noun→declared-target resolution (concept synonyms, singular/plural,
substring) — an agent naming 'res.partner'/'customer' resolves to whatever
THIS backend declares; no per-backend hardcode, portable to every adapter
617 tests green.
…cribe
/nil/v0.1/describe gains verb_details[] — {verb, type, tier, reversibility,
doctype, entity_type, required_args, references} — the adapter's own authority
statement, sourced from its WriteVerb table + COMPENSATIONS (omission =
IRREVERSIBLE, the honest default). Optional in NIL 0.1: a non-declaring adapter
yields [] and consumers must treat its verbs as metadata-unknown (fail closed),
never guess tier/type from verb names.
- sdk/connect.handshake: passes verb_details through the connection report
- controlplane /api/adapter-skeleton: exposes verb_details alongside verbs
- demo pocketbase adapter: declares all curated + generic verbs
- tests: describe/handshake coverage (4 new)
621 tests green.
…riven resume
Invariant: a run that stops at a gate is PARKED, never lost. Before this, a
HIGH-tier commit the System held came back as a 'parked' node output and the
walk continued past it on a phantom result, and an undecided await_approval
degraded to a poll-budget 'timeout' — both in-memory-only, neither resumable.
- kernel/executor: a held commit or an undecided approval raises an internal
_Park; execute() returns RunResult.waiting {kind, node, proposal, ...} with
the context at park time. execute(resume={context, node_id, output}) binds
the output as the parked node's output and continues via the node's OWN
next_after routing — no resume-only control flow.
- controlplane/store: new parked_runs table {run_id, node_id, kind, pinned
automation version, proposal_id, deadline, context}. settle_park() claims
waiting→settled so a re-delivered decision/event can never resume twice.
- automation/dispatch: _classify maps waiting→waiting_approval/waiting_event;
_record persists the park row alongside finish_run. resume_parked_run
reloads the PINNED plan and re-runs with resume=...; resume_on_decision
routes approve→continuation with the commit result bound, reject→rejected
(or the await_approval node's own on_rejected branch).
- controlplane/app: POST /proposals/{id}/decision — the same path that runs
_execute_approved/_materialize_dependents — now resumes every run parked on
that proposal; /automations/tick sweeps due deadlines (on_timeout routes).
Decision recorded: parked-run rows live in the control-plane store (the SSOT
for approvals); the kernel executor stays stateless between steps — resume is
a fresh executor over a persisted context, so restarts lose nothing. Parks
inside parallel branches are documented as unsupported (gather swallows the
signal).
Tests: executor park/resume, approve→completed with committed result in the
run record, reject→rejected with reason, restart survival over the same DB
file, double-decision idempotency, await_approval branch routing, deadline
sweep. 621→630 green.
…waits
Invariant: a process can WAIT for the world (a supplier's mail, a payment
webhook) as a first-class, governed step — parked as a row, resumed by the
same ledger dispatch that fires event triggers, never an in-memory sleep.
Dialect seam (cycle/0.2 stays FROZEN, additive only):
- Cycle.nil accepts "cycle/0.2" | "cycle/0.3"; the new step is only valid in
0.3 and 0.3 means exactly "uses wait_for_event" (two-way model rule). The
dialect is therefore content-determined, which lets the .nil parser INFER
it with no surface version marker while parse(print(ast)) == ast stays an
exact bijection.
- Grammar (parser+printer, exact inverse):
step AwaitReply { wait_for_event { on_event: "mail.received";
match { order_ref: $po }; timeout_seconds: 604800 -> route Escalate }
next Parse }
The timeout and its route print on ONE line — a deadline with nowhere to
go is unrepresentable. $name match values are explicit references to
variables/named outputs; bare literals stay literals (match is equality).
- Registry / projections / LSP: edges (next + on_timeout), $ref dead-ref
scan, hover detail, simulate happy path, mermaid event/timeout edges,
docs sentence, step keyword.
IR + runtime:
- kernel/models: WaitForEventNode (own node — NOT the clock-sleep `wait`):
on_event, shallow match (values may be data refs), positive timeout (V1),
REQUIRED on_timeout route; V2 covers dangling next/on_timeout; V6 sees
match references. compile lowers the step, resolving $po into $.input.po.
- executor: walking the node PARKS the run (kind=event) with the match
RESOLVED against the run context at park time; next_after routes a
matched-event resume to `next` (payload bound as the step's output) and a
{timed_out} resume to on_timeout.
- scheduler: dispatch_event — the same path that fires event triggers — now
resumes matching waiting parks (event-name equality + shallow field
equality, workspace-scoped); resume_due_waits sweeps passed deadlines on
the /automations/tick clock.
Tests: exact round-trip (incl. the bare-$po authoring form), 0.2/0.3
dialect refusals, lowering + $ref resolution, V1/V2 refusals (bad timeout,
missing/dangling route), park then match then resume with payload bound,
deadline timeout route, restart survival over the same DB file, workspace
scoping. 630 to 646 green.
…lock (M1a) Invariants enforced: the printer DEFINES canonical form and parse(print(ast)) == ast is exact (round-trip suite); content_hash is SHA-256 over canonical JSON so identical capabilities hash identically regardless of authoring key order (the registry's version lock, I4); invalid shapes refuse with structured NilSyntaxError(message, line, col) — never a bare traceback; archetype is an OPTIONAL closed-enum tag so a wrapped v0 capability can omit it instead of guessing semantics (I2); implemented_by requires a "default" implementation structurally. Spec deviation (codebase idiom wins): models are frozen pydantic DslModel (extra=forbid) like cycle/models.py, not stdlib dataclasses; content_hash lives beside the model (hash.py) as cycle/hash.py does, not as a model field.
…medness (M1b) Invariants enforced: only the five forms Auto|Approve|Seq|Quorum| Conditional are representable — par/weighted/dynamic/delegate/override are grammar-reserved and PARSE-REFUSE with V9_UNSUPPORTED_FORM (a named governance answer carrying line/col, not a generic syntax error); parse(print(ast)) == ast is exact for every form; V9 rules are pure functions returning the kernel's structured ValidationResult (refusals as answers, never exceptions): V9_SELF_APPROVAL (an approve unit missing distinct_from:[preparer] under sod.preparer_not_approver, I6), V9_QUORUM_UNSATISFIABLE (k > |of|), V9_QUORUM_DISTINCT (distinct demanded but unresolvable), V9_TIMEOUT_NO_ROUTE (a deadline with no escalate/ reject route), V9_AUTO_FORBIDDEN (auto() when capability risk > MEDIUM, I3). Each rule tested in both directions. Spec note: timeout.then is Optional in the MODEL (not required as the cycle idiom would suggest) precisely so 'every timeout has a route' can surface as a V9 finding at the offending unit rather than a parse crash; Conditional branches are non-conditional nodes, so nested conditionals are structurally unrepresentable in MVP.
… (M2a)
Invariants enforced: content_hash is the lock — registering the same
hash is an idempotent no-op (no new version), a new hash SUPERSEDES the
prior version (superseded_by + state=deprecated) and never edits in
place; every read is workspace-pinned and fails closed (no workspace ->
400 on list, 404 cross-tenant, refused write); lifecycle is the closed
set draft -> published -> deprecated and publish is an auth-gated act;
strategy registration is V9-gated — an ill-formed strategy (e.g.
V9_QUORUM_UNSATISFIABLE) is refused with structured diagnostics and
never stored, mirroring 'a failing plan is never stored'.
One generic versioned-registry engine backs both tables so the
disciplines cannot drift. Endpoints follow the existing FastAPI idioms:
_registry_authed bearer gating, {ok, definition} envelopes, structured
{error|refusal} refusals. Both AST-object and .nil-text intake are
accepted (the text surface is the SSOT convention).
…cles (M2b)
Invariants enforced: wrap_cycle is PURE and deterministic (no timestamps,
no randomness), so re-wrapping an unchanged cycle yields the same
content-hash and the registry no-ops — no duplicate version; risk =
max over the cycle's step verbs using DECLARED adapter metadata only
(verb_details), an undeclared verb or garbage tier counts as HIGH and
an unreachable adapter floors everything at HIGH (fail closed, never a
name-substring guess); exposure is {ai:false} — flipping it stays a
deliberate governed act; archetype is OMITTED, not defaulted — no tag
beats a wrong tag; the generated strategy seq(approve(role: owner)) is
registered alongside its capability so the strategy ref never dangles,
and it is V9-clean by construction.
Endpoint: POST /capabilities/wrap {workspace, cycle_id} — auth-gated,
workspace-pinned (cross-tenant wrap is a 404). Spec deviation: the
'nilscript wrap-cycle' CLI is deferred — the registry lives behind the
control plane, so the endpoint is the honest surface (spec allows
endpoint and/or CLI).
…ture-slot rows (M3a) One subject, N signature slots (strategy_signatures): Auto records a policy:<id> decision row and refuses above MEDIUM at runtime (not just V9 bind time); Approve holds one addressed slot whose timeout is a row deadline the tick sweep enforces (escalate re-addresses a fresh slot, reject rejects the whole subject); Seq materializes item N+1 only on item N's approval and a rejection anywhere cancels the rest; Quorum(k, distinct) commits only at k signatures from distinct actors (and distinct declared identities); Conditional routes via the kernel's OWN guard evaluator over $.input.* (no second evaluator). SoD: the preparer can never sign their own subject and distinct_from violations refuse — both SOD_VIOLATION, refusals not exceptions. rehold() voids collected signatures (superseded, audit row kept) and re-holds fresh slots for material edits. Deliberate deviation from the plan's 'reuse planned_steps': Seq carries the dependent-plan grammar (planned -> pending stepwise, cancel-the-rest) on the signatures table itself, because a strategy unit approves the SAME subject — there is no verb/args to re-propose, so planned_steps rows would be dishonest. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…+ endpoints (M3b)
prepare(workspace, capability, inputs, prepared_by) -> one persisted subject, card assembled BY
CODE ONLY (I5): pinned registry record (id/semver/registry version/content-hash), inputs
validated against the typed contract (missing/typed-wrong/unknown -> structured refusal listing
fields), modifiable = the NOT-required inputs (required slots locked), strategy state from the
B3 interpreter (units/signed/pending/two-key), affected systems from the default implementing
cycle's step-verb namespaces x adapter registry labels, risk = the capability floor,
reversibility/coverage from declared compensation, prepared_by stamped for SoD. Card body is
BYTE-deterministic — timestamps, prepared ids and signature rows live in the envelope, never
the hashed body (canonical sort_keys serialization + sha256 card_hash).
Endpoints: POST /prepared (prepare, no effect), GET /prepared/{id} (workspace-pinned card,
fail closed), POST /prepared/{id}/sign (the strategy-aware decision surface: SOD_VIOLATION
403s, approve-with-edits inside modifiable voids collected signatures and re-holds, full
approval fires the commit), POST /prepared/{id}/execute (auto/complete + retry; NOT_APPROVED
refuses with the pending units). The commit is the ONLY effect path: fire_manual on the default
implementing cycle, idempotency key prep:<id>, seeded inputs bound as $.input (fire_manual and
the live runner gained an optional input kwarg). /automations/tick now also sweeps strategy
unit deadlines: escalate re-addresses a fresh slot, reject rejects the prepared subject.
Deviation noted: risk/reversibility come from the REGISTRY record only (the wrap already baked
declared verb metadata into the capability floor, fail closed); live adapter tiers do not leak
into the card, keeping it deterministic on registry state alone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Closes the two C4 live-mode gaps the hub integration surfaced: - GET /prepared?workspace=&status= — the Decisions feed: the workspace's Permission Card envelopes newest-first, workspace-pinned fail closed (no workspace → 400; foreign workspace → empty), optional status filter - rejection reason persisted on the prepared row (idempotent ALTER migration for existing DBs, same pattern as prior columns) and surfaced in the card envelope — a rejected card now says why 762 tests green (2 new).
…ding refuses drift (M4)
A3: `cycle X implements IssueInvoice@2.3 triggers … { }` — additive on the ONE v0.3 seam.
Decision: any v0.3-only construct (wait_for_event step OR implements clause) forces the
cycle/0.3 dialect, content-determined in BOTH directions, so the .nil parser still infers the
dialect with no surface marker and parse(print(ast)) == ast stays an exact bijection.
cycle/0.2 stays frozen and loadable; cycle_content_hash drops a None `implements` so every
pre-implements cycle keeps its version lock byte-identical.
A4-V7 (capability/conformance.py, pure, V1-V6 ValidationResult shape so the hub renders
refusals unchanged):
V7_UNKNOWN_CAPABILITY registry target missing, or a different id/contract version
resolved (fail closed - conformance against the wrong contract
proves nothing)
V7_INPUT_UNPRODUCIBLE a REQUIRED capability input has no name in the cycle's
trigger-match/context/variables namespace
V7_OUTPUT_UNBOUND a declared output no step's `output` ever binds
V7_FLOOR_WEAKENED floor-only-rises (I3), interpretation documented in the module:
NOT max(step tiers) >= risk as an equation - when the floor is
HIGH/CRITICAL the cycle must present a gate at/above it: an
approval step, a DECLARED verb tier >= floor (undeclared = HIGH,
fail closed, same rule as wrap_cycle - honest because the runtime
gate parks undeclared commits), or a policy raising a step there.
Refusal lands at the offending step (node), like V1-V6.
V7_COMPENSATION_MISSING capability promises compensation but a write step has no
`compensate` and no checkpoint boundary exists (B5-ready seam)
Control plane: /cycles/register runs V7 when the AST carries `implements` - registry lookup
workspace-pinned, refusal stores nothing; /cycles/draft stays the V7-free preview.
Tests: 31 new (bijection both ways incl. patch versions, dialect seam both directions, every
V7 clause pass+refuse, workspace pinning, inline floor refusal at the step). 793 total green.
…osal (B5, M5)
A3: `step Phase1Done { checkpoint "order-placed" next Track }` — a v0.3 step on the same
content-inferred dialect seam (checkpoint => cycle/0.3; v0.2 frozen), parser/printer exact
bijection, name required and UNIQUE per cycle (duplicate names are unrepresentable — the name
is the rollback address). Lowers to a new CheckpointNode in the IR; V1-V6 unchanged.
Runtime: walking the node emits a marker with the committed-so-far snapshot and continues to
`next` — NO pause, no adapter call. dispatch persists each marker as a `run_checkpoints` row
{run_id, name, node_id, workspace, committed[], at}, idempotent by (run_id, name) — row-backed,
restart-safe. Executor RunResult gains `checkpoints`; on resume the committed-write ledger is
REBUILT from the restored context (pipeline order) so post-park checkpoints and saga unwinds
see pre-park commits too. `looks_committed` is the one public judgement of "this action output
is a committed effect", shared by executor and control plane.
Rollback (REUSES the existing compensation path, no second mechanism): POST
/runs/{run_id}/rollback {to_checkpoint} replays looks_committed over the persisted trace,
takes every write committed AFTER the marker, and previews the REVERSE chain of each step's
own `compensate_with` (args resolved against the trace so the card shows literals) — held as
ONE governed proposal (rb:{run_id}:{name}, verb run.rollback, tier HIGH) on the normal
pending/decision surface. Approval commits the compensations in reverse order via
PROPOSE->COMMIT with rb-{run_id}-{n} idempotency keys (the same honest forward-compensation
discipline as LocalExecutor._compensate); re-approval is a no-op (decide() guards the
transition, keys guard the crash window). Refusals as answers: IRREVERSIBLE_SEGMENT (409,
lists blocking steps, holds NOTHING), UNKNOWN_CHECKPOINT (404), workspace-pinned run lookup
fails closed. V7 (d) now honours a checkpoint boundary as compensation coverage.
Tests: 17 new (bijection, dialect gate, duplicate-name refusal, lowering, marker rows across a
restart, reverse-chain preview + idempotent re-preview, ordered approval commits with rb keys,
idempotent re-approval, IRREVERSIBLE_SEGMENT, unknown checkpoint/run, workspace pinning, V7-d
checkpoint coverage). 810 total green.
…le + tick sweep (B7 nil_schedule substrate)
A schedule is a row (scheduled_executions), never an in-memory timer: registered
only for pending/approved cards with a future ISO-8601 'when' (past timestamps
refuse with PAST_SCHEDULE), swept by the same /automations/tick clock as parked
runs and signature deadlines, and fired through the ONE shared execute path
(_execute_prepared_core, now also backing POST /prepared/{id}/execute). Outcomes
settle on the row (fired | refused) with the claim guard so overlapping ticks
never double-fire; a strategy unsatisfied at fire time records NOT_APPROVED as
the answer — never a silent retry.
…are/execute/schedule (B7, Gate M6)
The model's tool surface stays FIVE regardless of catalog size; zero raw verbs
reach it. CapabilityTools relays to the control plane (registry SSOT, typed
contracts, strategy interpreter, the one gated commit path):
- nil_discover: pure-code ranking (alias exact/substring in EN+AR, intent/
example word overlap, domain filter), published + exposure.ai ONLY (draft/
hidden never surface — fail closed), max 8, deterministic order, honest
empty ('do NOT fall back to raw verbs').
- nil_inspect: full contract + strategy summary + content-hash.
- nil_prepare: card envelope; INPUT_CONTRACT refusals pass through with field
lists as answers.
- nil_execute: NOT_APPROVED returns 'awaiting signatures — a human must sign
in Decisions', never retried.
- nil_schedule: one-shot row over the a98b0f6 substrate; PAST_SCHEDULE refuses.
Registered in BOTH surfaces (the capability plane is the model-facing plane;
verb tools stay behind the builder flag); absent entirely when no control
plane is configured. SKILL.md gains the discover → inspect → prepare → HUMAN
approves → execute discipline; verb-level docs kept for builder mode.
…e the .nil bijection
ActionStep has carried retry, on_error, and compensate since the v0.2
freeze, but the printer never emitted them and the parser never read them
— a cycle using any of them failed parse(print(ast)) == ast, breaking the
canvas⇄.nil SSOT trust contract.
Canonical grammar (between the verb line and the output/next routing
tail, in model field order; the fields are v0.2 — no dialect change):
retry { max_attempts: 3; backoff: exponential; initial_seconds: 2.0 }
on_error route -> Cleanup # '-> target' only when to is set
compensate_with odoo.refund_invoice { payment_id: "pay.id" }
The retry block prints every field explicitly (the approval
timeout_seconds voice); on_error routes borrow the 'on X -> Step' arrow;
compensate_with mirrors 'use verb { args }'. ActionStep-only — no other
step kind carries these fields; a query step with them refuses to parse.
Wiring (the wait_for_event precedent, c1d40d7):
- registry: on_error.to is a step-target edge (dead-ref undefined_step,
find-references); compensate args are data refs (undefined_ref, and a
compensation-only reader keeps an output 'used').
- lsp: retry/on_error/compensate_with in step keywords + semantic-token
keywords; the word after compensate_with classifies as a verb.
Byte-stability (non-negotiable): every fields-absent cycle prints
BYTE-IDENTICAL — pinned by sha256 regression over the three worked
fixtures, hashes computed against the printer before this change.
Tests: 836 -> 858 green (each field individually, combined, canonical
form/order, refusals, registry + LSP wiring, hash pinning).
…ate, permanent
tests/test_p0_gate_demo.py IS Gate P0 (MVP-EXECUTION-PLAN.md, quoted in the
module docstring): a 3-step cycle (query -> HIGH write -> notify) registered
as a capability runs live end-to-end, all in mock mode with zero credentials.
The one test walks, each assertion tagged with the invariant it proves
(I1 card determinism, I2 two-key+SoD, I3 approval-drives-execution,
I4 idempotency, I5 tenancy fail-closed, I6 per-phase rollback, I7 mock-first):
1. /cycles/register (pending_approval, armed by the owner) + /capabilities/wrap
(risk HIGH from DECLARED verb tiers) + /strategies two-key upgrade (v2 of
the wrapped strategy id — strategies are data).
2. /prepared -> the deterministic Permission Card: EXACT payload preview,
quorum(2, distinct) state naming both keys, parked on the Decisions feed,
zero effects fired.
3. preparer's own signature -> 403 SOD_VIOLATION.
4. first key -> pending (1 of 2), /execute refuses NOT_APPROVED, still no run.
5. second DISTINCT key -> the commit fires the implementing cycle EXACTLY once
(run key = prep:{prepared_id}); the run PARKS on the HIGH write (verb-tier
gate), visible in pending after the hold registers; the pre-write checkpoint
marker persisted as a row even while parked.
6. owner approves the write proposal -> ONE commit, the run RESUMES to the
notify and completes with the committed result (proposal, state, id) bound
in the trace.
7. replay: /prepared execute -> ALREADY_COMMITTED; re-firing the same
idempotency key -> replayed=true; one propose, one commit, one run row.
8. a second workspace sees NOTHING: empty prepared feed, 404 card, empty
pending, empty runs, 404 rollback.
9. /runs/{id}/rollback to the checkpoint -> ONE held governed proposal
(rb:{run}:{name}) listing the write's own compensate_with; approval
compensates with rb-{run}-0 keys; re-approval never double-compensates.
No joins had to be built: the prepare-plane commit already fires the
capability's default implementing cycle through fire_manual, and the parked
HIGH write resumes through the same decision endpoint — the demo composes
existing seams only (fixtures from test_gate_resume / test_prepared /
test_checkpoint_rollback). One honest sequencing note is documented: the
two-key card gates the FIRING; the HIGH write parks on the second, verb-tier
gate — governance is layered.
Tests: 858 -> 859 green.
…tes (Wave 4 §14.2) The anti-explosion spine (Encaps D7 / Risks 3,5,8): pure functions over the WHOLE capability set that a single Capability can't check about itself — pinned SemVer (this is how `latest` is rejected at the registry), one canonical concept (consistent owner/domain per id, no forked body at a version), and an acyclic dependency DAG (cycle detection with a witness path). Designed as executable invariants (Master Plan E1): the registration endpoint will call validate_registry(existing + candidate) and reject any violation naming the candidate. 13 tests. First implementation brick of the Wave 4 Constitution; nothing downstream (Skill/Domain/DSL/compiler) is stable until this gate is. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… §14.2b) The register endpoint now runs the registry gate before persisting: a candidate that would introduce a new SemVer or dependency-DAG violation is refused 409 with the violating witness, else it registers as before. The candidate replaces its own id (register supersedes), so a legitimate supersede never self-collides and a pre-existing registry issue never fails an unrelated registration; the gate fails OPEN on its own internal error (governance must not brick the registry). Audited against the live ws_acme catalog (45 capabilities) first — 0 violations, so enforcement is non-breaking. 3 endpoint tests (cycle→409 + not stored, acyclic allowed, supersede allowed). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…inding (Wave 4 §14.3) Introduces the Domain AST (domain/0.1): a curated business area that IMPORTS capabilities by alias at a pinned major (Encaps D2 — the DI/permission boundary; `latest` is unrepresentable since major is an int) and BINDS a backend per capability (D8 — the explicit multi-ERP routing decision that replaces the implicit newest-declarer-wins in os-server RoutingNilClient; Procurement.Crm→odoo vs Finance.Crm→sap, both Card-visible). The model makes an ambiguous alias / unbound / double-bound capability unrepresentable; resolve_alias + resolve_backend are the exact lookups the compiler will perform (it fails the compile when either returns None). Pure, no existing code touched. 11 tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ve 4 §14.3b) Adds the Skill sub-layer of a Capability (Encaps D3/D5): `Skill` = one named operation (send/receive/ notify) with input/output schemas, semantic-first `resolves_to` verb candidates, and a `GovernanceEnvelope` (tier · reversibility · the FULL effect set — the compile-checked blast radius the Permission Card shows). Capability gains an OPTIONAL `skills` tuple (wrapped v0 caps omit it → the live catalog is unaffected), validated for unique names + the I3 tier floor (a skill may only sit at/above the capability risk). `resolve_skill` + `resolve_skill_verb` are the compiler's lookups: semantic-first, an explicit `via:` disambiguates, and it REFUSES (never guesses) on an unknown skill or an ambiguous/ unsanctioned via. 14 tests; 87 capability tests green (parser/printer round-trip unaffected). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The frozen L2 contract Hermes emits and the compiler consumes: a BizSpec expresses WHAT must happen in governed business terms with no runtime detail. Two deliberately-distinct step kinds keep effects and control flow from blurring (D4): UseStep (call a capability Skill by meaning — Alias.skill, optional via/bind) and ControlStep (approval/wait/decision/checkpoint/notify — a primitive, never a capability). The IR checks shape only (dotted Alias.skill, approval needs a strategy, wait needs an event, ≥1 step); that a `use` names a REAL skill and not a private verb is enforced at COMPILE time by resolve_skill, not here — an honest boundary. This is the seam that lets Hermes stay replaceable and the compiler stay a pure L2→L3 function. 8 tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…gistry -> CompiledPlan (Wave 4 §14.4b) The payoff that ties the foundation together: compile_bizspec is a PURE function (same inputs -> same plan, no model) that lowers a BizSpec through a Domain + the registry. For each skill call it resolves the alias -> capability via the Domain's imports (D2), pins the exact SemVer at the imported major, resolves the verb (D3, semantic-first + via), and the backend (D8) — then computes the aggregate governance envelope (D5: strongest tier respecting the policy floor, union of effects, strongest reversibility) and validates that the capabilities the plan actually uses form no cycle. Every unresolved reference is a typed CompileRefusal (I2 — never a guess): UNIMPORTED_ALIAS, CAPABILITY/MAJOR_NOT_REGISTERED, UNKNOWN_SKILL, UNRESOLVED_VERB, UNBOUND_BACKEND, DEPENDENCY_CYCLE, DOMAIN_MISMATCH. CompiledPlan is the structured L3 the .nil printer (§14.4c) will serialize. 13 tests; 75 Wave-4 tests green across domain/skill/bizspec/compiler/registry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…Wave 4 §14.4c pt.1) render_plan turns a CompiledPlan into stable, human-readable text: the Domain + intent + aggregate governance envelope, then one line per lowered step (capability@version, skill->verb, governed backend D8, tier, bind, sorted args). This is the artifact a reviewer confirms before approval and a stable audit record (same plan -> same text). Explicitly NOT the runnable .nil cycle grammar: lowering a CompiledPlan to an executable Cycle AST is design-gated — a BizSpec ControlStep is thinner than a runnable ApprovalStep/WaitForEventStep (no approver/on_approve, match/on_timeout, next-chaining), so the control-step model must be enriched first (that half of §14.4c starts fresh). 2 tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…14.4c pt.2) Resolves the design gate: L2 carries no runtime scaffolding (§11), so step ids, linear next-chaining, the Flow entry, and the required transition targets (on_approve/on_reject/on_timeout) are SYNTHESIZED by the compiler — the BizSpec ControlStep gains only BUSINESS fields (approver, message, match, timeout). lower_to_flow maps each compiled step to its kernel step type (effect->ActionStep on the resolved verb; approval/notify/checkpoint/wait->their nodes) and appends a terminal so every target resolves; a `decision` step is refused in v0.1 (linear plans only). Proven RUNNABLE: a lowered flow wrapped in a Cycle survives print_nil->parse_nil identically. The full pipeline is now real end-to-end: BizSpec -> compile -> CompiledPlan -> lower -> runnable .nil. 6 lowering tests; 101 Wave-4 tests green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… §14.5) Pulled the ACTUAL cyc_order pipeline from the live control plane and mapped it onto the new stack: its three effect verbs (resource.read, procurement.create_purchase_invoice, commerce.record_payment) become a Procurement Domain (D2 imports + D8 odoo bindings) with three Skills, and its linear spine compiles+lowers cleanly TODAY (resolved verbs, pinned versions, aggregate HIGH/IRREVERSIBLE envelope, runnable round-tripping .nil). Surfaces the one concrete blocker: step_3's wait `on_timeout→step_5` escalation is NON-LINEAR, and v0.1 lowering is linear+terminal only. Framed as a design gap (L2 must stay scaffolding-free per §11) with three options; recommends A (inline business-level `on_timeout` action, compiler synthesizes the branch). Lays out the 5-step §14.5 plan: close routing gap → author Domain+Skills → express BizSpec → prove parity → verbs-private. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… routing gap (Wave 4 §14.5a)
The non-linear branch cyc_order needs, without leaking runtime routing into L2. A `wait` control step
gains an optional business `escalate` message ("if the deadline passes, emit this and halt") — a
message, NEVER a step id (§11: the DSL stays scaffolding-free). The compiler synthesizes the branch:
lower_to_flow emits a dedicated escalation NotifyStep (emit-and-halt) and routes the wait's on_timeout
to it instead of the shared terminal. This is the same division the whole architecture rests on — the
author states intent, the compiler owns the graph. Unblocks a faithful cyc_order migration (§14.5b).
33 lowering tests incl. the cyc_order-shaped escalation; 103 Wave-4 tests green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…a live production cycle (Wave 4 §14.5b)
The milestone: the live cyc_order (pulled from the control plane) expressed on the new stack — a
Procurement Domain, three capabilities each exposing one Skill, and a BizSpec in business language with
NO step ids and NO routing — compiles+lowers to a flow that reproduces cyc_order's execution semantics:
the same three effect verbs in order (resource.read -> procurement.create_purchase_invoice ->
commerce.record_payment), the same two human gates, and the same mail.received wait with {order_ref:$po}
correlation and the 7-day supplier-silence escalation branch. Governance aggregates to HIGH/IRREVERSIBLE;
backends are now EXPLICITLY bound to odoo (D8 — an improvement over implicit newest-declarer-wins); and
the lowered flow is runnable .nil (print/parse round-trip). Proves the architecture can represent a real
cycle without leaking runtime concepts into the business layer. 6 parity tests. §14.5c (verbs-private)
is now unblocked — only AFTER parity, as ordered.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…erb (Wave 4 §14.5c) The Skill API becomes the frozen ABI: a cycle reaches an effect ONLY through a Skill, never a verb. The compiler now refuses a direct verb reference BY NAME (PRIVATE_VERB) instead of a vague "unknown skill" — "comms.send_email is a private verb of Communication; call it through a skill (send, notify)". Applied only in the NEW stack (the legacy Cycle model keeps its verbs until the remove-legacy phase, as ordered: routing gap -> parity -> verbs-private -> delete legacy). Verbs/adapters/ERPs below the Skill line can now churn without touching any cycle. 1 test; parity + full compiler suite green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 3 Execution Phase: Create comprehensive test suite that simulates the end-to-end flow (Settings UI → CP → Executor → os-server) and prove all success criteria pass. **Test Suite:** - test_phase3_e2e.py: 16 integration tests (450+ lines) - BizSpec compilation with Domain bindings (3 tests) - Flow lowering with domain_id preservation (3 tests) - GovernedRoutingNilClient execution (3 tests) - Settings UI → CP API flow (2 tests) - Thread creation & correlation (2 tests) - Execution return values (2 tests) - Full Phase 3 integration flow (1 test) - test_phase3_parity_simulation.py: 15 parity tests (350+ lines) - Legacy cyc_order → compiled BizSpec equivalence (12 tests) - Round-trip NIL grammar serialization (1 test) - D8 explicit backend binding improvement (1 test) - Backward compatibility verification (1 test) **Test Results:** 31/31 PASSING ✓ **Verification Documentation:** - PHASE-3-VERIFICATION-CHECKLIST.md: All 50+ success criteria mapped to tests - PHASE-3-DEPLOYMENT-READINESS.md: Pre-deployment & deployment checklists - PHASE-3-SUMMARY.md: Executive summary of Phase 3 completion **Key Features Verified:** - BizSpec compilation with Domain bindings (D8 explicit backend routing) - Flow lowering preserves domain_id + backend_bindings - GovernedRoutingNilClient routes verbs to correct adapters - Parity: legacy cyc_order produces identical semantics when compiled - Thread creation with business_ref + correlation_id - Feature flag USE_GOVERNED_ROUTING provides rollback - Backward compatibility: old cycles still work **Wave 4 Reference:** §3 Capability Encapsulation Enforcement Governed backend binding (D8) now explicit in CompiledPlan + Flow. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
…sive events + review queue + outbound governance Wave 7 implements the complete communication loop for Business Threads: **Correlation Engine (5-layer cascade):** L1: Transport IDs (Message-ID, WhatsApp msg_id, SMS timestamp) [confidence: 1.0] L2: BCONV (Business Conversation ID) [confidence: 1.0] L3: Business Keys (order_ref, ticket_id, invoice_number) [confidence: 0.95] L4: Participant Matching (sender role, authority) [confidence: 0.85] L5: Temporal Causality (thread state, event criteria) [confidence: 0.75] **Passive Thread Events:** - CommunicationReceivedEvent: Ledger-backed inbound event - Deterministic thread resumption via wait_for_event nodes - Timeline rendering for thread case file **Review Queue:** - Handle ambiguous correlations (multiple matches) - Human picks correct thread - TTL-based expiry (72 hours default) - REST API for os-server integration **Outbound Governance:** - Route by tier: LOW/MEDIUM (send immediately), HIGH (notify), CRITICAL (wait for approval) - Reply token + BCONV stamping for return correlation - Approval cards for CRITICAL-tier messages **Testing:** - 43 comprehensive tests covering all 5 correlation layers - Ambiguous match escalation - Event lifecycle and store operations - Review queue resolution and expiry - Outbound routing and token stamping **Documentation:** - WAVE-7-COMMUNICATION-ENGINE.md: Full architecture + design principles - Integration points with control-plane and os-server - Phase 2 roadmap (full implementation + live testing) Files: - src/nilscript/comms/correlation_engine.py (460 lines) - src/nilscript/comms/passive_events.py (339 lines) - src/nilscript/comms/review_queue.py (346 lines) - src/nilscript/comms/outbound_governance.py (339 lines) - src/nilscript/comms/__init__.py (public API) - src/nilscript/docs/WAVE-7-COMMUNICATION-ENGINE.md (523 lines) - tests/test_wave7_correlation_engine.py (868 lines, 43 tests) Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
…+ tests Wave 5: Intent Boundary (Frozen Schema) - 7 intent kinds immutable (CreateBusinessCycle, ExecuteCycle, ReplyToThread, etc.) - Server-side CapabilityResolver (Kernel-owned, Hermes-opaque) - Intent versioning v1.0 locked - 68 tests passing Wave 6: Authority Layers (Governance Gates) - 5-tier hierarchy (L3 AuthorityLevel → L7 DelegationChain) - Role bundles + capability-scoped grants - Thread relationships + time-scoped permissions - Permission cards with multi-approver tracking - 31 tests passing Wave 7: Communication Engine (Smart Threading) - 5-layer correlation cascade (L1 transport IDs → L5 temporal causality) - Passive events resume parked threads via CommunicationReceivedEvent - Review queue for ambiguous messages (human resolution) - Outbound governance: BCONV + reply-token stamping - 43 tests passing Wave 8: Omnichannel Terminals (Multi-Channel) - Channel adapter contract (WhatsApp, Slack, SMS, Email, Mobile) - Invocation parser (extract cycle intents from channel messages) - Permission card renderer (channel-native UI) - Mobile terminal API (thin thread client) - 30 tests passing Healthcare Vertical Proof-of-Concept (HIPAA-Ready) - 5 healthcare capabilities (schedule, lab order, prescription, access records, verify coverage) - 3 clinical cycles (PatientIntake, LabOrder, Prescription) - HIPAA-compliant authority policies (right-to-access, minimum-necessary, audit trail) - Proves Kernel scales without modification (zero Kernel changes needed) - 30 tests passing Architecture: - Total new code: ~8,687 lines (Waves 5-8 + Healthcare) - Total tests: 200+ (all passing) - Kernel modifications: ZERO ✅ - Vertical-agnostic proven ✅ Security: - All secrets handled via environment variables - .env files properly excluded from git - HIPAA audit trail implemented Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
… for Control Plane
…utor with D8 governance routing - Wire GovernedRoutingNilClient for governed capability invocation - Execute Flow with backend_bindings (verbs → adapters) - Return actual execution result (not placeholder) - Support both Wave 4 compiled Flow and legacy cycle_id paths Phase 3 execution now complete: Settings UI → CP compile → CP execute with governance. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Multi-stage optimized image (python:3.12-slim) - Health check endpoint - Ready for production deployment Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
…us, specification)
…rovision derives caps, break kernel circular import Mirrors wosool-hub vendored copy (deployed to production): - _registry_authed: missing NIL_REGISTRY_TOKEN fails CLOSED under ENVIRONMENT=production - EventStore: missing/invalid NIL_VAULT_KEY refuses to boot in production - /tenants/provision: derives draft capabilities after adapter activation - kernel/__init__: lazy LocalExecutor import (PEP 562) breaks kernel→runtime→command_bus→cycle.models import cycle
…baseline bundle + Workspace Genesis endpoints Mirrors the wosool-hub vendored copy deployed to production (baseline 1.0.0).
…tor→runtime→cycle.models circular import
… detail reads, adapter bearers encrypted at rest Mirrors the wosool-hub vendored copy deployed to production (Phase 3).
…e claims against actor_roles (ROLE_NOT_HELD)
… (Phase 5 mirror)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 1 of multi-tenant SaaS (
PLAN-saas-multitenant): close the isolation hole where a request's tenant came from the freex-nil-workspaceheader — anyone could set it and read any workspace's data via registry routing.resolve_tenantgains a SaaS mode:claim_resolver(verified JWTworkspaceclaim)x-nil-workspaceheader cannot override it (mismatch → refused)x-nil-adapter-urlis rejected (identity routes to the tenant's registered active adapter)Header-trust remains only for self-hosted/dev (
multi_tenantwithoutsaas).build_remote_app/TenantToolsProviderthreadsaas+claim_resolver(envNIL_MCP_SAAS); SaaS fails closed without a resolver — it can never silently fall back to header-trust.Isolation conformance (the point)
25 mcp/tenant tests green; 105 green across mcp/tenant/intent/router.
Scope / honesty
This is the identity spine only (the decision we agreed: build this first). The production
claim_resolver(keycloak JWKS JWT verifier) is the deployment wiring — intentionally not hand-rolled here. Remaining for full SaaS: tenant-scope the newer surfaces (intent router providers, export, automation, Hermes isolation), per-tenant quotas/rate-limits, and the encrypted per-tenant secret vault (decided: control-plane vault). Not merged = no deploy.