refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies

domain:server#6 · os-support-ai · session_01WGufzibcN9oHa8kDbTTnL5

Filing gate: the maintainer asked for this on PR #30012 at 2026-11-04T10:03Z (「我觉得文件还是太长，还有进一步的拆分优化空间吗」「可以后续立卡处理」「合并之后再继续」). The facades are merged: engine.ts as 237f513 (#30012) and protocol.ts as 48914fd (#29998). Estimates come from the #29986 / #29985 dev reports. ⛔ Not a claim. Triage sets the grade and the lane (devx or server).

Business reason: bodies whose public return type is inferred stay on the class as #30019 exceptions, because moving them would change the .d.ts re-inference. In engine.ts there are 8: registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping and getStatus, 491 lines in all. In protocol.ts they include getDiscovery (460), findData (751), getData (75), cloneData (105) and the four *MetaItem doors. Writing each return type explicitly, equal to what is inferred today, lets the codemod move the body.
Reader who acts: packages/objectql / packages/metadata-protocol owners.

What to do

Spell each return type explicitly, and prove the public .d.ts is byte-equal before and after. That is one PR with no behaviour change.
Then re-run the codemod so the bodies move, and drop their rows from the tooling: a structural gate that refuses any method body in a facade file once protocol.ts and engine.ts land in facade form (ruling 6624258595) #30019 allow-list.
Dedupe: inferred return type facade, 30019 exception. New.

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Path: none

Triage: first-touch audit · p2 · `domain:server` · `pm:queue` · 2026-11-04T11:55Z

⛔ Not a claim.

Read fresh. The maintainer asked for this on PR refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012: give the inferred-return-type facade methods explicit return types, with the .d.ts unchanged, so the codemod can move them. This retires tooling: a structural gate that refuses any method body in a facade file once protocol.ts and engine.ts land in facade form (ruling 6624258595) #30019 exceptions. p2.
Serial with the other facade follow-ups on the same two files: refactor: compress the codemod facade stubs in engine.ts and protocol.ts — one shared host per facet instead of a per-call host literal (body-identical; about 1,000 lines off engine.ts) #30051, refactor: facade ObjectRepository and ScopedContext in engine.ts with the same codemod (about 700 lines), as the ObjectQL class already is #30052, refactor: move the private docblocks of the hand-series stubs into their hand modules — about 1,900 lines off engine.ts (86 stubs) and about 4,000 off protocol.ts (157 stubs) #30053, refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054, refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055 and refactor: move shared state out of the protocol.ts and engine.ts facades into state-owning facets, so the hot bodies left on the class can become delegations (ruling 6624345766) #30020. One PR per file at a time. Any PR over 3,000 lines takes a freeze window with the maintainer's approval.

Generated by Claude Code

chore(scripts): the six sql-driver.ts inferred-return-type rows go to…

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

Claim: PM loop round 1
Session: session_01Utp6CYVV6fcAQrNTDQRvPb (seat) · dev = project card thread session_01Utp6CXZTh9qvT24wTN6dd6
Account: os-bill
Branch: claude/project-thread-alkkr9 (harness-pinned thread branch; platform exception to claude/issue-<n>-<slug>)
Worktree: objectstack-issue-30054
Domain: domain:server
Seat: domain:server#5
File surface: packages/objectql/src/**, packages/metadata-protocol/src/**, the #30019 allow-list the facade gate reads, and one changeset. ⛔ packages/spec/**, ui/**, skills/**, docs/adr/**, .claude/**, AGENTS.md (stop on breach and explain in the report)
Container & model: M, mode:thread, model: default tier (opus), effort: high (p2)
Clause-②: no (provisional) — the public .d.ts must stay byte-equal, so no exported member changes
Metadata-protocol: none (provisional) — an internal refactor, nothing an author writes
Responsibility: inferred public return types keep 8 engine.ts bodies and the protocol.ts doors (getDiscovery, findData, getData, cloneData, *MetaItem) on the facades as #30019 exceptions (card body, read from the #29986 / #29985 reports) | none: the facades stay oversized | maintainers of packages/objectql and packages/metadata-protocol
Thread-read: none
Premise: holds per the card. Seat ruling: one PR with no behaviour change; the .d.ts diff is the proof
Serial constraints cleared: Serial behind #30055 (seat 3, codemod pass 4 --members moves six engine.ts bodies) for the engine.ts half. The protocol.ts half goes first. If #30055 has not merged by then, the PR is Part of #30054 for protocol.ts only.

Order: project file server-seat5/dispatch-30054.md (amendment 12:16Z), delivered to the card thread.

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb
os-dev-report

Card thread session_01Utp6CXZTh9qvT24wTN6dd6 · branch claude/project-thread-alkkr9 · draft PR #30516 · head 1777fb2d2

{
  "issue": 30054,
  "status": "rework",
  "branch": "claude/project-thread-alkkr9",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/30516",
  "head": "1777fb2d2",
  "session": "session_01Utp6CXZTh9qvT24wTN6dd6",
  "premise_still_valid": true,
  "summary": "Step 1 for protocol.ts only, opened as Part of #30054. The eight protocol.ts doors (getDiscovery, findData, getData, cloneData, saveMetaItem, publishMetaItem, rollbackMetaItem, deleteMetaItem) spell their return type, copied from the base build's dist/index.d.ts; the published index.d.ts and index.d.cts are byte-equal before and after (empty diff). Step 2 (move) is not mechanical: codemod-split-protocol.mjs refuses its own output, and --verify --base 48914fdc^ no longer re-proves (79/85 bodies, 71/78 host-split checks; post-split edits in facet modules and two non-facet top-level statements the unlift refuses), so moving needs a new facade pass in scripts/codemod-split-protocol.mjs, outside the file surface. The engine.ts half is not started: #30055's PR #30463 is still open. The 8 registry rows stay, with their reason rewritten.",
  "tests": "pin src/protocol.facade-door-return-types.pin.test.ts: 9/9 at head; 8/9 red on origin/main's protocol.ts (one per door). Ablation via ablation-replace.mjs: rollbackMetaItem annotation removed (anchor 1->0, blob 0a87e4f8->ec11148a), 1 failed / 8 passed naming it, restored blob == HEAD, git diff HEAD empty. metadata-protocol full vitest at 1777fb2d2: 317 files passed / 4 skipped, 22434 tests passed / 26 skipped; typecheck exit 0. .d.ts proof: base a1d0b1ee9 vs head 1777fb2d2, index.d.ts and index.d.cts cmp byte-equal (sha256 f7c56a2155a2b77a both); first proof at base c5800818 also byte-equal.",
  "gates": "dispatch-gates --commands at 1777fb2d2: 69 derived, each exit recorded before any pipe, 69/69 exit 0; --ran: 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN. Facade gate exit 0 (67 named exceptions). pnpm lint exit 0 at 63a626492; eslint over the 2 changed source files exit 0 at head. CI check-runs: in_progress at report time.",
  "line_budget": "267 changed lines (+251 / -16), 4 files; under 3000",
  "files_changed": [".changeset/30054-protocol-door-return-types.md", "packages/metadata-protocol/src/protocol.facade-door-return-types.pin.test.ts", "packages/metadata-protocol/src/protocol.ts", "scripts/facade-delegation-registry.json"],
  "deviations": [
    "Part of #30054, not Fixes: step 2 (move) not mechanical for protocol.ts, and the engine.ts half is serial behind #30055 (PR #30463 open), both per the order's fallback clauses.",
    "origin/main merged twice: after the first merge, #30427 (a7b8876f5) widened publishMetaItem's seedApplied receipt (landed); the first spelling would have narrowed the published type. Re-copied from a1d0b1ee9's build (commit 1777fb2d2) and re-proved.",
    "Changeset is patch, not skip-changeset: dist source maps ship in files[] and move with the new lines (recent facade PRs used skip-changeset)."
  ],
  "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm",
  "mcp_calls": "5 — issue_read x4 (#30054 get, #30054 get_comments x2, #30019 get), pull_request_read x1 (#30441 get); no write tool",
  "api_writes": "2 — relay pr_create (fw-20261105T135627Z-66d105, PR #30516), this os-dev-report comment via post-stamped. git push is not a REST write.",
  "open_questions": [
    {
      "question": "How should the eight protocol.ts bodies move?",
      "options": [
        "A: a tooling card for a facade pass in scripts/codemod-split-protocol.mjs (move a named member of the landed facade, as the engine codemod's later passes do), then this card's step 2 runs it",
        "B: accept the eight as standing exceptions with a reason, and close the protocol half at step 1"
      ],
      "recommendation": "A, because the gate's exception list is meant to shrink and the engine codemod already shows the pass shape; it is outside this card's file surface."
    }
  ],
  "security_findings": "none",
  "out_of_scope_findings": [
    "class: none (tooling limit, not a defect) · codemod-split-protocol.mjs has no pass over the landed facade and no longer re-proves from its base · carrier: seat 5 (open_questions A) · dedupe: protocol codemod facade pass, inferred-return-type move"
  ]
}

Report taken 2026-11-05T13:57Z.

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

PR #30516 (Part of #30054, step 1 of the protocol.ts half) is ACCEPTed, marked ready, and has auto-merge armed · 2026-11-05T14:02Z.

What is left on this card:

The protocol.ts body move is filed as codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518 (a codemod pass for a facade that has already landed).
The engine.ts half stays claimed here, Blocked-by: refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055 (PR refactor(objectql): type the six #4918 erasure-pinned ObjectQL methods and move their bodies out of engine.ts with the codemod's fourth pass #30463). The same thread does it after that PR merges.

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

Part 1 landed · 2026-11-05T15:40Z

PR #30516 merged as 43faa2201 at 2026-11-05T15:39Z.

The eight protocol.ts facade doors (getDiscovery, findData, getData, cloneData, saveMetaItem, publishMetaItem, rollbackMetaItem, deleteMetaItem) now spell their return types. The published index.d.ts / index.d.cts are byte-equal.
A pin (protocol.facade-door-return-types.pin.test.ts) keeps each annotation in place.

Still owed on this card:

engine.ts half (types and move for registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping, getStatus). Its serial blocker refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055 / PR refactor(objectql): type the six #4918 erasure-pinned ObjectQL methods and move their bodies out of engine.ts with the codemod's fourth pass #30463 merged at 15:17Z (4adc89090), so this half is now in progress in the same card thread.
protocol.ts body move for the eight doors. It needs a landed-facade pass in scripts/codemod-split-protocol.mjs first; that tool gap is codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518.

The card stays open.

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb
os-dev-report

Card thread session_01Utp6CXZTh9qvT24wTN6dd6 · branch claude/project-thread-alkkr9 · draft PR #30571 (engine.ts half) · head 2ea0deb9d

{
  "issue": 30054,
  "status": "rework",
  "branch": "claude/project-thread-alkkr9",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/30571",
  "head": "2ea0deb9d",
  "session": "session_01Utp6CXZTh9qvT24wTN6dd6",
  "premise_still_valid": true,
  "summary": "engine.ts half, opened as Part of #30054. All eight ObjectQL methods (registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping, getStatus) spell their return type, copied from the base build's declaration chunk. The #30055 --members pass moved five bodies (getStatus, triggerHooks, setDatasourceMapping, init, destroy) into their facets and their five registry rows are deleted; objectql core.d.ts, index.d.ts and util-DJB5AN6K.d.ts are byte-equal to base c23eafa88, and --members --verify --base 405373c08 exits 0. The pass refuses registerApp and registerDriver (engine-registration.ts header hand-edited) and fails its undo proof on registerHook (engine-hooks-and-functions.ts line 44), so those three rows stay with a rewritten reason. Still owed on the card: those three, plus the eight protocol.ts bodies waiting on #30518.",
  "tests": "pin src/engine.facade-return-types.pin.test.ts: 9/9 at head; 8/9 red on origin/main's engine.ts. Ablation via ablation-replace.mjs: init stub annotation removed (anchor 1->0, blob 2fa8f560->20c28b40), 1 failed / 8 passed naming init, restored blob == HEAD, git diff HEAD empty. Facade gate with the head registry over a detached origin/main worktree: exit 1, five problems, one per moved member; at head exit 0. objectql full vitest at 2ea0deb9d: 554 files, 11019 tests passed; typecheck exit 0.",
  "gates": "dispatch-gates --commands at 2ea0deb9d: 70 derived, each exit recorded before any pipe, 70/70 exit 0; --ran: 70 derived, 70 run, 0 NOT-MEASURED, 0 UNRUN. Facade gate exit 0 (56 named exceptions). eslint --no-inline-config over the 5 changed source files exit 0. CI check-runs: in_progress at report time.",
  "line_budget": "430 changed lines (+262 / -168), 7 files; under 3000",
  "files_changed": [".changeset/30054-objectql-return-types.md", "packages/objectql/src/engine-hooks-and-functions.ts", "packages/objectql/src/engine-migration-state.ts", "packages/objectql/src/engine-secrets-and-routing.ts", "packages/objectql/src/engine.facade-return-types.pin.test.ts", "packages/objectql/src/engine.ts", "scripts/facade-delegation-registry.json"],
  "deviations": [
    "Part of #30054, not Fixes: three engine.ts bodies are not mechanical with the --members pass, and the eight protocol.ts bodies wait on #30518.",
    "Branch not restarted from main: the force-with-lease push was refused by this session's permission classifier, so the branch merges origin/main over #30516's squashed commits (git diff origin/main empty before this PR's commits); the PR's commit list shows those old commits, its diff is the seven files only.",
    "Changeset is patch (dist source maps ship and move)."
  ],
  "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm",
  "mcp_calls": "8 — issue_read x4, pull_request_read x4 (#30441 get, #30516 get, #30516 get_status, #30571 get_files); no write tool",
  "api_writes": "4 in all for the card — relay pr_create x2 (PR #30516, PR #30571), os-dev-report comment x2 (6659827407 and this one). git push is not a REST write.",
  "open_questions": [
    {
      "question": "Where do the eleven rows still citing #30054 go?",
      "options": [
        "A: re-point the three engine.ts rows and the eight protocol.ts rows to #30518 (or a sibling tooling card for the engine codemod's two refusals), then #30054 closes on this PR's landing",
        "B: keep #30054 open until a codemod can move them"
      ],
      "recommendation": "A, because the remaining work is a codemod capability, not this card's type-spelling job."
    }
  ],
  "security_findings": "none",
  "out_of_scope_findings": [
    "class: none (tooling limit) · codemod-split-engine --members refuses engine-registration.ts (header hand-edited) and fails the undo proof for registerHook (engine-hooks-and-functions.ts import block) · carrier: seat 5 · dedupe: members pass header refusal, registerHook undo proof"
  ]
}

Report taken 2026-11-05T16:24Z.

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

Part 2 landed · 2026-11-05T17:23Z

PR #30571 merged as bfbdeeca2 at 2026-11-05T17:22Z.

All eight engine.ts ObjectQL methods on this card now spell their return types. The published @objectstack/objectql declarations are byte-equal.
Five bodies moved into their facets with refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055's --members pass: getStatus, triggerHooks, setDatasourceMapping, init and destroy. Their five registry rows are gone (56 named exceptions remain).

Still owed on this card (11 registry rows, all still naming #30054):

engine.ts: registerApp, registerDriver, registerHook. The --members pass refuses or cannot prove these moves, and the tooling gap is codemod-split-engine --members: move registerApp, registerDriver and registerHook out of the landed engine.ts facade (hand-edited engine-registration.ts header; registerHook's undo proof fails at the import block) #30572.
protocol.ts: the eight doors typed by PR refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516. Their move waits on the protocol codemod's landed-facade pass, codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518.

Blocked-by: #30518, #30572

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

Release: session_01Utp6CYVV6fcAQrNTDQRvPb · reason: clock-out (maintainer: server lane keeps only seat 2) · next: pm:blocked, Blocked-by: #30518, #30572

Both halves have landed what is mechanical today: PR #30516 (protocol.ts return types) and PR #30571 (engine.ts return types plus five body moves). The 11 remaining registry rows still name this card: protocol.ts's eight doors wait on #30518, and engine.ts's registerApp / registerDriver / registerHook wait on #30572. When both land, the bodies move and the rows are deleted with no new design.

Navigation Menu

Repository navigation

refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054

What to do

Triage: first-touch audit · p2 · `domain:server` · `pm:queue` · 2026-11-04T11:55Z

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054

Description

What to do

Activity

objectstack-fleet commented on Nov 4, 2026

Triage: first-touch audit · p2 · domain:server · pm:queue · 2026-11-04T11:55Z

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

objectstack-fleet commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Triage: first-touch audit · p2 · `domain:server` · `pm:queue` · 2026-11-04T11:55Z