feat: governed callers - MSP becomes one implementation of the caller role

[Freshair129]

Summary

This PR implements ADR-GKS-GOVERNED-CALLERS. The owner accepted it on 2026-09-27, including all four open questions as proposed.

Why. A customer that already has its own auth and memory should not have to deploy MSP just to write to GKS. GKS doesn't need the MSP product. It needs someone to fill three roles: authenticate the user, choose the scope, and attest provenance. This PR turns MSP into the first implementation of that role, a governed caller. Any other system can be provisioned for its own portfolios.

How a governed caller works

{ "schemaVersion": "gks-client-grants/v2",
  "clients": [{ "profile": "governed", "clientId": "acme-backend", "credentialSha256": "…",
                "provenanceNamespace": "acme", "portfolioIds": ["acme-portfolio"],
                "allowedTools": ["gks_knowledge_promote", "gks_search", "…"] }] }

• Transport: HTTP only. The credential is sent as Authorization: Bearer gksc_…, and each call carries _meta.gksCallerAuth with { version: "gks-caller-auth/v1", callerId, scopeDigest }.
• Boundary: the caller may act only in the portfolios listed in its grant, and each portfolio has exactly one governed caller. Because idempotency keys and refs are keyed by scope, two callers can never collide. The exact tenant wall (C0 D1) still applies inside a caller's own portfolio.
• Provenance: provenance_ref, provenanceRef and evidenceRef must use <own namespace>:proof/…. A caller cannot write under another caller's namespace, and msp is reserved.
• Attribution: every write records the authenticated caller_id (migration 0008).
• Out of scope: pipeline tools, OIDC/JWT, verifying proofs (GKS-IDN-006), and portfolios shared between callers.

What did not change for MSP

• The GKS_MSP_RELAY_CREDENTIAL / gks-msp-auth/v1 envelope over stdio and HTTP, API-010 payloads, and response shapes are all unchanged.
• MSP keeps msp:proof/ with the same error messages.
• MSP is denied only the portfolios that a governed grant owns (gks_scope_denied, "This portfolio is governed by another caller."). With no governed grants configured, behaviour is identical to before.
• The tool schema provenance pattern widens from ^msp:proof/ to ^[a-z][a-z0-9-]{0,30}:proof/. Every value accepted before is still accepted.

Changes

Area	Change
gks-contracts/client-auth.mjs	Grants v2 parsing (governed profile; v1 still parses as read); authorizeGovernedCallerRequest; governedPortfolios; GKS_MSP_CALLER
gks-contracts/validation.mjs, tool-definitions.mjs	Provenance checked against the caller's namespace (default msp); schema pattern widened
gks-core	promoteCandidate, applyHumanResolution and linkArtifact take a caller and pass callerId to persistence
gks-persistence, migrations/0008_caller_attribution.sql	caller_id NOT NULL DEFAULT 'msp-runtime' on promotions, stage_evidence, human_resolutions and artifact_links. The port accepts an optional callerId. The value is not returned in responses.
apps/gks-server	A bearer credential resolves to a read or governed grant. MSP is denied on governed portfolios. directClientGrant is renamed clientGrant.
docs	ADR-GKS-BOUNDARY 0.7.0b, ADR-GKS-CLIENT-ACCESS 0.3.0b, GKS-PORT-CONTRACT 0.11.0b, README, production runbook (provisioning and revoking a governed caller), and the call-direction rule in CLAUDE.md

Evidence

• tests/contract/governed-callers.test.mjs (27 tests):
  • grants parsing, plus 9 invalid documents that must fail startup;
  • 10 authorization denials;
  • over real HTTP: a governed caller writes and reads in its own portfolio, attributed to itself; it is denied outside its boundary, under MSP's namespace, without an envelope, and on pipeline tools;
  • MSP is denied the governed portfolio but keeps the others;
  • migration 0008 backfills existing rows as msp-runtime, including a stage-evidence row created by the 0005 hook.
• C0.4 golden corpus: 23 of 24 cases replay unchanged. The one that changes is TOOL-001, where tools/list now shows the widened pattern.
• check:baseline: caught exactly the tool registry hash and migration 0008; re-locked.
• Real MSP suites (MSP_REPO_ROOT pointing at the local Memory-and-Soul-Passport checkout):
  • msp-provider-compatibility passes.
  • msp-service-chain fails, but inside MSP's own client before any request reaches GKS. MSP's latest commit (fd6c24b) requires a workspace ID that this test's fixture doesn't send. This is unrelated to this PR and should be fixed separately.

Follow-up

The ADR's acceptance criteria include golden corpus cases for a governed caller. The corpus runner currently speaks only stdio, so the next PR adds an HTTP mode to the runner and a governed-caller golden case.

Test plan

• npm test: vitest 327 passed, 2 skipped (the MSP suites need MSP_REPO_ROOT); security 12/12; unit 9/9
• npm run check:c0 (PASS 24 / NOT_RUN 1), check:baseline, check:corpus
• msp-provider-compatibility against the real MSP checkout
• CI on this PR

🤖 Generated with Claude Code