Repository navigation
ADR-0076: remaining objectql/protocol layering work (cross-repo window) #2462
Copy link
Copy link
Closed
Description
Tracking issue for the remaining work from ADR-0076 (objectql layering / protocol segmentation / honest capabilities).
Done (for context)
- ✅ protocol relocated out of the engine →
@objectstack/metadata-protocol; lean@objectstack/objectql/coreentry + boundary ratchet (refactor(objectql): extract metadata-protocol + add lean ./core entry (ADR-0076 Step 1) #2415). - ✅ D9 step-1:
ObjectStackProtocolsegmented into per-domain interfaces (DataProtocol/MetadataProtocol/…), composed alias for back-compat — non-breaking (feat(spec): segment ObjectStackProtocol into per-domain interfaces (ADR-0076 D9, step 1) #2429). - ✅ ADR D1–D12 recorded (rev.9).
Remaining — all gated to a coordinated cross-repo window (framework + cloud + ../objectui), unless noted
- D10 — distribute protocol implementations to domain packages. Data facade → transport; analytics/feed/realtime impls owned by their existing services (
service-analytics/service-messaging/service-realtime); the metadata-management impl stays in@objectstack/metadata-protocol(name retained — OQ#7). Dissolve the central facade. Risk: med; cross-repo. - D11 — decompose the transport god-implementation.
runtime/http-dispatcher.ts(~3.8k) +rest/rest-server.ts(~5.1k) → thin framework-agnostic port + per-domain normalized handlers (NOT framework-specific routes — keep multi-adapter). Confirm dispatcher↔rest-server overlap; validate multi-adapter by writing a 2ndIHttpServeradapter (thin Workers/Express) to prove the port is free of Hono-isms. Risk: high; cross-repo. - D12 — honest capabilities (fixes agents being misled by fake services). Standardize a stub/dev/fallback marker; make
http-dispatchersvcAvailablerespect it (reportstatus:'stub'/handlerReady:false, neveravailable); add thestubstatus to the discovery schema; update consumers (agents, console) to trust only real services. Mark the analytics fallback + plugin-dev stubs honestly — do not delete (no/analytics404). Risk: med; cross-repo (console readsdiscovery.services). See OQ#11 (marker convention). - Step 2 — make the
@objectstack/objectqlpackage itself protocol-free. Turn the protocol wiring into aMetadataProtocolPlugin(capability plugin, like plugin-security); update framework boot sites + cloud's ~8new ObjectQLPlugin()sites to also register it. Risk: high; breaking boot contract; cross-repo (cloud). - D7 — engine repo-split (trigger-gated). Only when the cross-package commit ratio of
engine.ts/registry.ts(currently 88%) falls to a low, stable level. Track the metric in CI. Then extract on the objectui sibling-link model. Risk: high; deferred. - (optional, low-risk, any time) A1.5 — narrow consumers to the new sub-interfaces (e.g. data-only callers →
DataProtocol), per the D9 incremental guidance.
Notes
- Resolved, no action: A2 (delete the "duplicated" analytics) — it's a deliberate fallback+
replaceService, not a collision; handled by D12 (mark honestly). - Sequencing: D9 contract segmentation is spec/type-level and already started (feat(spec): segment ObjectStackProtocol into per-domain interfaces (ADR-0076 D9, step 1) #2429). The implementation-level items above touch cloud boot and/or the console discovery contract, so they batch into one coordinated window.
Generated from the ADR-0076 kernel review.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity
os-zhuang commentedon Jul 25, 2026
进度更新(2026-07-25):D11 步骤④ 完成;步骤③ 接缝落地(PR-1)
✅ D11 步骤④ — env 解析统一到 KernelResolver 缝:DONE(#3487)
REST 服务器的平行 hostname/
X-Environment-Id解析链(同一条链在resolveRequestEnvironmentId/resolveI18nService/computeExecCtx手抄三份)收敛为单一入口,经新RestRequestEnvResolver缝消费 host 的 ADR-0006kernel-resolver服务——REST 与 dispatcher 面对"这个请求归哪个 env"给出同一个答案(session 兜底补齐)。resolver 正常返回即终局;旧链保留为 OSS 单环境 fallback 与降级路径。cloud 零改动(kernel-resolver本就注册在env-registry旁)。cloud 侧new ObjectQLPlugin()站点实测已从 ~8 降到 3(Step 2 窗口成本进一步下降)。✅ D11 步骤③ PR-1 — 薄域注册表接缝:DONE(#3491)
DomainHandlerRegistry(first-match{prefix, match, methods, handler},匹配语义保真旧 if 链、毛边照留)+dispatch()查表前置 + 公共registerDomainHandler()缝。种子四域示范三种 handler 形状:/health+/ready(无服务依赖)、/analytics(服务桥,fallback 语义留服务层 per D10/D12)、/i18n(可选服务 501 自兜)。迁移纪律 = 注册表先行、代码后搬、归属最后:本 PR handler 体不动,行为零变化(conformance 41 断言 + 11 条新接缝测试锁定)。🔻 剩余(更新后)
createHonoAppcatch-all 退役 → 解锁步骤①。Two PRs merged this session: #3487 (D11 step ④), #3491 (D11 step ③ PR-1).
feat(runtime): extract first four dispatcher domain bodies into domai…
os-zhuang commentedon Jul 27, 2026
进度更新(2026-07-27):D11 步骤③ PR-2 落地 + 一处重要计划修正
✅ 步骤③ PR-2 — 首批四域抽体(#3507 + 修复 #3510)
/analytics、/i18n、/notifications、/security四个 handler 体从 dispatcher 上帝类抽到packages/runtime/src/domains/独立模块,运行在显式DomainHandlerDeps契约上(resolveService/getService/success/error——域可触碰的全部 dispatcher 面)。http-dispatcher.ts 净瘦 235 行。registry 新增match:'segment';/notifications+/security撤出 if 链。薄handleXxx委托保留给直调方。原清单写"按域抽取 normalized handler 到所属服务包"——实施调查证明它对多数域不成立:服务槽是多方提供的(
i18n= I18nServicePlugin 或 AppPlugin 内存 fallback 自动注册;analytics= service-analytics 或 ObjectQLPlugin fallback)。路由是槽的桥而非提供方私产;注册权移进任一提供方,另一方的部署即 404(A2 调研警告过的同款回归)。独占槽的外部包仍可经公共registerDomainHandler()自注册。后续抽体 PR 沿用"体进 domains/ 模块、注册留 dispatcher"。🔍 搬迁翻债一例(后续 PR 的预防措施已做): 抽体使旧代码成为 CodeQL 眼中的"changed code",notifications 里潜伏自 ADR-0030 的尾斜杠正则
js/polynomial-redos(high)被首次扫出(security 域同款早已修过)——已照 split+filter 先例修复(#3510)。预扫结论:剩余 handler 中同类高危仅handleActions一处(/^\/+|\/+$/g且正则冗余,其后紧跟 split+filter),/actions 抽体时顺手删除即可;其余均为线性安全的^\/+开头锚定。🔻 剩余(更新后)
Three PRs merged this session: #3507 (PR-2 extraction), #3510 (redos fix), plus #3487/#3491 earlier (step ④ + PR-1).
feat(runtime): extract /keys /storage /ui dispatcher domain bodies — …
feat(runtime): extract /share-links dispatcher domain body — ADR-0076…
feat(runtime): extract /packages dispatcher domain body — ADR-0076 D1…
feat(runtime): extract /automation dispatcher domain body — ADR-0076 …
os-zhuang commentedon Jul 27, 2026
进度更新(2026-07-27,第二批):D11 步骤③ 抽体系列 PR-3..6 全部合并
自上一条评论后又落地 4 个 PR(全部零行为变化,conformance 41 断言 + 接缝套件锁定):
/keys(含零容忍铸钥安全契约 +'/keys?'变体双注册项)、/storage(删一条论证过的死 fallback 腿)、/ui。deps 扩getObjectQL。/share-links——cloud per-env kernel 的设计主面(步骤① re-scope 发现),保真即全部意义。deps 扩getRequestKernelService(per-request 已解析 kernel 读服务:token 行与被分享记录必须同库)+routeNotFound。/packages——最大单域(~680 行,含独占 helperassemblePackageManifest/applyPublishedSeeds)。deps 扩errorFromThrown/resolveActiveOrganizationId/announceKernelEvent/logger。步骤② 单管线行为保持。/automation(~260 行)——系列最干净刀,deps 契约零增长;/actions/connectors/_status守卫顺序原样锁定。现状:12 域已进注册表,http-dispatcher.ts 从步骤③启动时的 4765 行瘦到 ~2600 行;
DomainHandlerDeps契约稳定在 11 个方法。handleActions不可机械抽——它直接操作 env 解析状态(this.kernel/kernelResolver/resolveDefaultProject+ 4 个私有 helper),正是 CloudKernelResolver 注释里 "action routes resolve scope before the seam" 所指。归入/data/meta深耦合批,需先设计"env 解析状态"在 deps 契约中的形态,再动这三个域。🔻 剩余:
/auth/mcp/ai(中体量,机械可做)→/actions/meta/data(深耦合批,单独设计)→ 全部迁完后createHonoAppcatch-all 退役 → 解锁步骤①。Four PRs merged this session: #3522, #3533, #3537, #3542.
feat(runtime): /auth /ai 两域 handler 体抽出 — ADR-0076 D11 步骤③ PR-7 (#2462)…
feat(spec)!: 移除从未实现的 GraphQL 面 — 不在产品计划 (#2462 后续) (#3562)
os-zhuang commentedon Jul 27, 2026
进度更新(2026-07-27,第三批):机械批收官 + GraphQL 面整体移除
/auth+/ai抽体。deps 惰性成员isAuthRequired()/getRegisteredAiRoutes()(TS2729 构造顺序陷阱教训)。14 域进注册表,机械批收官。resolveRequestExecutionContext;plugin-dev stub;qa 矩阵两行 + ratchet pins + dogfood 面用例;22 manifest 键 + references + skill-refs。/graphql恒 501 → 404。保留 external-datasource 'graphql' 协议选项(客户端连第三方合法)与 cloud 保留字。changeset 按 launch-window 惯例 minor(feat(spec)!: remove the dead PortalSchema — never-enforced no-op projection (#3464) #3486 同款)。objectui 死联合成员'graphql'(types/data-protocol.ts:1494)记为跨仓清理项。🔻 深耦合批(最后一关)缩减为四域:
/actions/meta/data/mcp(graphql 出列)。共享设施:action 执行家族 9 helper(/actions + /mcp 经 buildMcpBridge)+ env 解析状态(this.kernel/kernelResolver/resolveDefaultProject)。切法建议不变:先抽 action-execution 子系统模块(deps 只加 getActionExecutor()),再逐域机械抽,/meta /data 终刀 → catch-all 退役 → 解锁步骤①。Three PRs merged this session-batch: #3551, #3562 (+ redos/randomness fixes folded in).
feat(runtime): extract action-execution subsystem — ADR-0076 D11 step…
feat(runtime): extract /actions and /mcp dispatcher domains — ADR-007…
os-zhuang commentedon Jul 27, 2026
进度更新(2026-07-27,第四批):深耦合批两刀落地,if 链只剩 /meta /data
ActionExecutionDeps窄至两方法(resolveService/getObjectQL),零 env 解析状态。ADR-0104 warn-once 静态成员随体搬为模块函数(类静态引用会造成模块→dispatcher 值回环)。/actions+/mcp抽体。env 预解析段收敛为两个 deps 缝(getDefaultEnvironmentId+resolveProjectKernelObjectQL——ADR-0006 直调方 kernel 交换,this.kernel写入副作用仍归 dispatcher);/mcp/skill→/mcp匹配序四条有序注册项复刻;预扫的冗余尾斜杠正则(CodeQL redos 孪生)顺删;authz identity pin(buildMcpBridge context-threaded)随体指向domains/mcp.ts。现状:16 域进注册表;dispatch() if 链仅剩
/meta/data两分支。抽体工艺三坑已成体系(类静态引用×2、测试直调补委托、conformance pin 随体搬家),terminal 刀直接套用。🔻 剩余:终刀 PR-10 =
/meta+/data(handleMetadata/handleData,数据面核心)→ if 链清空 →createHonoAppcatch-all 退役 → 步骤① 解锁 → D11 步骤③ 全线收官。之后 #2462 仅剩 Step 2/D10(cloud 窗口)与 D7(门控)。Two PRs merged this batch: #3565, #3568.
feat(runtime): extract /meta and /data — ADR-0076 D11 step ③ PR-10, t…
os-zhuang commentedon Jul 27, 2026
🏁 D11 步骤③ 收官(2026-07-27):dispatcher 按域拆解完成,if 链清零
✅ #3573(PR-10 终刀):
/meta(327 行,含 ADR-0033 草稿路径 + ADR-0046 slimDocList)+/data(122 行,callData 桥 + 语义化isMultiTenantHost()替代直捅 kernelResolver)。步骤③ 全系列账目(10 刀 + 2 修复 + 1 删除,全部合并)
终态:18 个域模块 + action-execution 子系统各自独立;
DomainHandlerDeps契约 16 方法显式化域可触碰的全部 dispatcher 面;dispatch() = 关卡序 + 查表;conformance(41 断言)+ 接缝套件 + dogfood(351)全程锁定零行为变化。抽体连带翻出并修复 3 个 CodeQL 潜伏问题(redos/冗余正则/insecure-randomness)。🔻 #2462 剩余(全部为窗口/门控等待态)
createHonoAppcatch-all 退役——需跨仓核对 cloud 两 host 的dispatch()委托路径(/share-links /notifications 转正为注册表解析),建议单独小 PR + cloud 侧回归。步骤③ 主线至此关闭;本 issue 收敛为上述三项等待/后续态。
os-zhuang commentedon Jul 27, 2026
步骤① 关闭(2026-07-27):catch-all 洗白裁决,无代码变更
核对完成,裁决如下(详见 ADR 修订 #3576):
#2462 至此收敛为两项窗口/门控等待态:Step 2 + D10(cloud 3 boot 站点,等协调窗口)、D7 引擎分仓(周指标 95.2% 门控)。D11 全线(②③④①+D12+A1.5+OQ#9/10/11)关闭。
docs(adr): ADR-0076 OQ#9 verdict — the catch-all is rehabilitated, st…
feat(metadata-protocol,objectql): MetadataProtocolPlugin + registerPr…
feat(objectql,metadata-protocol)!: single-source protocol assembly + …
os-zhuang commentedon Jul 27, 2026
🏁 Step 2 + D10 收官(2026-07-27):跨仓三腿闭环
用户开启 cloud 协调窗口后,Step 2 按预写配方(含一处评估后修正)完整落地:
createMetadataProtocolPlugin()+ObjectQLPlugin.registerProtocol开关(默认 true 零破坏);重绑订阅抽共享方法、delegated 模式 start() 惰性 arm.objectstack-shabumpassembleMetadataProtocol()单一来源(引擎删 112 行内联)+ objectql 六条 protocol re-export 删除(breaking-as-minor)配方修正(与 A2/步骤① 同类):objectql→metadata-protocol 依赖有意保留——
./core入口本就零 protocol,强迫 framework 内 ~20 个单 kernel/dev/测试 boot 站点双插件是纯样板税。Step 2 目标落地为"零装配所有权、单一来源":cloud 生产装配完全由 metadata 域包拥有;framework 便利模式挂载同一代码路径。D10 一并裁决完成:其各项诉求已分布达成——实现归 metadata 域包(本 Step 2)、DataProtocol 收窄至传输消费方(A1.5)、analytics fallback 诚实标注(D12)、feed 已委托 IFeedService(先在);残留仅 protocol.zod 组合别名删除(spec breaking,留下个大版本,无行为影响)。
#2462 最终态
本 issue 可以关闭或降为 D7 观测伞。
os-zhuang commentedon Jul 27, 2026
✅ 关闭:全部实质工作完成,余项已拆分独立跟踪
本 issue 追踪的 ADR-0076 跨仓窗口工作全线收官(详见上方逐批进度评论;共 22+ 个 PR 跨 framework/cloud/objectui 三仓合并):
拆出的独立跟踪
fix(metadata-protocol,objectql)!: retire the degraded analytics shim …
fix(spec,runtime,metadata-protocol): discovery's "install this to ena…
refactor(spec,client,metadata-protocol,runtime)!: 退役 workflow 服务槽位与 g…
fix(runtime): dispatcher `capabilities.search` answers a stated `fals…
fix(mcp): register the object tools on the stdio transport (objectsta…
docs(api): stop documenting a `/graphql` route the dispatcher removed
fix(core,hono): retire /graphql residue — stale surface list and iner…
docs(skills): drop the five GraphQL residue sites and the stale /stor…
docs(api): stop documenting a `/graphql` route the dispatcher removed (…
fix(core,hono): retire /graphql residue — stale surface list and iner…
docs(skills): clear the GraphQL residue from the published catalog an…
docs: correct two stale GraphQL residue sites in package source comments
fix(runtime): ActionEngineFacade.delete refuses a nullish id instead …
test(spec): the first api/ file group's test titles state each cited …