An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 1 kind: system-spec id: spec:AST-031 authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null phase: proposed owners: [josephfarina, cixzhang] affects_architecture: [architecture:cli-surface] affects_families: [] affects_contributing: [] affects_consumer_docs: [authoring]
Runtime integration feature composition system spec
Intent
Define reusable composition rules for runtime integration features — CLI
capabilities that an integration can contribute alongside its default manifest.
Each feature is a named export from the integration module and an optional
matching field in astryx.config. Multiple handlers compose additively: every
configured eligible handler runs in isolation, failures are reported per handler, and
the feature defines one aggregate command outcome without letting one handler
silence the others.
This spec captures the general composition contract first, then records the
requirements specific to gapReport, the first feature built on it.
Non-goals
- Replace the default-export manifest or its contribution model (components,
templates, codemods, docs). Those are loaded by the
Projectseam and are outside this scope. - Define transport protocols, network destinations, or persistence formats for any handler.
- Provide a plugin system with lifecycle hooks, dependency ordering, or inter-handler communication.
Requirements
General composition rules
The following rules apply to every runtime integration feature that follows
this spec. A feature is identified by a named export from
astryx.integration.{ts,mjs,js} and optionally a matching field in
astryx.config.
Named export + matching project config field
A feature is declared as a named export from the integration module.
The same feature may also appear as a field in the consumer's
astryx.config for project-level handlers. Older CLI versions that do not
recognize the named export ignore it and continue loading the default manifest.
Additive composition
Every handler in the effective set receives an ordered delivery outcome. The
project handler comes first, then each integration handler in the order the
integrations appear in astryx.config. An eligible handler runs; a public
handler without consent records consent_required without being called. No
handler overrides or displaces another.
Identity dedupe by handle function
When the same handle function reference appears more than once in the
effective set (e.g. a project config re-exports an integration's handler), it
runs exactly once, at the position of its first occurrence.
Per-handler structuredClone copy
Each handler receives its own structuredClone copy of the event. A handler
that mutates its input cannot affect any other handler.
Failure isolation + aggregate response
A handler that throws, times out, or misbehaves produces a failed delivery for that handler. Later handlers still run. The command's aggregate response collects a per-handler delivery record so the caller can see exactly which handlers succeeded, which failed, and why.
Lifecycle / async
- Timeout: each handler has a 30-second wall-clock timeout and receives an
AbortSignalthat fires when that budget expires. - Async: handlers may be async; the CLI awaits each one.
- Execution order: handlers run sequentially in effective-set order. A handler's failure does not skip subsequent handlers.
Per-handler consent metadata
Each handler declares an audience of 'internal' or 'public'. The CLI
enforces consent per handler: a public-audience handler is not invoked
unless the caller has explicitly confirmed the public write. An internal
handler requires no additional confirmation.
Inspectable consent (consent_required delivery)
When the caller has not confirmed consent and a handler requires it, the CLI
records a consent_required delivery for that handler without calling it. The
caller can inspect which handlers would need consent before re-running with
confirmation.
Fallback behavior
A built-in fallback (e.g. opening a GitHub issue via issuesUrl) activates
only when the effective handler set is empty after deduplication. The
presence of any configured handler — project or integration — suppresses the
fallback entirely.
issuesUrl is target metadata
issuesUrl on an integration manifest or project config describes the
destination for human-readable issue links. It is metadata about the target
package, not a handler implementation. Handlers use it as context; the CLI
uses it for fallback routing.
Mutation-sensitive tests
Tests for a feature built on this composition model MUST cover the fan-out order, isolation, deduplication, timeout, consent gating, consent-required inspection, fallback suppression, and aggregate response shape. Removing a fail-closed guard MUST break a test.
Gap-report-specific requirements
gapReport is the first feature built on the general composition rules above.
FR1 — Handler type. A gap-report handler is a plain object conforming to
GapReportHandler:{ audience: 'internal' | 'public', handle: (event: GapReport, context: { signal: AbortSignal }) => GapReportHandlerReceipt | Promise<GapReportHandlerReceipt> }.GapReportHandlerreplacesGapReportWriter.FR2 — Event shape. The
GapReportevent carriesschemaVersion: 1, plain camelCase field names, normalized values, and atargetobject with{ package, version, issuesUrl }. No snake_case, no abbreviations, no nested debug context.FR3 — Receipt contract. A handler MUST return a
GapReportHandlerReceipt:{ status: 'filed' | 'routed_only' | 'skipped', url?: string, message?: string }. No other status values are accepted.urlandmessageare optional and carry human-readable context.FR4 — Handler isolation. Each handler runs in isolation:
- Each handler runs in its own worker.
stdoutis redirected tostderr, andprocess.exit,process.exitCode, and late promise continuations are contained in that worker. - A throw or timeout (30 s) produces a failed delivery for that handler. The CLI aborts the handler's signal, then terminates its worker before starting the next handler.
- A failed handler does not affect the command's own exit code or other handlers.
- Each handler runs in its own worker.
FR5 — No inherited-handler opt-out. There is no opt-out mechanism for gap-report handlers analogous to
inheritDebug. Every internal handler in the effective set runs, and every public handler receives an outcome subject only to the explicit consent gate. TheinheritDebugfield inpackage.jsonis a compatibility exception specific to thedebugfeature (see Decision log DEC-2); it does not set a precedent for other features.FR6 — Effective set. The effective handler set is: project config's
gapReporthandler first (if present), then each integration'sgapReportnamed export inastryx.configintegration order. Deduplication is byhandlefunction identity.FR7 — Target selection. The target package for the gap report is selected by: explicit
--packageflag → the unique component owner when only one package owns the component → Core as the default. Target selection is not based on handler count or handler source.FR8 — Built-in GitHub fallback. When the effective handler set is empty (zero handlers after deduplication), and the target has a GitHub
issuesUrl, the CLI offers to file viagh issue create. This fallback is consent-gated (publicaudience). Any otherissuesUrlscheme produces arouted_onlyreceipt. The fallback is suppressed entirely when at least one handler exists.astryx swizzle's receipt offers itsgh issue createline whenghis on PATH, whatever its login state. A logged-outghasks for its own login when the line runs. The text receipt shows the command; the JSON receipt keeps the command and the issues URL.FR9 — Project config field.
astryx.configgains agapReportfield accepting aGapReportHandler. This is the project-level handler and runs first in the effective set.FR10 — Integration named export. An integration declares its handler as
export const gapReport: GapReportHandlerfrom its integration module. The named export is deliberately not a default-manifest field, consistent with thedebugfeature's export convention.FR11 — Per-handler consent. Each handler's
audienceis evaluated independently. A fan-out with mixed audiences invokesinternalhandlers unconditionally and gatespublichandlers on caller consent. Ungated handlers still run even when a gated sibling is blocked.FR12 — Aggregate response. The command's response includes a
deliveriesarray with one entry per effective handler or fallback. Each delivery recordshandlerType,handler,audience,status,url, andmessage. The response shape is the same in--jsonand human output modes.FR13 — A destination the caller names. When the caller names a destination with
--to, that destination replaces the handlers and the FR8 fallback for that report.architecture:cli-surfaceINV36 governs the option and who chooses the destination.
Platform support
- Supported: Node >= 22.13, any OS the CLI supports.
- Unsupported: handlers that depend on network access, native binaries, or platform-specific APIs are the handler author's responsibility; the CLI provides isolation but not capability detection.
Current-state impact
debug already composes one project function with every integration named export,
in project-first/config-order delivery, with identity dedupe and per-handler copies.
Its synchronous process-exit lifecycle and existing inheritDebug compatibility
switch remain unchanged.
PR #6200 initially selected one executable gap writer. This specification replaces
that model before release: gapReport becomes one project handler plus every loaded
integration handler, and each handler returns its own receipt. Existing consumers
without handlers keep the consent-gated issuesUrl fallback. No released config or
integration API requires migration because the single-writer shape has not shipped.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1–FR3 | gap-report handler type and receipt contract tests | valid handler; missing audience; wrong status value; non-object return | an invalid handler shape or receipt is accepted silently |
| FR4 | handler isolation tests | handler writes stdout; handler calls process.exit; handler throws; handler exceeds 30 s | stdout corruption reaches the JSON envelope, or exit/throw stops later handlers |
| FR5 | no-opt-out assertion test | project sets inheritDebug: false in package.json; gap-report handlers still run |
an opt-out mechanism suppresses a gap-report handler |
| FR6 | effective-set ordering and deduplication tests | project + two integrations; duplicate handle ref; project only; integrations only | wrong order, duplicate execution, or missing handler |
| FR7 | target selection tests | explicit package; unique owner; ambiguous owner requiring --package; no component match |
handler count influences target, ambiguity is guessed, or an unknown component fails to default to Core |
| FR8 | fallback activation and suppression tests | zero handlers + GitHub issuesUrl; zero handlers + non-GitHub issuesUrl; one handler present | fallback fires with a handler present, or non-GitHub issuesUrl claims it filed |
| FR9–FR10 | config field and named-export loading tests | project config with gapReport; integration with named export; both present; neither present | config field ignored, named export ignored, or old CLI breaks on named export |
| FR11 | mixed-audience consent tests | all internal; all public with consent; all public without consent; mixed with partial consent | a public handler runs without consent, or an internal handler is blocked by consent |
| FR12 | aggregate response shape tests | all succeed; one fails; one times out; consent_required entries; empty set (fallback) | missing delivery entry, wrong source attribution, or response shape differs between --json and human |
| FR13 | named destination tests | --to naming an integration with a GitHub issuesUrl, with and without consent; a non-GitHub issuesUrl; an unknown package |
a handler runs with --to, or an unknown destination sends anything |
| General | mutation-sensitive composition tests (structuredClone) | handler mutates event fields; handler adds properties to event | mutation leaks to a subsequent handler |
Decision log
DEC-1 — Handlers compose additively; no single-writer selection
Reference: spec:AST-031/DEC-1
Decider: josephfarina, 2026-09-10
Every configured handler runs. The previous model selected one writer based on target ownership, which meant an integration could not observe reports about components it did not own. Additive composition lets every interested party receive every report while isolating failures to individual deliveries.
Rejected: single-writer selection by target ownership; priority-based override where a project handler silences integration handlers; "first match wins" routing.
DEC-2 — No general opt-out mechanism for runtime features
Reference: spec:AST-031/DEC-2
Decider: josephfarina, 2026-09-10
The debug feature's existing inheritDebug switch remains a compatibility
exception owned by that feature. It does not establish a general
inherit<Feature> convention. Gap reporting is an explicit command whose purpose
is to notify every configured handler, so loading an integration opts into its
handler. Any future opt-out requires a separate owner decision.
Rejected: automatically cloning inheritDebug into a general package.json
pattern; adding a gap-report opt-out that silently prevents a loaded integration
from receiving an explicit report.
DEC-3 — Target selection uses component ownership, not handler count
Reference: spec:AST-031/DEC-3
Decider: josephfarina, 2026-09-10
The target package for a gap report is the package that owns the component. When
multiple packages claim the same component name, the CLI requires an explicit
--package instead of guessing. A name with no exact owner defaults to Core.
Handler count and handler order never change target attribution.
Rejected: selecting the target by handler count or integration order; silently choosing one ambiguous owner; distributing target ownership to every package that ships a handler.
Open questions
None.