§29 SDK & Workbench Architecture

This specification section defines implementation contracts for the Decision Lineage Protocol substrate.

The Decision Lineage Protocol defines nineteen primitives, ten behavioral invariants, seventy-nine SHACL shapes, seventy-two cross-cutting operations, forty-four query patterns, and three substrate profiles. §26 specifies the logical model. §27 specifies the operation catalog. §28 specifies the query architecture. This section specifies how those layers are consumed: the SDK that programmatic clients use to interact with the substrate, and the Workbench that human operators use to govern through it.

The SDK provides typed access to primitives, operations, and queries through three composable layers. The Workbench provides the governance user interface — organized not by screen or workflow, but by governance concern. Together, they constitute the development and governance experience for the DLP substrate.

---

§29.1 Architecture Overview

§29.1.1 SDK Architecture

The SDK exposes the substrate through three layers. Each layer builds on the one below it; each layer is independently usable.

Table 29.1.1: SDK Layer Architecture

The Core layer is the SDK's foundation. Every operation passes through it. The Query layer adds read-path sophistication — named patterns with typed parameters and return structures that abstract the dual-language query engine (§28). The Extension layer provides the mechanisms through which applications customize the substrate for domain-specific governance.

§29.1.2 MCP Server Integration

The MCP Server (§28) is the primary AI agent interface. The SDK wraps MCP tools for programmatic access while preserving the same operation semantics and return structures. The relationship is architectural:

• MCP tools expose thirty-five query patterns and operation endpoints to AI agents through natural-language parameter descriptions.
• The SDK Query layer exposes the same thirty-five patterns plus nine SDK-only internal patterns through typed method signatures.
• Both interfaces produce identical return structures (§28). A query executed through MCP and the same query executed through the SDK Query layer return structurally equivalent results.

The MCP Server is not a separate system. It is an interface projection of the SDK — a translation layer that maps MCP tool invocations to SDK method calls.

§29.1.3 Workbench Architecture

The Workbench is the governance user interface — the human interface to the substrate. It is organized by governance concern, not by application workflow. Three component classes serve three governance scopes:

Table 29.1.2: Workbench Component Classes

Component availability is profile-gated (§29.13). Components activate when the substrate instance reaches the profile tier and graduation stage that requires them. No component renders data the profile cannot produce.

Each Workbench component consumes query patterns from §28 and renders operation results from §27. The component does not contain governance logic. It renders governance state and captures human actions that the SDK Core layer executes as operations. The Workbench is a rendering and interaction layer over the SDK.

---

§29.2 SDK Core Layer

The Core layer provides typed access to the nineteen primitives and seventy-two cross-cutting operations with integrated invariant enforcement. Every write operation passes through the two-pass SHACL validation engine (§5.3) before persistence.

§29.2.1 Typed Primitive Access

The SDK exposes each of the nineteen primitive types as a typed record structure. The nine Tier 1 record types (IntentRecord, CommitmentRecord, CapacityRecord, WorkRecord, EvidenceRecord, DecisionRecord, AuthorityRecord, AccountRecord, ConstraintRecord) carry the common metadata fields defined in §28: id, instance_id, truth_type, verification_state, record_lifecycle_state, created_at, created_by, version. Each type extends common fields with its MVR fields (§7).

Table 29.2.1: Core Layer Primitive Operations

§29.2.2 Operation Contracts

The Core layer exposes the seventy-two cross-cutting operations (§27) as typed method contracts. Each operation specifies:

• Input parameters — typed, validated against the operation's preconditions.
• Primitive composition — which primitives the operation creates, reads, or modifies, and in what sequence.
• Authorization — what authority is required, whether human-only or delegable to AI actors.
• Invariant implications — which behavioral invariants (B1–B10) are triggered by this operation.
• Return structure — the typed result object produced on success, or the validation error on failure.

Operations compose atomically. A signal.create operation creates a Signal record, an Evidence record (truth type Authoritative for the observation act), and routes the signal to the authority chain (B8) — all within a single transactional boundary. If any step fails validation, no records are persisted.

Table 29.2.3: Operation Domain Summary

§29.2.3 Invariant Enforcement Integration

The SDK Core layer integrates the two-pass SHACL validation engine as a mandatory pre-write gate.

Table 29.2.2: Validation Pass Integration

Pass 1 validation is non-negotiable. No profile, no configuration, and no extension can downgrade a Pass 1 shape below Blocking. Pass 2 validation is profile-configurable within defined bounds: enforcement mode may be adjusted between Blocking, Warning, and Logging, but no shape may be downgraded below Logging.

The SDK returns validation results as typed objects. A ValidationError on a Pass 1 failure contains: the invariant violated (B1–B10), the shape URI that fired, the focus node (the primitive instance that failed), the severity (sh:Violation), and a remediation guidance string describing what the caller must provide to satisfy the shape.

---

§29.3 SDK Query Layer

The Query layer provides typed access to the forty-four named query patterns defined in §28. Each pattern is a parameterized template with typed inputs and a typed return structure. The Query layer abstracts the dual-language query engine — callers specify what they want; the engine determines whether to use Cypher (graph traversal), SQL (relational aggregation), or both.

§29.3.1 Named Pattern Access

Each query pattern is exposed as a named method with typed parameters and a typed return structure.

Table 29.3.1: Query Layer Pattern Access

§29.3.2 Parameterized Templates

Every query pattern accepts typed parameters. Parameters fall into three categories:

• Scope parameters — instance_id (required on all patterns), actor_id, authority_id — identify the query target.
• Filter parameters — status, truth_type, cognitive_type, invariant — narrow the result set.
• Traversal parameters — max_depth, relationship_type, time_window — control graph traversal depth and temporal range.

The SDK validates parameters before query execution. Invalid parameters produce a ValidationError with the parameter name, the constraint violated, and a suggested action.

§29.3.3 Return Structure Types

All query results are typed. The SDK Query layer defines eleven return structure families:

• Primitive records (9 types) — one per Tier 1 primitive, with common metadata fields.
• Graph results (3 types) — PathResult, TreeResult, SubgraphResult for graph traversal patterns.
• Aggregate results (3 types) — CountSummary, DistributionResult, TimelineResult for analytical patterns.
• Governance state results (3 types) — GapRegisterEntry, ActivationStatusRecord, ConformanceResult for governance domain patterns.
• Orchestration results (3 types) — RoutingDecisionRecord, WorkSpecificationRecord, GraduationAssessment for orchestration patterns.
• KPI results (2 types) — InvariantSignalReading, KPILifecycleRecord for KPI domain patterns.

List-returning patterns wrap results in PaginatedList<T> with cursor, limit, total, and has_more fields. Every query response includes QueryMetadata recording query execution identity, timing, engine selection, and profile context.

---

§29.4 SDK Extension Points

The SDK defines extension points at documented boundaries. Each extension point specifies what is extensible, what constraints govern extension, and what composition rules apply. Extension points enable application-specific governance without modifying the core substrate.

§29.4.1 Content Package Extensions

Content packages customize the substrate for specific governance domains. A content package bundles:

• Intent templates — pre-defined intent structures for domain-specific objectives (e.g., compliance intents, financial intents, operational intents).
• Evidence types — domain-specific evidence classifications with validation rules.
• Authority templates — pre-configured delegation structures for common organizational patterns.
• Constraint sets — domain-specific SHACL shapes that extend the core seventy-nine shapes.

Content packages are scoped to profiles. An EAS content package may activate governance patterns unavailable at BAS or PAS. Content packages compose additively: multiple packages may be active simultaneously, and their constraints compose through intersection (§A2.2).

Table 29.4.1: Content Package Constraints

§29.4.2 Custom Governance Rules

Applications may define additional SHACL shapes for domain-specific constraints beyond those provided by content packages. Custom shapes follow the same registration and enforcement model as the core shapes.

Custom shapes MUST:

• Target existing primitive classes or content package extensions.
• Declare a severity level (sh:Violation, sh:Warning, or sh:Info).
• Declare an enforcement mode (Blocking, Warning, Logging, or Advisory).
• Register in the shapes graph with a distinct namespace URI.

Custom shapes MUST NOT:

• Override the enforcement mode of any core shape.
• Relax any constraint established by an ancestor instance in the portfolio hierarchy (tighten-only cascade, §23).
• Create circular dependencies with existing shapes.

§29.4.3 Custom Query Patterns

Applications may register additional query patterns with the SDK Query layer. Custom patterns use the same parameterized template system as core patterns.

Custom patterns MUST:

• Declare typed input parameters and a typed return structure.
• Use the PaginatedList<T> wrapper for list results.
• Include QueryMetadata in every response.
• Register with a pattern identifier in the application namespace (not the QP- prefix reserved for core patterns).

Custom patterns MUST NOT:

• Bypass depth-gated visibility rules (§23). Custom patterns respect the same visibility constraints as core patterns.
• Return data from instances outside the caller's authorized scope.

§29.4.4 Custom Composite Operations

Applications may define composite operations built from atomic SDK Core operations. A composite operation sequences multiple atomic operations within a transactional boundary.

Custom operations MUST:

• Compose exclusively from documented SDK Core operations.
• Produce the same invariant enforcement behavior as the component operations executed individually.
• Record the composite operation in the audit trail as a single governance act with lineage to its component operations.

Custom operations MUST NOT:

• Suppress or defer invariant validation that would fire on component operations.
• Create primitives without satisfying their behavioral invariant requirements.

§29.4.5 Event Subscription Extensions

The SDK provides an event subscription mechanism for governance events. Applications subscribe to events at documented lifecycle boundaries.

Table 29.4.2: Subscribable Event Categories

Event subscriptions are passive observers. A subscription receives notification of governance events after they occur; it cannot block, modify, or intercept the event. This preserves the substrate's invariant enforcement integrity — extensions observe governance but do not gate it.

DESIGN SPACE: The event delivery mechanism — webhooks, message queues, server-sent events, polling — is an implementation choice. The SDK MUST provide a subscription registration API and guarantee at-least-once delivery semantics.

§29.4.6 Extension Composition Rules

Extensions compose with the core substrate through defined rules that prevent extension conflicts and maintain governance integrity.

Table 29.4.3: Extension Composition

§29.4.7 Interchange Format Support

The SDK exposes query results through the three interchange formats specified in §28: MCP/JSON, JSON Export, and RDF/OWL Export. SDK consumers additionally access results as typed native objects — the programmatic access layer through which the interchange formats are produced.

Table 29.4.4: Interchange Format Architecture

All three formats represent the same underlying query results; they differ in serialization and structural fidelity. The SDK typed access layer produces the interchange format appropriate to the consumer: MCP tools return MCP/JSON, programmatic SDK methods return typed objects convertible to JSON Export or RDF/OWL on request.

Key fidelity differences between JSON formats and RDF/OWL (§28): decision lineage (QP-LIN-01) loses causal branching in JSON. Impact radius (QP-LIN-03) collapses thirteen edge types to a generic edge_type field. Instance tree (QP-PRO-02) collapses five relationship types to generic "children." Conformance check (QP-GOV-04) simplifies the W3C SHACL validation report format. For governance applications requiring full fidelity, the RDF/OWL format is the canonical export.

---

§29.5 Workbench Component Taxonomy

The Workbench organizes governance interaction into twelve component types across three classes. Each component has a defined data contract (what query patterns it consumes), interaction contract (what operations it invokes), and profile gate (when it activates).

§29.5.1 Core Components

Core components are present in every substrate instance regardless of profile. They provide the fundamental governance interaction capabilities that all profiles require.

Table 29.5.1: Core Component Inventory

§29.5.2 Governance Components

Governance components activate at EAS and BAS profiles. They provide governance activation tracking, conformance monitoring, and authority chain management.

Table 29.5.2: Governance Component Inventory

The Knowledge Integration Dashboard provides two surfaces for TMI Operate mode (§18, §19) alignment management:

Contextual inline. When a practitioner works with a governed object (in the Primitive Browser, Decision Surface, or any component rendering primitive instances), pending alignment claims for that object's primitives appear inline. The user can confirm, correct, or dismiss an alignment proposal without leaving their governance context. This surfaces alignment review as a natural side-effect of governance work — the practitioner encounters alignment proposals where they are relevant, not in a separate queue.

Dedicated steward view. An ontology steward — a governance role with authority over the knowledge integration scope — accesses the full dashboard to manage:

• Pipeline health — TMI Alignment Pipeline (§18.3) throughput, confidence distribution across the three matchers, Stage 7 Review Queue depth and age
• Graduation progress — alignment claims by namespace scope (sandbox → tenant → domain → core), advancement and reversion trends (§18.4)
• Namespace coverage — which ontology families have active alignment coverage, gap detection across the ten recognized families (§19.2)
• Bridge integrity — cross-ontology bridge relationship health (§19.5), propagation accuracy, stale bridge detection
• Conservation law tension — alignment proposals flagged for potential conservation law conflict (§18.6), organized by affected primitive and law

The contextual surface is available to all users who encounter governed objects with pending alignment claims. The dedicated steward view is authority-gated — only actors with integration scope authority see the full dashboard.

§29.5.3 Enterprise Components

Enterprise components activate at EAS profile only. They provide KPI management, AI orchestration oversight, and recursive portfolio governance.

Table 29.5.3: Enterprise Component Inventory

§29.5.4 Component Data Flow Architecture

Every Workbench component follows a uniform data flow: query patterns provide read access to governance state; operations provide write access through the SDK Core layer; validation results flow back to the component as rendering updates.

Table 29.5.4: Component Data Flow

Components do not communicate directly with each other. Cross-component navigation is link-based: a violation rendered in the Conformance Dashboard links to the focus node in the Primitive Browser; a signal in the Signal Capture component links to the flagged object's detail view. The Workbench maintains navigational consistency through primitive identity — every governed object has a stable URI that any component can reference.

§29.5.5 State Machine Rendering

The Workbench renders nine lifecycle state machines (SM-1 through SM-9) and three truth type state machines (§6). Each state machine renders through its owning component.

Table 29.5.5: State Machine to Component Mapping

The §6 truth type system defines three additional orthogonal state machines: Evidence Verification (VerificationState), Derived Promotion (TruthType), and Claims Graduation (ClaimsGraduationStage). These are rendered by the Primitive Browser on every Evidence instance — the verification state indicator, truth type indicator, and claims graduation stage are visible on every record.

Each state machine rendering shows: the current state, the set of valid transitions from the current state, the guard conditions for each transition (what must be true for the transition to fire), and the authority requirement (who can trigger the transition). Transitions that require a Decision primitive (most non-automatic transitions) link to the Decision Surface for resolution.

---

§29.6 Primitive Browser & Lineage Navigation

The Primitive Browser provides navigation and inspection of primitive instances within a substrate instance. It is the foundational Workbench component — every other component links back to the Primitive Browser when a user needs to inspect a specific governed object.

§29.6.1 Primitive Instance Rendering

The Primitive Browser renders instances of all nineteen primitive types. Each instance renders with:

• Identity — primitive type, instance identifier, human-readable label.
• Truth type indicator — visual distinction between Authoritative, Declared, Derived, and Opaque records (§6). Derived records carry visible attribution identifying the generating agent or computation. Opaque records carry visible boundary indicator identifying the inspection boundary source.
• Verification state — current verification outcome (unverified, verification_pending, verified, verification_failed, cannot_verify).
• Record lifecycle state — whether this record is active or superseded.
• Invariant status — which behavioral invariants (B1–B10) apply to this instance and their current validation state.

Table 29.6.1: Primitive Browser View Modes

§29.6.2 Truth Type Visualization

Truth type is a first-class visual element. Every primitive rendering distinguishes the three truth types through consistent visual language:

• Authoritative — the canonical record. Human-verified, immutable. Rendered with the highest visual confidence.
• Declared — human-asserted, attestation-backed. Rendered with moderate visual confidence and the declaring entity attribution.
• Derived — machine-generated, requires promotion. Rendered with explicit Derived marking, generating agent attribution, and a promotion pathway indicator when promotion is applicable.

The visual distinction is mandatory. A governance interface that renders Derived and Authoritative records identically violates the epistemic boundary (§6.2).

§29.6.3 Lineage Traversal

The Primitive Browser provides graph-based lineage traversal using the thirteen cross-primitive relationship types defined in §4.4. Traversal supports:

• Upstream navigation — from a Decision, trace back through the Evidence it evaluated, the Authority that legitimized it, the Intent that framed it, and the Account that contextualized it.
• Downstream navigation — from a Decision, trace forward to the Work it authorized, the Commitments it created, and the Constraints it established.
• Impact radius — from any primitive, visualize all connected primitives within a configurable depth limit (QP-LIN-03).

Lineage traversal respects depth-gated visibility (§23). A user in a child instance sees full detail for their own instance, full detail for direct children, and aggregate patterns for deeper descendants. The Primitive Browser does not expose data outside the user's authorized visibility scope.

§29.6.4 Cross-Primitive Relationship Rendering

The Primitive Browser renders the thirteen cross-primitive relationship types (§4.4) as navigable edges in the governance graph. Each relationship type is visually distinct and carries its cardinality and invariant enforcement status.

Table 29.6.2: Relationship Type Rendering

Relationships with invariant enforcement render with a distinct visual treatment: the link itself indicates whether the invariant is currently satisfied. A broken B1 link (Work without Commitment) renders as a violation indicator inline, navigable to the Conformance Dashboard violation detail.

---

§29.7 Signal & IQ Capture Components

Signal Capture and IQ Capture are the two human capture mechanisms specified in §14–§16. The Workbench renders them as paired entry points: Signal Capture for object-anchored problems, IQ Capture for context-anchored emergence.

§29.7.1 Signal Capture Component

The Signal Capture component implements the §15 contract: zero friction, always available, structurally typed, optionally deep, authority-routed, context preserved.

Data consumed: QP-SIG-01 (signal list with status and type filters), QP-SIG-03 (escalation chain for routing visualization).

Rendering contract:

The Signal Capture entry point MUST be present on every interface that renders a governed object. This is the B7 architectural guarantee: if an object is rendered, it is flaggable.

§29.7.2 IQ Capture Component

The IQ Capture component implements the §16 contract: zero friction, always available, structurally typed, optionally deep, context preserved, investigator-routed.

Data consumed: QP-SIG-02 (IQ list with status and intent type filters).

Rendering contract:

§29.7.3 Cross-Mechanism Integration

The Workbench renders cross-mechanism interactions (§14.5) as bidirectional links. When a signal spawns an IQ, the signal detail view shows the linked IQ with its current lifecycle state. When an IQ spawns a signal, the IQ detail view shows the linked signal. Both link types are navigable — clicking traverses to the linked record's detail view.

The Workbench surfaces reservation signals on reference: when a reserved object is rendered in any context (Primitive Browser, Decision Surface, governance dashboard), active reservations are visible as annotations with their surface trigger status and reservation nature.

---

§29.8 Decision Surface Components

The Decision Surface component renders the §17 contract: the interactive interface through which humans evaluate governance conditions and resolve them through Decision primitives. Decision Surfaces compose from three Validated Projection types — Plan Baseline, Condition Assessment, and Prediction.

§29.8.1 Decision Surface Rendering

The Decision Surface presents four compositional elements, each traceable to its source VP.

Table 29.8.1: Decision Surface Composition

§29.8.2 VP Overlay Rendering

Validated Projections are Derived truth (§6). The Decision Surface renders them with explicit Derived marking:

• Confidence indicators — numerical confidence (0.0–1.0) with mode-specific computation visible on hover or drill-down.
• Staleness indicators — VP cache state (Current, Stale, Recomputing, Invalidated) visible on each component. Stale components show time since staleness and whether recomputation is in progress.
• Assumption inventory — each VP's assumptions are accessible. The user can challenge any assumption and request an alternative projection with modified parameters.
• Version provenance — the specific VP version (projection_id + version) that was Current when the surface was composed.

If any component VP transitions to Stale or Invalidated between surface composition and human resolution, the Decision Surface re-renders with updated components before permitting Decision creation.

§29.8.3 Information Quality Indicators

The Decision Surface integrates information quality indicators from the capture mechanisms:

• IQ presence/absence — for each decision option, the surface shows whether investigative queries have been conducted and what they found. Options with unresolved blocking IQs (§16.6) are marked as blocked.
• Signal inventory — active signals attached to the condition's subject primitive are visible. Unresolved signals are flagged.
• Reservation visibility — active reservations on the condition's subject are surfaced during decision evaluation.
• Evidence completeness — for each option, the surface indicates what evidence exists (with truth type) and what evidence gaps remain.

§29.8.4 Authority Verification

Before a human resolves a Decision Surface, the Workbench verifies:

• The resolving actor holds Authority over the condition's scope (QP-AUTH-03).
• The authority chain is traceable to root (B5).
• The Decision will link to an Account (B4 — the SDK Core layer enforces this).

Authority verification results are rendered inline. If the actor lacks sufficient authority, the Decision Surface displays the required authority scope and the actor's current authority, with an escalation pathway.

§29.8.5 Reservation Capture at Resolution

When a human resolves a Decision Surface by selecting a disposition, the interface offers reservation capture (§14.6.1). The resolver may record held objections as reservation signals attached to the Decision. Reservations do not block the resolution — they enrich the lineage record. The reservation nature taxonomy (framing, terminology, completeness, edge_case, confidence, timing, other) and surface trigger configuration are accessible at resolution time.

---

§29.9 Governance Dashboard Components

Governance dashboard components render the governance activation pipeline (§12), conformance state (§5, §13), and authority structures. They activate at EAS and BAS profiles.

§29.9.1 Governance Activation Dashboard

The Governance Activation Dashboard renders the six-stage activation pipeline (§12) for the substrate instance.

Data consumed: QP-GOV-01 (governance registry), QP-GOV-02 (activation pipeline), QP-GOV-03 (gap register).

Table 29.9.1: Activation Dashboard Elements

§29.9.1.1 Gap Register Detail

The gap register is the operational core of the Governance Activation Dashboard. Each gap represents a governance requirement that is not yet fully evidenced. The rendering provides actionable context for closure.

Table 29.9.4: Gap Register Entry Rendering

Gap register entries sort by criticality (conservation-critical first) and within criticality by closure stage (earlier stages first). This ordering is deterministic — the four-level criticality scheme (§12) produces a total order over gaps.

§29.9.2 Conformance Dashboard

The Conformance Dashboard renders invariant validation results across all seventy-nine SHACL shapes and the ten behavioral invariants.

Data consumed: QP-INV-01 (invariant compliance), QP-INV-02 (violation history), QP-INV-03 (override audit), QP-GOV-04 (conformance check).

Table 29.9.2: Conformance Dashboard Elements

§29.9.3 Authority Browser

The Authority Browser provides interactive navigation of authority chains, delegation trees, and authority verification.

Data consumed: QP-AUTH-01 (authority chain), QP-AUTH-02 (delegation tree), QP-AUTH-03 (check authority).

Table 29.9.3: Authority Browser Elements

---

§29.10 KPI Dashboard Components

The KPI Dashboard renders the three KPI classes defined in the KPI evolution model (§28 Domain J): Invariant Signals (always-on health monitoring), Control KPIs (intent-driven phase-specific levers), and Intent Progress Indicators (strategic continuity tracking). The KPI Dashboard activates at EAS profile only.

Data consumed: QP-KPI-01 (KPI lifecycle), QP-KPI-02 (invariant signals), QP-KPI-03 (control KPIs).

§29.10.1 Invariant Signal Zone

Invariant Signals are always-on, never time-boxed, and never targets. They protect the enterprise during rapid change. The Invariant Signal zone renders eight dimensions continuously.

Table 29.10.1: Invariant Signal Dimensions

Each dimension renders:

• Current value — latest reading from QP-KPI-02.
• Trend indicator — increasing, stable, or decreasing, computed from historical values.
• Threshold status — normal, warning, or critical relative to configured thresholds.
• Historical series — time-series visualization with configurable time window.
• Drill-down — from any dimension, navigate to the underlying primitives contributing to the reading.

Invariant Signals run in the background of every EAS governance session. They do not require user action to render — they are ambient governance health indicators.

§29.10.2 Control KPI Zone

Control KPIs are intent-driven, phase-specific, and explicitly temporary. The Control KPI zone renders active controls with their governance context.

Rendering contract:

The governing rule — no KPI may silently disappear — is enforced structurally. The Workbench does not provide a "delete KPI" action. KPI retirement requires a Decision with an Account (B4), an authority approval, and a mandatory learning summary.

§29.10.3 Intent Progress Indicator Zone

Intent Progress Indicators are slow-moving, aggregated, and reinterpreted more often than redefined. The IPI zone renders strategic continuity.

Rendering contract:

---

§29.11 Orchestration Monitor Components

The Orchestration Monitor renders AI work orchestration state: work specification status, routing decision audit, AICAR cognitive type classification, and delegation scope. The Orchestration Monitor activates at EAS profile only.

Data consumed: QP-ORC-01 (work specifications), QP-ORC-02 (routing decisions), QP-ORC-05 (delegation scope), QP-ACT-01 (actor context).

§29.11.1 Work Specification Status

The Orchestration Monitor renders active and historical work specifications.

Table 29.11.1: Work Specification View

§29.11.2 Routing Decision Audit

Every routing decision in the seven-step resolution engine (§A2) is a governance act with full lineage. The Orchestration Monitor renders routing decisions for audit and review.

Table 29.11.2: Routing Decision View

§29.11.3 AICAR Classification Visibility

The Workbench renders the AICAR cognitive type classification for transparency and audit.

Table 29.11.3: AICAR Classification View

§29.11.4 Delegation Scope Browser

The Delegation Scope Browser renders the delegation landscape for AI actors within the instance.

Table 29.11.4: Delegation Scope View

§29.11.5 Portfolio Browser

The Portfolio Browser renders the recursive instance hierarchy (§23): parent-child relationships, constraint cascade visualization, depth-gated views, and cross-instance aggregation.

Data consumed: QP-PRO-01 (profile status), QP-PRO-02 (instance tree), QP-ACT-01 (actor context), QP-ACT-02 (actor portfolio).

Table 29.11.5: Portfolio Browser Elements

---

§29.12 SHACL Violation Rendering Contract

Every SHACL shape validation result maps to a Workbench rendering. The seventy-nine shapes across five categories (Governance, Actor, Portfolio, Orchestration, KPI) plus the seventeen Phase 1 foundation shapes produce validation outcomes that the Workbench must render consistently.

§29.12.1 Three-Level Rendering Model

The Workbench renders validation outcomes at three severity levels.

Table 29.12.1: Violation Rendering Levels

§29.12.2 Shape-to-Component Mapping

Each SHACL shape maps to the Workbench component that renders its violations.

Table 29.12.2: Shape Category Rendering

The Conformance Dashboard is the universal fallback — every shape violation appears there regardless of which component triggered it. Domain-specific components (Governance Activation Dashboard, Authority Browser, Portfolio Browser, Orchestration Monitor, KPI Dashboard) additionally render violations relevant to their governance concern.

§29.12.3 Remediation Guidance Pattern

Every Blocking violation renders with remediation guidance. The guidance pattern is structured:

1. What failed — the shape URI and a human-readable description of the constraint.
2. Where it failed — the focus node: primitive type, instance identifier, and the specific property that did not satisfy the shape.
3. Why it matters — the invariant or governance rule the shape enforces, and the governance failure that the shape prevents.
4. How to fix it — specific, actionable guidance. For B1 violations: "Link this Work item to a Commitment." For B5 violations: "This Authority has no delegation chain to root. Either mark it as a root authority or establish a delegation from an existing authority."

Remediation guidance is generated from the shape metadata — the shape URI, target class, and property constraints — not from hard-coded strings. This enables custom shapes (§29.4.2) to produce remediation guidance using the same pattern.

§29.12.4 Violation Context Preservation

When a violation occurs, the Workbench preserves the operational context:

• The operation that triggered the violation — which operation was attempted, by whom, when.
• The primitive state at violation time — the focus node's properties at the moment of validation failure.
• The shape that fired — the full shape URI, severity, and enforcement mode.
• The validation pass — Pass 1 (Core), Pass 2 (SPARQL), or Schema Pass.

This context is recorded as Evidence with truth type Authoritative (the validation result is a system fact) and is queryable through QP-INV-02 (violation history).

---

§29.13 Profile-Gated Component Availability

Workbench components activate based on the substrate instance's profile type and graduation stage. No component renders data that the profile cannot produce. No component offers interactions that the profile does not support.

§29.13.1 Profile-Component Matrix

Table 29.13.1: Component Availability by Profile

§29.13.2 Graduation-Gated Rendering

Within a profile, graduation stage determines which component features are available.

Table 29.13.2: Graduation Stage Feature Activation

§29.13.3 PAS Simplification

PAS (Project Accountability Substrate) instances operate with a simplified Workbench. The simplification follows from PAS's bounded scope, limited governance hierarchy, and reduced RACIVG model (Owner + Collaborator instead of full six-role model).

PAS-specific rendering rules:

• Conformance Dashboard renders Pass 1 shapes only. Pass 2 shapes (B5-T, B6-U, B8-routing, B9) render at Logging level — visible in audit views, not in active dashboards.
• Authority Browser renders authority chains (QP-AUTH-01) but does not render full delegation trees (QP-AUTH-02) — PAS authority structures are flat by design.
• Signal routing renders default routes without algedonic bypass controls — PAS delegation depth is typically insufficient to warrant multi-level escalation.
• Governance Activation Dashboard, KPI Dashboard, Orchestration Monitor, and Portfolio Browser do not render at PAS.

---

§29.14 SDK Constraints

SDK constraints are specified as MUST, MUST NOT, and DESIGN SPACE statements. MUST and MUST NOT are implementation requirements. DESIGN SPACE identifies decisions left to substrate implementors.

§29.14.1 Core Layer Constraints

MUST:

1. Enforce Pass 1 SHACL validation (B1–B4, B5-immediate, B6-binding, B8-core) as Blocking on every write operation across all profiles.
2. Enforce the Schema Pass (B7) at deployment time. Deployment MUST fail if any of the 19 primitive classes lacks a signal attachment surface.
3. Return typed ValidationError on Pass 1 failure containing: invariant violated, shape URI, focus node, severity, and remediation guidance.
4. Enforce progressive immutability: fields immutable from their assignment point MUST reject modification attempts.
5. Enforce monotonic truth type promotion (Derived → Declared → Authoritative). Demotion MUST be rejected.
6. Execute composite operations atomically. If any component operation fails validation, no records from the composite are persisted.
7. Record every operation in the audit trail with actor identity, timestamp, operation type, and affected primitive references.

MUST NOT: 8. Allow any profile, configuration, or extension to downgrade a Pass 1 shape below Blocking. 9. Allow any invariant enforcement to be downgraded below Logging for any profile. 10. Persist a primitive record that fails structural validation against its MVR field requirements (§7). 11. Allow AI actors to create records with truth type Authoritative or Declared. All AI-generated records enter as Derived (B3).

DESIGN SPACE: 12. Transport protocol for SDK method invocation — REST, gRPC, native library binding, or other protocols. 13. Concurrency model for simultaneous write operations — optimistic locking, pessimistic locking, or serializable transactions. 14. Pass 2 evaluation scheduling — per-operation, batched, periodic, or event-triggered. The evaluation schedule is profile-configurable within documented bounds.

§29.14.2 Query Layer Constraints

MUST: 15. Expose all forty-four query patterns as typed methods with validated parameters and typed return structures. 16. Include QueryMetadata (query_id, pattern_id, executed_at, execution_ms, language_used, profile_type) in every query response. 17. Enforce depth-gated visibility (§23) on all query patterns. No query may return data from instances outside the caller's authorized visibility scope. 18. Use PaginatedList<T> wrapper for all list-returning patterns with cursor, limit, total, and has_more fields. 19. Return ValidationError on invalid query parameters before query execution.

MUST NOT: 20. Expose SDK-only patterns (QP-AUTH-04, QP-AUTH-05, QP-ACT-04, QP-ORC-03, QP-ORC-04, QP-SIG-04, QP-PRO-03, QP-PRO-04, QP-TMP-02) through the MCP Server. These patterns are internal to SDK consumers. 21. Return stale Validated Projection results without staleness indicators. If a VP is in Stale state, the response MUST include staleness metadata.

DESIGN SPACE: 22. Query engine selection strategy — whether the SDK automatically selects Cypher, SQL, or hybrid execution based on the query pattern, or whether the caller can influence engine selection. 23. Result caching strategy for frequently-accessed query patterns.

§29.14.3 Extension Layer Constraints

MUST: 24. Provide extension registration APIs for content packages, custom shapes, custom patterns, custom operations, and event subscriptions. 25. Validate that custom SHACL shapes do not override, relax, or contradict any of the 79 core shapes. 26. Validate that custom query patterns respect depth-gated visibility (§23). 27. Guarantee at-least-once delivery for event subscriptions. 28. Reject content package activation when the package's declared profile compatibility does not match the instance's profile type.

MUST NOT: 29. Allow extension-defined shapes to reduce the enforcement mode of core shapes. 30. Allow custom operations to suppress or defer invariant validation that would fire on component operations. 31. Allow event subscriptions to block, modify, or intercept governance events. 32. Allow content packages to introduce new primitive types.

DESIGN SPACE: 33. Event delivery mechanism — webhooks, message queues, server-sent events, or polling. 34. Content package distribution mechanism — bundled with SDK, external registry, or file-based loading. 35. Extension namespace management — how application namespaces are allocated, validated, and prevented from colliding.

§29.14.4 Workbench Component Constraints

MUST: 36. Render the Signal Capture entry point on every interface that displays a governed object (B7 enforcement). 37. Render the IQ Capture global entry point on every Workbench screen (§16.7). 38. Render truth type indicators (Authoritative, Declared, Derived, Opaque) on every primitive instance rendering. Derived records MUST carry visible agent attribution. Opaque records MUST carry visible boundary indicator. 39. Render VP-derived content with explicit Derived marking, confidence indicators, and staleness state (§17). 40. Re-render the Decision Surface when any component VP transitions to Stale or Invalidated before human resolution (§17.8). 41. Record the specific VP versions (projection_id + version) in every Decision primitive created from a Decision Surface resolution. 42. Render remediation guidance on every Blocking SHACL violation with: what failed, where it failed, why it matters, and how to fix it. 43. Enforce profile-gated component availability — no component renders data that the profile cannot produce.

MUST NOT: 44. Render Derived and Authoritative records identically. The visual distinction is mandatory. 45. Allow Decision creation from a Decision Surface whose component VPs include any in Invalidated state. 46. Auto-select disposition on a Decision Surface without human selection. Disposition is a governance act. 47. Provide a "delete KPI" action. KPI retirement requires a Decision with Account, authority approval, and mandatory learning summary. 48. Use IQ capture patterns by user for performance evaluation, supervisor visibility without consent, or individual-identifying aggregation (§16.8 pattern privacy).

DESIGN SPACE: 49. Visual design — colors, typography, layout, spacing, responsive breakpoints, accessibility implementation. 50. Interaction patterns — keyboard shortcuts, drag-and-drop, modal flows, command palette implementation. 51. Component rendering technology — web components, framework-specific components, native platform controls. 52. Dashboard layout — fixed, configurable, or role-based arrangement of governance components. 53. Notification and alerting UX — how warnings, invariant signal threshold breaches, and escalation events are presented to users.

---

Scope

Scope limited to logical model specification. Transport protocol, serialization format, and implementation languages are DESIGN SPACE.

Implementation Requirements

SDK implementations MUST respect all invariant shapes, enforce truth type boundaries, and validate all constraints at specified passes. Specification is immutable during lock period. SHACL two-pass validation is mandatory. Truth type boundaries are preserved through all operations. Session isolation is required for all writes.