Make the Harness DSL state only executable contracts

Traceability

• Spec ID: harness-dsl-v0.3-semantic-contraction
• Status: Implemented

Intent

Replace the v0.2 authoring surface that mixes executable requirements with prompt-only intent. The v0.3 language keeps the existing Source -> IR -> Revision -> Materialization -> Receipt trust chain, but makes the authored contract smaller and falsifiable:

• source files identify their language version;
• deployments bind one harness to one runtime in source;
• a workflow either describes the single session the shipped adapters really run, names a programmatic controller, or declares a state machine that only a proven orchestration adapter may accept;
• capability requirements are satisfied in their native dimension (delivered, exposed, or connected) instead of sharing a synthetic strength ladder; and
• tool contracts have an identity that an adapter exposure must match.

Author-facing permissions, free-form settings, capability bindings, and tool input/output name lists are removed because no shipped adapter enforces or consumes them. Runtime permission callbacks and executor options remain owned by the runtime APIs that actually apply them.

Acceptance Scenarios

• AC-1 — Versioned source: every v0.3 source starts with language 0.3. Compilation rejects a missing or unsupported source version with a structured, source-qualified diagnostic, and the lowered bundle uses irVersion: 0.3.0.
• AC-2 — Honest workflow modes: workflow x \{ session coder \} is the portable single-session form. It must name exactly the one agent in every using harness. A state-machine workflow declares an entry agent and typed outcomes; compilation rejects unknown outcomes, missing entries, unreachable agents, and stop-free graphs. Shipped Qoder and Pi descriptors support only session, so a state machine fails resolution instead of becoming prompt prose. Programmatic workflows retain descriptor-owned language gating.
• AC-3 — Kind-specific satisfaction: requirement syntax contains no preferred, minimum, or on-degrade. A skill resolves only when delivered, a tool only when an exact tool contract is exposed, and an MCP only when connected. Missing realization fails resolution. Revision, report, and receipt entries record dimension, state, mechanism, and reason without a cross-kind strength value.
• AC-4 — Explicit composition: a named deployment references exactly one harness and one declared runtime. Compilation rejects duplicate deployment ids and duplicate harness/runtime pairs. Resolution accepts only a pair declared by a deployment and records the deployment id/hash in the revision.
• AC-5 — Tool contract identity: the standard tool ids have frozen builtin contract ids and may be referenced without a local declaration. Any other tool must declare a non-empty contract string. Adapter tool exposure states both the host tool and contract id; a missing or mismatched contract fails resolution. The removed input/output identifier lists no longer imply a schema the runtime does not validate.
• AC-6 — Removed inert syntax: v0.3 rejects binding, target, runtime execution, requirement strength/degradation blocks, capability permissions, harness configure, and tool input/output. No v0.3 IR or materialization receipt carries author settings or requested/enforced permission claims.
• AC-7 — Trust-chain preservation: revisions remain deeply frozen and bind harness, deployment, runtime/adapter descriptor, workflow, capabilities, source locks, and optional component snapshot provenance. Executor preflight still rejects revision, bundle, adapter, or source drift before SDK load.
• AC-8 — One teaching contract: package examples, README, highlighting, generation skill, validator, tests, and current in-repo consumers describe only v0.3 syntax and distinguish core, adapter, and devtool ownership.

Non-goals

• Implementing a state-machine scheduler, per-agent host sessions, structured outcome extraction, or handoff payloads. The language may describe that contract, but shipped adapters must reject it until an executor proves it.
• Adding MCP support, new host adapters, or new standard tool contracts.
• Designing a general policy language, adapter configuration language, package registry, dependency solver, or JSON-Schema transport for custom tools.
• Migrating persisted v0.2 revisions or compare evidence. Their irVersion remains the discriminator; v0.3 code must reject them rather than reinterpret them.
• Changing npm package versions, release metadata, changelog, roadmap, or publication workflow.

Plan and Tasks

1. Change the Langium grammar and generated artifacts: add the language header, session/state-machine workflow forms, agent outcomes, tool contracts, and deployment; remove target, binding, strength, permissions, settings, and tool input/output syntax.
2. Bump the IR contract to 0.3.0. Replace target/binding/strength data with deployments, kind-specific realization state, tool contract ids, and the deployment-bound revision shape.
3. Update compiler validation/lowering for source version, workflow outcome and reachability checks, standard tool synthesis, custom tool contracts, and deployment uniqueness.
4. Update resolver and adapter descriptors so exact capability facts decide availability. Preserve source locks, adapter identity/hash checks, deep freezing, and component snapshot provenance.
5. Update executor materialization and preamble generation. Session workflows add no fake control-flow prompt; unsupported workflow modes fail before SDK load.
6. Migrate all package examples, the generation skill and validator, package docs, highlighting grammar, compare/experiment/UI consumers, and fixtures.
7. Regenerate Langium sources and validate focused behavior, package gates, module boundaries, documentation links, and the repository test surface proportionate to the changed public contract.

Test and Review Evidence

• AC-1/AC-2/AC-4/AC-5/AC-6: compiler tests assert parsed IR and structured diagnostics from behavior, including missing version, invalid workflow outcome/reachability, undeclared custom tool, contract mismatch, undeclared deployment pair, and removed v0.2 syntax.
• AC-3: resolver tests cover delivered skill, exposed exact-contract tool, connected MCP, and each unavailable/mismatched path. Receipt tests assert the dimension/state/mechanism shape with no strength fields.
• AC-7: existing revision, source-lock, adapter drift, executor preflight, and source-delivery tests remain green after fixture migration.
• AC-8: compile and resolve every shipped .harness example, run the generation-skill tests, npm run check:generated, package build/typecheck/test, targeted package consumers, and the Markdown doc-link graph after docs move or link changes.
• Risk — breaking source language: all v0.2 files fail under v0.3. Mitigate with the explicit header, actionable diagnostics where parsing permits, a before/after README example, and migration of every in-repo source in the same change.
• Risk — false orchestration claim: a descriptor could claim state-machine support before an executor implements it. Mitigate by keeping shipped descriptors session-only and preserving registry/live-descriptor drift tests; adding support requires its own execution spec and runtime evidence.
• Risk — consumer shape drift: UI/compare/experiment fixtures may embed revision or receipt shapes. Validate parsed persisted artifacts and consumer tests rather than relying on TypeScript compilation alone.
• Risk — cross-platform generated output: regenerate through the repository Langium command and run existing Windows-portable behavior tests; do not add shell-dependent runtime behavior.

Implementation Evidence

• AC-1/AC-2/AC-4/AC-5/AC-6: packages/harness/test/compile.test.ts, resolve.test.ts, and sugar.test.ts exercise the language header, workflow modes/outcomes/reachability, explicit deployments, exact tool contracts, and rejection of removed v0.2 syntax through compiler/resolver behavior.
• AC-3/AC-7: resolver, revision, materialization, executor, adapter, and skill-delivery tests cover kind-specific facts, deployment/content hashes, descriptor drift, source locks, deep freezing, and pre-SDK failure.
• AC-8: examples, README, Shiki grammar, generation skill/reference/ validator, harness-ui fixtures, and compare/experiment fixtures use v0.3.
• npm run harness:test: 17 test files, 156 tests passed.
• npm run harness-ui:test: 3 test files, 29 tests passed.
• npm test: 95 root test files, 1325 tests passed.
• npx vitest run test/skills-docs/doc-link-graph.test.mjs: 1 test file, 6 tests passed after regenerating the routing graph (no graph diff).
• npm run pack:verify: npm and runtime-zip verification passed.
• node skills/generate-harness-dsl/scripts/validate.mjs resolves both minimal.harness and standard-coding.harness; full-surface.harness exits non-zero with explicit state-machine, MCP, custom-tool, and program-controller limitations, as intended.
• Two consecutive npm run langium:generate runs produced identical SHA-256 hashes for all generated files. The repository check:generated wrapper compares against HEAD, so it reports the intended uncommitted generated diff until this change is staged or committed.
• Current harness-studio verification is unavailable because unrelated concurrent checkpoint-history edits changed /api/config without updating its existing exact-shape assertion: the build passes and 44 of 45 tests pass, while test/server.test.ts still expects no historyEnabled field. Before those edits changed during this work, all 45 tests passed.