Conduir - Solution-Level Capability Contracts

Conduir - Solution-Level Capability Contracts

Date: 2026-05-16
Status: Draft solution architecture contract baseline
Purpose: Define major capability/function boundaries so each solution area can be built and validated independently while still composing into the full Conduir ecosystem.

This is the layer above ANATOMICAL-SYSTEM-SPEC.md.

• ANATOMICAL-SYSTEM-SPEC.md defines organ/component membranes.
• This document defines major capability/function boundaries.
• CAPABILITIES.md defines capability inventory and status.
• SUBSTRATE-SEQUENCING.md defines the critical substrate closure order.
• Wire-level truth remains maestro-platform/docs/living-system/08-CONTRACT-SPECS.md.

1. Design Stance

At solution level, Conduir is not a list of services. It is a set of major functions that exchange explicit business and technical contracts:

Mission Experience
  -> Collaborative Execution
    -> Canonical Evidence
      -> Memory and Twin
        -> Preferred Path
          -> Governed Improvement
            -> Safe Exploration
              -> Governance, Compliance, Economics, Observability

The key question at this level is:

Can a whole capability work in isolation, publish its contract, and then plug into the rest of the ecosystem without hidden coupling?

If the answer is no, the boundary is not mature enough.

2. Solution Capability Map

Important framing: SOL-0 is the floor. SOL-9, SOL-11, and SOL-12 are cross-cutting control functions. SOL-1 through SOL-8 are the user-visible/product-learning functions.

3. Solution-Level Anatomy

flowchart TB
    SOL0["SOL-0 Substrate and Trust Foundation<br/>identity, tenant, event fabric, storage, audit"]

    SOL1["SOL-1 Mission Experience and Intake<br/>user/API/MCP entry"]
    SOL2["SOL-2 Collaborative Execution<br/>Symposium, team protocols, LLM/tool planning"]
    SOL3["SOL-3 Canonical Evidence<br/>OutcomeEvent, trace, replay, learning bus"]
    SOL4["SOL-4 Memory and Twin<br/>agent/entity memory, user twin"]
    SOL5["SOL-5 Preferred Path<br/>route maturity, rationale, personalization"]
    SOL6["SOL-6 Reuse Library<br/>blocks, templates, provenance"]
    SOL7["SOL-7 Governed Self-Evolution<br/>proposal, apply, rollback"]
    SOL8["SOL-8 Exploration and Simulation<br/>side-lanes, what-if, blueprint"]

    SOL9["SOL-9 Governance Control<br/>tiers, budgets, kill switch, policy"]
    SOL10["SOL-10 External Integration<br/>adapters, MCP, provider/tool boundaries"]
    SOL11["SOL-11 Economics and Observability<br/>costs, SLOs, vitality"]
    SOL12["SOL-12 Data Lifecycle and Compliance<br/>retention, forget, lineage"]

    SOL1 --> SOL2
    SOL2 --> SOL3
    SOL3 --> SOL4
    SOL4 --> SOL5
    SOL5 --> SOL2
    SOL2 --> SOL6
    SOL6 --> SOL2
    SOL3 --> SOL7
    SOL8 --> SOL7
    SOL7 --> SOL2

    SOL9 -. governs .-> SOL1
    SOL9 -. governs .-> SOL2
    SOL9 -. governs .-> SOL5
    SOL9 -. governs .-> SOL7
    SOL9 -. governs .-> SOL8

    SOL10 --> SOL1
    SOL10 --> SOL2
    SOL10 --> SOL7

    SOL11 -. observes .-> SOL1
    SOL11 -. observes .-> SOL2
    SOL11 -. observes .-> SOL3
    SOL11 -. observes .-> SOL7

    SOL12 -. constrains .-> SOL3
    SOL12 -. constrains .-> SOL4
    SOL12 -. constrains .-> SOL6

    SOL0 === SOL1
    SOL0 === SOL2
    SOL0 === SOL3
    SOL0 === SOL4
    SOL0 === SOL5
    SOL0 === SOL6
    SOL0 === SOL7
    SOL0 === SOL8
    SOL0 === SOL9
    SOL0 === SOL10
    SOL0 === SOL11
    SOL0 === SOL12

4. Capability Boundary Standard

Every major capability must publish a solution contract with this shape:

Rule: a capability is not solution-ready until its produced contracts can be consumed by the next capability without translation, hand-patching, or undocumented assumptions.

5. Capability Contracts

5.0 — Ownership of the Constitutional Surface (disambiguation note)

The "Tier-Forbidden floor" and "protected paths" are referenced across SOL-0, SOL-7, and SOL-9. To eliminate ambiguity:

So: SOL-9 declares, SOL-0 enforces, SOL-7 honours. Three roles, one floor.

SOL-0 - Substrate and Trust Foundation

Hard boundary: no higher capability may create its own identity, event, audit, or tenant-isolation mechanism. The Tier-Forbidden floor is enforced here, never delegated.

SOL-1 - Mission Experience and Intake

Boundary rule: SOL-1 presents and validates. It does not decide the execution route or write learning memory.

SOL-2 - Collaborative Execution and Cognition

Boundary rule: SOL-2 is the brain for a mission, not the memory, not the policy source, and not the tool itself.

SOL-3 - Canonical Evidence and Learning Bus

Boundary rule: every learning claim begins here. If SOL-3 did not validate it, no downstream capability should treat it as evidence.

SOL-4 - Entity, Agent, and User Memory

Hard boundary: user twin data must not be written into agent memory; agent learning must not become user preference without consent.

SOL-5 - Preferred-Path Orchestration

Boundary rule: SOL-5 recommends. SOL-2 executes. SOL-9 governs allowable autonomy.

SOL-6 - Reuse and Strategic Asset Library

Boundary rule: SOL-6 supplies reusable starting points. Catalogue activation applies an explicit,
asset/version-bound approval whose product evidence and independent approver are attested by the
product adapter and revalidated by the canonical service; it does not silently mutate mission
execution or merge production code. Retirement remains advisory until the external lifecycle
authority applies it.

SOL-7 - Governed Self-Evolution

Hard boundary: SOL-7 may never mutate identity, audit, governance, or tenant isolation machinery through AI-driven apply.

SOL-8 - Exploration and Simulation

Boundary rule: SOL-8 explores. SOL-7 graduates. SOL-9 governs. Main-lane state is protected until approval.

SOL-9 - Governance Control Plane

Hard boundary: governance can bias all capabilities, but only humans in authorized roles can mutate governance state. The floor is declared here; enforced by SOL-0; honoured by every actuating SOL.

SOL-10 - External Integration Fabric

Boundary rule: external systems are plug-ins, not trusted organs. All outputs must be normalized and sanitized.

SOL-11 - Economics and Observability

Boundary rule: SOL-11 observes and accounts; it does not paper over missing evidence with status claims.

SOL-12 - Data Lifecycle and Compliance

Boundary rule: data may be useful, but not all useful data may be retained.

6. Solution Boundary Catalogue

These are the major capability-to-capability handshakes. Component contracts may sit underneath them, but these are the solution contracts PMs, architects, and engineering leads should track.

7. Solution-Level Execution Flows

7.1 Mission-To-Learning Flow

SOL-1 Mission Experience
  emits NormalisedMission
    -> SOL-2 Collaborative Execution
      emits OutcomeEvents
        -> SOL-3 Canonical Evidence
          writes DecisionMemory/Twin candidates
            -> SOL-4 Memory
              returns recall/twin context
                -> SOL-5 Preferred Path
                  returns RouteRationale to SOL-2

Success condition: the second similar mission chooses or explains a better route because of evidence from the first mission.

7.2 Reuse Flow

SOL-2 Execution produces useful artifact
  -> SOL-3 Evidence validates outcome
    -> SOL-6 Reuse Library records ArtifactCandidate
      -> promotion policy evaluates ReusePullEvent + efficacy
        -> SOL-2 later pulls ReusableBlock

Success condition: a block can be promoted, pulled, cited, and demoted from evidence.

7.3 Governed Self-Evolution Flow

SOL-3 Evidence or SOL-8 Exploration detects improvement
  -> SOL-7 creates MoveProposal
    -> SOL-9 Governance approves/rejects by tier
      -> SOL-7 EvolutionApplier dry-runs and writes RollbackRecord
        -> apply
          -> SOL-11 observes
            -> regression signal rolls back if needed

Success condition: apply applies, rollback rolls back, and audit can prove both.

7.4 Exploration Flow

SOL-9 sets exploration budget
  -> SOL-8 runs isolated side-lane
    -> SOL-3 validates side-lane OutcomeEvents separately
      -> SOL-8 scores ObjectiveScore
        -> winner becomes MoveProposal through SOL-7

Success condition: side-lane evidence cannot alter main-lane route state until governance graduation.

7.5 Data Lifecycle Flow

SOL-12 receives retention/export/delete trigger
  -> checks PrivacyScope, legal hold, audit policy
    -> issues ForgetEvent or RetentionAction
      -> SOL-4 deletes/exports memory and twin records
        -> SOL-3/SOL-11 preserve audit/replay policy
          -> SOL-12 emits EliminationProof

Success condition: user data can be exported or forgotten without deleting immutable audit.

7.6 Conscience Reflection Flow (mid-horizon)

SOL-3 emits EvidenceEvent stream
  -> Conscience module (cross-cutting; proposed owner)
       reads stream + GovernancePolicy + audit chain
    -> evaluates "did we act consistently with stated values?"
      -> emits ConscienceReflection { judgement, rationale, recommendation }
        -> route to:
           - SOL-9 (governance update proposal)         if policy gap
           - SOL-7 (MoveProposal for behaviour change) if pattern change needed
           - SOL-12 (data-lifecycle adjustment)         if retention/forget gap
           - SOL-11 (vitality alert)                    if drift trending wrong
        -> if MoralInjury detected (system was forced to violate values):
           - emit MoralInjuryRecord -> Z4 audit chain (indefinite)

Success condition: the system surfaces questionable patterns before the next external audit cycle catches them. Maps to VF-14 in VISION-TOP-DOWN-MAPPING.md.

7.7 Sunset / Instance Mortality Flow (mid-horizon)

Health signals -> SOL-11 trend analysis (vitality, incident rate, debt)
  -> threshold-crossing or scheduled lifecycle review
    -> SOL-9 evaluates SunsetVerdict candidate
      -> org-board signs SunsetVerdict
        -> SOL-0 + SOL-1 enter draining mode (no new missions)
          -> SOL-7 + SOL-5 + SOL-4 export inheritance payload
            -> successor instance imports (see 7.8)
              -> in-flight missions complete or migrate
                -> SOL-12 runs final retention cycle
                  -> SOL-0 seals audit chain
                    -> decommission

Success condition: an unhealthy instance is retired gracefully (drained, succession run, audit preserved) without firefighting. Maps to VF-15.

7.8 Cross-Instance Succession Flow (long-horizon)

Parent instance (sunsetting)
  -> exports inheritance payload:
       - AgentDNA (generalised, anonymised)
       - DecisionMemory (per-tenant scoped)
       - Routing-pattern templates (anonymised)
       - Immune memory (attack signatures)
       - GovernanceState (signed version)
       - Audit-chain seal
       - Replay-tape index
  -> Successor instance imports under:
       - constitutional-ancestor-hash match (required)
       - cryptographic signing per artefact
       - tenant-consent verification (per-twin)
  -> Succession handshake: 8 steps (see ANATOMICAL-SYSTEM-SPEC.md §10.2)
  -> Parent ceases ops only after successor vitality > 70

Success condition: lineage continues, audit + replay survive, no tenant-data leak across instances. Maps to VF-15 + (when present) VF-16. The two-parent variant (AI-EVOLUTION-MORALITY-MORTALITY.md Part 1) builds on this single-parent foundation.

8. Solution-Level Acceptance Gates

Minimum solution-ready standard: G1-G7.
Minimum product-claim standard: G1-G10.

9. Capability Isolation Test Harness

Each major function should have a contract fixture pack:

fixtures/
  sol-1-mission-experience/
    valid_mission_request.json
    invalid_missing_actor.json
    oversized_payload.json
  sol-2-execution/
    normalised_mission.json
    route_rationale.json
    memory_recall_result.json
  sol-3-evidence/
    outcome_event.success.json
    outcome_event.failure.json
    outcome_event.invalid_schema.json
  ...

For each SOL capability, require:

10. Priority Order

This is the solution-level order. It mirrors the substrate sequencing but lifts it to capability readiness.

11. Open Solution Decisions

12. Cross-Walk Pointer

For the full dialect cross-walk (SOL ↔ CAP ↔ VF ↔ Six-layer spine ↔ suite ↔ milestone ↔ anatomy organ ↔ substrate seam), see 00-CONDUIR-MASTER-ARCHITECTURE.md §3.6. That table is the canonical translation surface; do not maintain a local copy here.

For the vision counterpart of each SOL (VF-1..VF-16), see VISION-TOP-DOWN-MAPPING.md (VISION-TOP-DOWN-MAPPING.md) §4B (alias table) — every SOL maps to one or more VFs, and three VFs (VF-13 Self-Model, VF-14 Conscience, VF-15 Mortality) have no current SOL and are flagged for promotion.

13. Maintenance Contract

14. Bottom Line

At component level, the question is "does this membrane validate?"

At solution level, the question is "does this capability publish a stable business contract that neighboring capabilities can trust?"

The load-bearing solution contracts are:

1. SOL-1 -> SOL-2: valid mission to execution
2. SOL-2 -> SOL-3: execution to canonical evidence
3. SOL-3 -> SOL-4: evidence to scoped memory
4. SOL-4 -> SOL-5: memory to preferred route
5. SOL-5 -> SOL-2: route rationale back to execution
6. SOL-8 -> SOL-7 -> SOL-9: exploration to governed improvement
7. SOL-12 -> SOL-4/SOL-3: lifecycle policy over all data
8. SOL-0 -> all: substrate identity, signal, isolation, audit (and Tier-Forbidden floor enforcement)

If these contracts hold, individual capabilities can be developed independently and still join the organism. If they do not, isolated components will demo well and fail when assembled.