Skip to content

ADR-0076: remaining objectql/protocol layering work (cross-repo window) #2462

Closed

Description

@os-zhuang

Tracking issue for the remaining work from ADR-0076 (objectql layering / protocol segmentation / honest capabilities).

Done (for context)

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 2nd IHttpServer adapter (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-dispatcher svcAvailable respect it (report status:'stub'/handlerReady:false, never available); add the stub status 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 /analytics 404). Risk: med; cross-repo (console reads discovery.services). See OQ#11 (marker convention).
  • Step 2 — make the @objectstack/objectql package itself protocol-free. Turn the protocol wiring into a MetadataProtocolPlugin (capability plugin, like plugin-security); update framework boot sites + cloud's ~8 new 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

Generated from the ADR-0076 kernel review.

Activity

  1. os-zhuang commented on Jul 25, 2026

    @os-zhuang
    ContributorAuthor

    进度更新(2026-07-25):D11 步骤④ 完成;步骤③ 接缝落地(PR-1)

    ✅ D11 步骤④ — env 解析统一到 KernelResolver 缝:DONE(#3487)
    REST 服务器的平行 hostname/X-Environment-Id 解析链(同一条链在 resolveRequestEnvironmentId / resolveI18nService / computeExecCtx 手抄三份)收敛为单一入口,经新 RestRequestEnvResolver 缝消费 host 的 ADR-0006 kernel-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 条新接缝测试锁定)。

    🔻 剩余(更新后)

    • D11 步骤③ PR-2..N:逐域把 handler 体 + 注册权移交所属服务包(缺席语义 501→404 逐域决定,配 D12 discovery 联动 + console 确认);全部迁完后 createHonoApp catch-all 退役 → 解锁步骤①。
    • D11 步骤①(blocked on ③ 完成,re-scope 见上条评论)。
    • Step 2 + D10(cloud 3 boot 站点,等协调窗口,排在 ③ 之后)。
    • D7 引擎分仓(指标 2026-07-25 实测 95.2%(118/124,90 天窗口),门控继续)。

    Two PRs merged this session: #3487 (D11 step ④), #3491 (D11 step ③ PR-1).

  2. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    进度更新(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 委托保留给直调方。

    ⚠️ 计划修正(重要,覆盖上面 2026-07-17 评论的表述):handler 注册权留 dispatcher,不移交服务包。
    原清单写"按域抽取 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 抽体时顺手删除即可;其余均为线性安全的 ^\/+ 开头锚定。

    🔻 剩余(更新后)

    • 步骤③ PR-3..N:逐域机械复制抽体模式。建议批次:小体量先行(/keys /storage /ui /share-links /packages),大头随后(/automation /actions /auth /meta /data /mcp /ai)。全部迁完 → catch-all 退役 → 解锁步骤①。
    • Step 2 + D10(cloud 3 boot 站点,等窗口,排步骤③后)。
    • D7 引擎分仓(95.2% 门控中)。

    Three PRs merged this session: #3507 (PR-2 extraction), #3510 (redos fix), plus #3487/#3491 earlier (step ④ + PR-1).

  3. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    进度更新(2026-07-27,第二批):D11 步骤③ 抽体系列 PR-3..6 全部合并

    自上一条评论后又落地 4 个 PR(全部零行为变化,conformance 41 断言 + 接缝套件锁定):

    现状: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(深耦合批,单独设计)→ 全部迁完后 createHonoApp catch-all 退役 → 解锁步骤①。

    Four PRs merged this session: #3522, #3533, #3537, #3542.

  4. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    进度更新(2026-07-27,第三批):机械批收官 + GraphQL 面整体移除

    🔻 深耦合批(最后一关)缩减为四域:/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).

  5. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    进度更新(2026-07-27,第四批):深耦合批两刀落地,if 链只剩 /meta /data

    现状:16 域进注册表;dispatch() if 链仅剩 /meta /data 两分支。抽体工艺三坑已成体系(类静态引用×2、测试直调补委托、conformance pin 随体搬家),terminal 刀直接套用。

    🔻 剩余:终刀 PR-10 = /meta + /data(handleMetadata/handleData,数据面核心)→ if 链清空 → createHonoApp catch-all 退役 → 步骤① 解锁 → D11 步骤③ 全线收官。之后 #2462 仅剩 Step 2/D10(cloud 窗口)与 D7(门控)。

    Two PRs merged this batch: #3565, #3568.

  6. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    🏁 D11 步骤③ 收官(2026-07-27):dispatcher 按域拆解完成,if 链清零

    ✅ #3573(PR-10 终刀):/meta(327 行,含 ADR-0033 草稿路径 + ADR-0046 slimDocList)+ /data(122 行,callData 桥 + 语义化 isMultiTenantHost() 替代直捅 kernelResolver)。

    步骤③ 全系列账目(10 刀 + 2 修复 + 1 删除,全部合并)

    PR 内容
    #3491 注册表接缝(PR-1)
    #3507 + #3510 四域抽体 + redos 修复(PR-2)
    #3522 keys/storage/ui(PR-3)
    #3533 share-links(PR-4,cloud 设计主面)
    #3537 packages 最大单域(PR-5)
    #3542 automation(PR-6)
    #3551 auth/ai + CSPRNG 修复(PR-7)
    #3562 GraphQL 面整体删除(产品决策)
    #3565 action-execution 子系统(PR-8)
    #3568 actions/mcp 深耦合批(PR-9)
    #3573 meta/data 终刀(PR-10)

    终态:18 个域模块 + action-execution 子系统各自独立;DomainHandlerDeps 契约 16 方法显式化域可触碰的全部 dispatcher 面;dispatch() = 关卡序 + 查表;conformance(41 断言)+ 接缝套件 + dogfood(351)全程锁定零行为变化。抽体连带翻出并修复 3 个 CodeQL 潜伏问题(redos/冗余正则/insecure-randomness)。

    🔻 #2462 剩余(全部为窗口/门控等待态)

    • 步骤①(现已解锁):createHonoApp catch-all 退役——需跨仓核对 cloud 两 host 的 dispatch() 委托路径(/share-links /notifications 转正为注册表解析),建议单独小 PR + cloud 侧回归。
    • Step 2 + D10(cloud 3 boot 站点,等协调窗口)。
    • D7 引擎分仓(每周指标门控中,95.2%)。

    步骤③ 主线至此关闭;本 issue 收敛为上述三项等待/后续态。

  7. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    步骤① 关闭(2026-07-27):catch-all 洗白裁决,无代码变更

    核对完成,裁决如下(详见 ADR 修订 #3576):

    1. 步骤③ 用相反刀法达成了步骤① 的目标——原文设想"退役 catch-all 后删死分支";实际落地是"域体全部搬出、if 链清零",catch-all 委托进的不再是不可枚举的上帝 if 链,而是关卡序 + first-match 注册表的薄管线。病根("declared≠mounted≠implemented" 可藏身的地方)已根治,catch-all 作为薄管线入口是合理终态。
    2. "删死分支"被吸收:无分支可删,只有有 owner、有接缝测试的注册表条目。cloud fallback 织物(/share-links per-env 主面、/notifications 唯一 owner)走同一管线。
    3. cloud 侧验证:objectos-runtime 240 测试全过(含 kernel-resolver 策略——委托路径核心)对拆解后 dispatcher 零改动通过。service-cloud 的 37 个文件级失败经归因为 feat(spec)!: remove dead enable.trash/mru capability flags (#2377 close-out, ADR-0049) #3414(enable.trash/mru prune)的跨仓 fixture 债,与 dispatcher 线无关,已另立任务跟进。
    4. 可选 polish(adapter 枚举注册表挂显式路由)需关卡 middleware 化,成本>收益,有意不排期。

    #2462 至此收敛为两项窗口/门控等待态:Step 2 + D10(cloud 3 boot 站点,等协调窗口)、D7 引擎分仓(周指标 95.2% 门控)。D11 全线(②③④①+D12+A1.5+OQ#9/10/11)关闭。

  8. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    🏁 Step 2 + D10 收官(2026-07-27):跨仓三腿闭环

    用户开启 cloud 协调窗口后,Step 2 按预写配方(含一处评估后修正)完整落地:

    腿 PR 内容
    A(framework 加性) #3578 createMetadataProtocolPlugin() + ObjectQLPlugin.registerProtocol 开关(默认 true 零破坏);重绑订阅抽共享方法、delegated 模式 start() 惰性 arm
    B(cloud 翻转) cloud#877 三站点(objectos-stack / artifact-kernel-factory / control-plane-preset)全切委托装配 + .objectstack-sha bump
    C(framework 收官) #3591 assembleMetadataProtocol() 单一来源(引擎删 112 行内联)+ objectql 六条 protocol re-export 删除(breaking-as-minor)
    C 跟进 cloud#879 SHA bump + cloud 侧唯一 re-export 消费方改指

    配方修正(与 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 最终态

    • ✅ D9 / D11(②③④①)/ D12 / A1.5 / Step 2 / D10 / GraphQL 出列 —— 全部关闭
    • ⏸ D7 引擎分仓:唯一余项,每周指标门控(95.2%),无人力投入
    • 📎 旁支:OSV 存量漏洞升级、cloud fixture 债(已完成 cloud#876)各有独立任务

    本 issue 可以关闭或降为 D7 观测伞。

  9. os-zhuang commented on Jul 27, 2026

    @os-zhuang
    ContributorAuthor

    ✅ 关闭:全部实质工作完成,余项已拆分独立跟踪

    本 issue 追踪的 ADR-0076 跨仓窗口工作全线收官(详见上方逐批进度评论;共 22+ 个 PR 跨 framework/cloud/objectui 三仓合并):

    拆出的独立跟踪

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions