ADR-0030: Certify ecosystem product chats through one application layer
ADR-0030: Certify ecosystem product chats through one application layer
Context
AgentsKit Chat 0.3.0 consolidates the public application framework into
@agentskit/chat and @agentskit/chat-cli. AgentsKit Docs, the deployed
Registry, and Playbook consume that graph, while other active consumers still
use legacy package names, lack production deployment, or retain host-specific
product chat surfaces. Low-level AgentsKit binding examples also look like chat
applications even though their purpose is to teach the underlying binding.
Issue closure alone cannot support an ecosystem-wide adoption claim. The claim needs one definition of a product chat, bounded treatment of private consumers, and evidence that fails closed when a version, migration, CI run, or production smoke is missing.
Decision
AgentsKit remains the runtime substrate. It owns controllers, lifecycle, framework bindings, adapters, tools, memory, RAG, replay, eval, and reusable agent primitives. AgentsKit Chat is the single application layer for product chats. It owns portable application definitions, deterministic routes, policy composition, component manifests, session envelopes, protocol, server seams, and native renderer shells. Hosts own configuration, content, branding, deployment, and business-specific actions or state machines.
A product chat is an end-user conversational surface that composes
application behavior, presentation, and a runtime or deterministic answer
source. Every declared product chat must consume @agentskit/chat or a
supported subpath at the exact certified version. Direct use of an AgentsKit
binding is allowed only in an explicitly classified low-level binding
example whose purpose is to teach that primitive. Such examples are excluded
from product-chat adoption totals and may not be presented as framework hosts.
The repository commits ecosystem-adoption.json as the public convergence
ledger. A strict runtime schema verifies:
- the fixed set of declared consumers and supported repositories;
- product, infrastructure, and low-level-example classification;
- exact framework version and supported import paths;
- remaining legacy standalone packages;
- public CI and production evidence; and
- aggregate private attestations without URLs or implementation fields.
certified is derived from evidence, not issue state. A public product chat
requires the exact version, no legacy package, consolidated consumption,
passing CI with an HTTPS evidence URL, and a passing production smoke URL. A
private product chat requires the same contract plus a bounded private-audit
attestation; its source, topology, identifiers, behavior, and business rules
remain outside public artifacts.
The ledger is an audited baseline, not a live network monitor. Cross-repository certification resolves evidence and updates the ledger through reviewed PRs. Repository CI validates schema and internal consistency without depending on network availability.
System boundary
flowchart TD
AK["AgentsKit · reusable runtime primitives"] --> AC["AgentsKit Chat · application layer"]
AC --> H["Product-chat hosts"]
H --> B["Host configuration, branding, deployment"]
H --> P["Private or product-specific behavior"]
M["ecosystem-adoption.json"] --> G["Schema and certification gate"]
G --> C{"Certified?"}
C -->|"yes"| CL["Public adoption claim"]
C -->|"no"| W["Migration or deployment work"]Non-functional requirements
- The gate is deterministic, offline, and adds no production dependency.
- Exact-version rollback remains available per consumer until final certification.
- Existing renderer bundle, accessibility, conformance, and performance budgets remain unchanged.
- Public evidence contains no provider secret, user content, private source, internal topology, identifier, or business rule.
- Missing evidence is incomplete, never implicitly successful.
Alternatives considered
- Infer adoption from closed issues. Rejected because issue state does not prove the current default branch, package graph, deployment, or production behavior.
- Require every educational chat example to use AgentsKit Chat. Rejected because it would prevent AgentsKit from teaching its lower-level bindings and would blur the framework/runtime boundary.
- Publish the private AKOS inventory. Rejected because convergence requires contract evidence, not disclosure of private behavior or topology.
- Run network checks in every repository test. Rejected because ordinary CI must remain deterministic; network resolution belongs to the final cross-repository certification workflow.
- Allow semver ranges in the ledger. Rejected because a range does not prove which artifact produced the evidence.
Consequences
Positive
- “Powered by AgentsKit Chat” becomes measurable and reviewable.
- Low-level examples remain valid without weakening product adoption claims.
- Private consumers can prove conformance without exposing internal logic.
- Missing migrations and deployments remain visible instead of being hidden by a closed milestone.
Negative
- Adding or removing a declared consumer requires a schema and ADR review.
- Evidence updates add cross-repository maintenance work.
- Broad promotion remains blocked until every required product chat is certified.
Neutral
- The ledger records external repositories but does not fetch or mutate them.
- Existing host deployment and monitoring systems remain host-owned.
Failure modes and mitigations
| Failure | Mitigation |
|---|---|
| Stale successful URL | Final certification resolves URLs and records a new audited date. |
| Legacy package reintroduced | Consumer repository gates plus this ledger keep certification false. |
| Private detail enters public evidence | Private records accept only fixed aggregate attestation values. |
| Workspace dogfood misrepresented as npm | Consumption mode is explicit and workspace is restricted to the framework-owned portal. |
| Missing generic primitive discovered | Migration stops and the primitive is fixed and released in its upstream owner first. |
Acceptance
HITL approval was recorded on 2026-07-14 for the product-chat definition, the low-level-example exception, the private-attestation boundary, and the rule that broad promotion requires every declared product chat to be certified.