R4.2 P0-C Trace / Tool-MCP / Credential Governance

Status boundary

This change is a candidate implementation on the governed P0-C branch. It does not promote protected main, deploy Production, or assert that all R4.2 target architecture is complete.

Scope model

Governance resources use an explicit scope_type:

tenant requires tenant_id and may narrow to user, project, conversation, and run;
system and global prohibit tenant ownership fields;
legacy preserves unscoped historical records without inventing ownership.

System and global tools therefore never receive a synthetic tenant merely to satisfy a tenant-oriented schema.

Trace lineage

TaskPlan and MessageEnvelope scope is bound to a TraceContext. The trace records trace_id, span_id, parent span, correlation, causation, task, message, and the canonical P0-A scope. Child spans must keep the parent's trace, task, and scope. Privileged visibility does not permit cross-scope trace splicing.

MessageEnvelope.correlation_id is persisted and identity-bound. Existing handoff databases are upgraded in place with an idempotent column migration; legacy rows retain their prior event IDs because a null correlation field is not added to the historical identity material.

Observability keeps its legacy presentation fields, but new governed records also carry immutable trace and scope fields. Scoped records require a trusted server actor for queries. A repeated execution ID is an idempotent replay only when the complete record matches; conflicting overwrites are denied.

Tool and MCP governance

ToolDescriptor binds a tool or MCP server to:

an explicit resource scope;
required actor capabilities;
an optional credential reference.

Invocation authorization requires exact propagation of the trace scope and a capability superset. Unknown tools, cross-tenant calls, scope substitution, and non-privileged access to system/global resources fail closed. Every successful registration and invocation appends hash-chained audit evidence.

Credential governance

Credentials are represented only by references whose schemes are systemd-credential, vault, or secret-manager. Raw bearer tokens, passwords, and arbitrary values are rejected. Grants are bound to scope, operation, task, tool, and expiry. Public/audit records contain a reference hash where disclosure is unnecessary; secret material is never persisted by this module.

The existing runtime credential broker remains backward compatible for system leases, adds explicit tenant/system/global invariants, and rejects providers that attempt to return raw token/secret/password environment values instead of file/reference indirection.

Durable evidence

The SQLite governance store is restart-safe and idempotently initializes four tables: governed tools, trace spans, credential grants, and audit evidence. Audit entries form a SHA-256 chain. Acceptance requires the chain to verify and contain the required actions; missing evidence is not treated as success.

Acceptance tests

The candidate must pass:

TRACE_LINEAGE_CONTINUITY;
TRACE_SCOPE_MISMATCH_DENY;
TOOL_MCP_AUTHZ_DENY;
TOOL_SCOPE_PROPAGATION;
CREDENTIAL_SCOPE_DENY;
CREDENTIAL_SECRET_EXPOSURE_DENY;
AUDIT_EVIDENCE_COMPLETENESS;
P0-A scope and P0-B handoff regression suites;
Python compilation, git diff --check, and a diff-scoped secret scan.

The repository-wide baseline currently has seven unrelated failures in the isolated host environment (five stale continuation-contract fixtures and two host-permission fixtures). The same seven failures reproduce at the untouched a642b045775b9154a00ae78543037fbef4fb447b base; they are not suppressed or modified by P0-C.

3.7 KiB Raw Blame History