Contracts

Every boundary in Astrolabe is a TypeScript interface in @astrolabe/core (no runtime dependencies). Implementations live in other packages and can be replaced. This page maps the contracts; the source files are the reference.

                      ComponentManifest (data, one per type)
            /                     |                      \
 ComponentDefinition      PlayerElementApi        EditorDescriptor
 (engine side)              (player side)           (authoring side)
        |                         |                        |
     Engine  ----- view ----> <astl-player> <---- EditorAdapter (your WYSIWYG)
        |                         |
   AnswerKey <--- grade ---- Checker (local or HTTP: grading protocol)

Contracts (file)	Implemented by	Purpose
`ComponentManifest`, `AttributeSpec`, `ChildSpec`, `ScoringSpec` (`manifest.ts`)	each component	the only per-type schema: attributes with visibility, children, scoring modes, issue codes, a11y pattern, CSS parts
`ComponentDefinition`, `ValidateContext`, `CompileContext`, `SlotSpec` (`definition.ts`)	each component	validate an element, produce slots + keys, produce the public view element
`SlotKind`, `NormalisationProfile`, `GradeContext` (`slots.ts`)	engine built-ins + yours	open registry of grading semantics
`ScoringRule`, `ScoringGroup` (`scoring.ts`)	engine	all-correct / per-slot / proportional
`Engine`, `EngineOptions`, `CompileResult`, `ValidationReport` (`engine.ts`)	`@astrolabe/engine`	validate, compile, grade, solution, describe
`AnswerKey`, `Metadata`, `Compilation` (`compiled.ts`)	engine	compile outputs
`Answers` (`answers.ts`)	everyone	strings keyed by slot id
`GradeResult`, `GroupResult`, `Solution` (`result.ts`)	engine	what students and hosts see; no key data
`Checker`, `CheckRequest`, `CheckResponse`, `SubmitRequest`, `SubmitResponse`, `CheckerError` (`checker.ts`)	`localChecker` (engine), `httpChecker` (player), yours	how a player gets verdicts
`ProblemDetails`, `ProblemCode`, `ProtocolPath` (`protocol.ts`)	`@astrolabe/server`, yours	HTTP binding of the checker (protocol 1)
`AttemptPolicy` (`policy.ts`)	hosts	practice / test / review, navigation, checks, deadline, pass mark, reveal
`Snapshot` (`snapshot.ts`)	player	restore an attempt after reload
`PlayerElementApi`, `ElementContext`, `ElementFeedback`, `PlayerEvent` (`player.ts`)	each component element	how `<astl-player>` talks to elements
`SourceCompiler` (`player.ts`)	`astrolabe.js`, yours	turns a light-DOM source with answers into a view and a checker (HTML with answers)
`EditorDescriptor`, `InspectorField`, `EditorAdapter` (`authoring.ts`)	components; your WYSIWYG	editor-agnostic authoring
`Issue`, `IssueLocation`, `EngineIssue` (`issues.ts`)	engine + definitions	validation results as codes + params
`MessageCatalog`, `MessageFormatter`, `I18n` (`i18n/types.ts`)	core (`createI18n`, `icuFormatter`)	UI strings, ICU MessageFormat 1
`ElementNode`, `TextNode` (`ast.ts`)	engine	the document tree definitions work on

Stability

Contracts are versioned with the packages (semver). Wire formats carry their own versions: content format (<astl-doc format="1">), element v, AnswerKey.format, Snapshot.format, PROTOCOL_VERSION.
Stored views and keys are immutable. A newer player must render every older view version of its elements; ComponentDefinition.migrations upgrades old sources.
Conformance fixtures (packages/components/src/<type>/fixtures) are the executable contract for engine ports.