# Stage 1: Foundation contract

This document is the implementation specification for Stage 1 of the
[long-term roadmap](../dsh-control-plane-roadmap.md). It defines public,
runtime-neutral records. It does not start a Runtime, read a Profile, mount a
Cordis Service, or render a DSH Client panel.

## Contract envelope

Every record has:

```json
{
  "kind": "runtime",
  "schemaVersion": "1.0",
  "id": "runtime.fixture.official"
}
```

At Stage 1, `kind` was stable and selected six public records. Later roadmap
stages may add compatible contract kinds, such as the Stage 5 `scenario` record:

- `runtime`: an adapter-backed Runtime registration and capability summary;
- `profile`: a named DSH Profile reference under a Runtime;
- `preset`: a session composition reference and safe permission declaration;
- `session`: lifecycle metadata and links, never transcript content;
- `plan`: structured work items and links to Sessions or References;
- `knowledge-reference`: a pointer to an external source, never its contents.

The normative JSON Schemas live in `schemas/`. The dependency-free runtime
validator and JSON round-trip helpers live in `src/contracts/index.mjs`.

## Version and compatibility

`schemaVersion` uses `major.minor` syntax. Writers emit the current `1.0`
version. Readers accept any valid minor version with the same major because
minor revisions are additive. Unknown fields are retained during a validated
parse/serialize round trip and must still be plain JSON and public-safe. A
major version change is incompatible and requires an explicit migration.

This is a control-plane contract version, not a claim that every DSH release
implements these records. The current local DSH observation is version
`0.1.0-rc.8`; its `dsh.bundle.patch`, Host, Client, and Profile contracts are
version-qualified integration inputs for a later stage.

## Boundary rules

Records are JSON-safe plain objects: null, booleans, finite numbers, strings,
arrays, and plain objects only. They reject functions, class instances,
cycles, `undefined`, non-finite numbers, and prototype-bearing objects.

Public records contain identifiers, labels, statuses, capabilities, timestamps,
and opaque references. They do not contain:

- absolute paths, real `DSH_HOME` values, ports, credentials, or environment
  values;
- raw Session messages, complete Context/Service/Snapshot objects, or logs;
- Knowledge contents or private repository material.

`locationRef`, `profileRef`, `promptRef`, and Knowledge `ref` are opaque
references such as `fixture://...` or `local-config://...`; local resolution is
owned by a later adapter and never serialized into the public record.

## Fixtures and acceptance

`examples/contracts/*.fixture.json` uses synthetic IDs and timestamps only.
Fixtures are standalone JSON and do not depend on a local Profile or private
Knowledge provider. The Stage 1 test suite covered all six records,
round-trip preservation, version compatibility, malformed data, unsafe values,
and schema-file parseability.

Stage 1 is complete only when the fixtures validate without a machine
configuration, the safe-core scan passes, and the contract tests pass. Runtime
lifecycle, allowlisted process adapters, DSH Bundle loading, Host/Client RPC,
Slot registration, and UI behavior remain later-stage work.