Repository navigation
ADR-0087 P0: enforce the protocol handshake (make engines.protocol real) #2644
Description
Part of #2643 (ADR-0087). First phase — smallest change, highest value/cost. Turns a protocol/consumer version mismatch from an arbitrary downstream crash into a structured, machine-actionable load-time refusal, and pays down a standing ADR-0078 violation (a declarable field the runtime ignores).
Status: core enforcement + install seam shipped in #2650 (draft). Remaining items (load-path handshake, lint nudge, scaffold stamping) tracked below — this issue stays open until they land.
The bug this fixes
PluginEnginesSchema.protocol (packages/spec/src/kernel/manifest.zod.ts, ADR-0025 §3.2, protocol-first per §3.10 #3) is declared, documented, and checked by no loader, installer, or CLI command (repo-wide grep: the only non-test hit is the schema's own .describe()). A package built against protocol N and loaded by an incompatible runtime therefore fails deep inside a .parse() or a renderer contract instead of at the boundary.
Scope (D1)
-
PROTOCOL_VERSION/PROTOCOL_MAJORconstant exported from@objectstack/spec/kernel(drift-tested against the package major). — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650 - Pure handshake core in
@objectstack/metadata-core:checkProtocolCompat(),assertProtocolCompat(), structuredProtocolIncompatibleError(OS_PROTOCOL_INCOMPATIBLE) carrying both versions + themigrate meta --from Ncommand; refuses only on a positive mismatch, grandfathers absent ranges, never false-rejects an unparsed range. — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650 - Install seam:
installPackageruns the handshake before the registry write. — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650 - Load seam: run the handshake on the boot-time durable-package rehydration path and
AppPlugin.start()for code-defined stacks (the sameassertProtocolCompatcall). -
objectstack lintflags a package with noengines.protocolrange (nudge toward declaring it). - Scaffold stamping:
create-objectstackand thedefineStacktemplates emitengines: { protocol: '^<current major>' }by default — the ratchet that closes grandfathering.
Acceptance criteria
- A fixture package declaring an incompatible
engines.protocolis rejected at install with the structured diagnostic (error code + both versions + migrate command asserted); it does not reach the registry write. — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650 - A compatible range installs unchanged; a package with no range installs with exactly one warning. — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650
-
@objectstack/downstream-contract+ the api-surface snapshot stay green (2 added, 0 breaking; snapshot regenerated). — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650 - The diagnostic is identical in shape whether the consumer is one major behind or five. — feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) #2650
- The same guarantees hold on the load path, not just install.
Boundaries
- No source rewriting here — this phase only refuses; the migration that resolves the refusal is P1 (conversion) / P2 (
migrate meta). - The error must name the chain/command, not a doc the consumer "should have read" — see ADR-0087 D1.
Refs: #2643, #2650, ADR-0087 (D1), ADR-0078, ADR-0025 §3.2/§3.10.
Activity
feat(protocol): enforce the engines.protocol handshake (ADR-0087 P0) (#…
os-zhuang commentedon Jul 15, 2026
记录:本 issue 被 #2650 自动关闭时,正文中还有三项未勾选(load seam、lint 提示、脚手架 stamping),此后一直没有跟踪载体。这三项已在 #2972 全部补齐:
sys_packages启动再水化路径(@objectstack/service-package)对不兼容包发出结构化OS_PROTOCOL_INCOMPATIBLE拒绝并跳过(boot 继续);AppPlugin(code-defined stack)在 manifest 分解前 fail-fast。objectstack lint:新增protocol/missing-engines-range(warning + fix-it)。engines: { protocol: '^<major>' },由sync-template-versions.mjs在版本时重新 stamp,并有一致性测试防漂移。#2972 合并后 D1 即完整落地(install + load 两侧 + 棘轮两端)。
Generated by Claude Code
feat(protocol): complete ADR-0087 — load-seam handshake, chain backfi…