# Architecture

## Layers

```text
Control Plane Core
  ├─ Runtime Registry
  ├─ Profile / Preset Registry
  ├─ Session Bridge
  ├─ Plan / Artifact / Knowledge Reference Bridge
  ├─ Scenario Adapter Registry
  └─ Health and lifecycle state
          │
Runtime Adapter Layer
  ├─ Official DSH adapter
  ├─ Customized DSH adapter
  ├─ Development DSH adapter
  └─ Explicit custom adapters
          │
DSH Runtime
  ├─ Profile
  ├─ Preset
  └─ Session
```

## Ownership

### Control plane core

Owns runtime-neutral identifiers, adapter registration, lifecycle state,
health summaries, and references to plans, artifacts, and knowledge. It must
not own credentials, raw transcripts, or arbitrary process execution.

### Runtime adapter

Owns the mapping from a public `RuntimeNode` to one local DSH installation.
Each adapter exposes an allowlisted `inspect`, `start`, `stop`, and `health`
operation. The adapter receives validated configuration; it does not accept an
unbounded command string from the UI.

### DSH Host integration

Owns the process-side Service and the narrow RPC needed by the Client. It may
read DSH-supported registries and expose scalar summaries. Provider placement
must follow the target DSH's Host composition rules.

### DSH Client integration

Owns browser presentation, Slot registration, local presentation state, and
theme-scoped styles. It uses additive Slots and independent failure boundaries.
It must not replace the DSH root, conversation, or sidebar tree unless a later
ADR explicitly proves that replacement is required.

## Package contract target

The current local DSH `0.1.0-rc.8` inspection shows the following public plugin
shape in existing bundles:

```json
{
  "exports": {
    ".": "./lib/index.js",
    "./client": "./lib/client.js",
    "./cordis.patch.yml": "./cordis.patch.yml",
    "./package.json": "./package.json"
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["<verified-dsh-client-package>"]
    }
  }
}
```

The Stage 3 package currently implements this shape as one installable
`dsh-control-plane` package. It exports `./client` and `./typert`, and its
`cordis.patch.yml` inserts one additive Loader row. The `packages/` tree is
internal source composition for the checked-in browser bundle, not a set of
required sibling packages at install time.

This is a version-qualified observation, not a promise that all future DSH
versions accept the same fields. A future compatibility update must re-check
the installed package contracts and extend the supported version matrix.

## Reference bridge

The Stage 4 bridge is a metadata graph, not a content transport. Plans,
Artifacts, and Knowledge References link through bounded identifiers and opaque
references. A reference-only Provider can list and describe those records, but
has no synchronization or upload operation. Markdown is treated as the
preferred source format for future adapters; this repository does not read the
Markdown body.

The DSH Host turns the graph into four read-only projections: Plan Panel,
Artifact Board, Knowledge Reference Catalog, and Scenario Catalog. Each Client contribution is
an additive Settings Slot with its own effect, disposer, error boundary, and
recovery behavior.

## Scenario adapters

Scenario adapters are replaceable metadata producers. The built-in adapters use
one protocol for Generic Project, Developer Workspace, BrandOS, and Interview
Learning. They return bounded topic/question-set summaries plus Plan, Session,
Artifact, Knowledge Reference, and source provenance links. They do not read
directories, fetch repositories, upload question content, or mutate Sessions.

External sources carry a pinned commit and an explicit license status. An
unknown license is preserved as `unknown`; the control plane never infers a
license from a repository name or silently republishes upstream content.

## Cross-boundary data

Host-to-Client messages are JSON-safe and minimal. They may contain identifiers,
labels, statuses, capabilities, timestamps, and error codes. They must not
contain live Cordis Contexts, Services, React elements, functions, class
instances, credentials, raw logs, or complete Session data.

## Lifecycle

Every optional registration is owned by its Cordis fiber or explicit lifecycle
controller. The acceptance surface includes activation, absent optional
dependency, Slot collision, render failure, stop, unload, reload, disable, and
recovery.