Skip to content

refactor(objectql): spell the eight ObjectQL facade methods' inferred return types and move five bodies into their facets (.d.ts byte-equal) - #30571

Merged
objectstack-fleet[bot] merged 12 commits into
mainfrom
claude/project-thread-alkkr9
Nov 5, 2026
Merged

objectstack-fleet[bot] merged 12 commits into
mainfrom
claude/project-thread-alkkr9

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Requested by Bill · project thread

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

Part of #30054 (the engine.ts half: all eight return types spelled, five bodies moved; three engine.ts bodies and the eight protocol.ts bodies stay, see Acceptance notes)

Clause-②: no — the published index.d.ts, core.d.ts and the shared declaration chunk of @objectstack/objectql are byte-equal before and after, so no exported member changes.
Metadata-protocol: none
Skills-docs: none — an internal refactor of eight method signatures and five method bodies' location; no published type or behaviour changes, and no skill text names them.

What changes

  • Return types (engine.ts). registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping and getStatus declare their return type, copied from the line the base build printed for each in dist/util-*.d.ts (the ObjectQL class), re-indented to the file's two spaces. getStatus spells name: "data" with the printer's double quotes, which the declaration emit keeps.
  • Moves (--members). node scripts/codemod-split-engine.mjs --members getStatus,triggerHooks,setDatasourceMapping,init,destroy --write: getStatus and triggerHooks go to engine-hooks-and-functions.ts, setDatasourceMapping and init to engine-secrets-and-routing.ts, destroy to engine-migration-state.ts. Each method stays on the class with its docblock and signature as a one-call stub. Nothing generated is edited by hand.
  • Registry. The five moved members' rows are deleted (the gate refuses a row whose member is already a delegation). The three rows that stay keep card 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 and say why each body stays.
  • Pin. engine.facade-return-types.pin.test.ts parses engine.ts and requires each of the eight methods to carry its exact return type text.
  • Changeset. @objectstack/objectql patch: the declarations are byte-equal, but the shipped source maps move.

Tests

  • New pin: 9/9 at head. On origin/main's engine.ts (restored unstaged, then put back from HEAD, git diff HEAD empty) 8 of 9 fail, one per method.
  • Ablation (once, scripts/ablation-replace.mjs): init's stub annotation removed, anchor 1 → 0, blob 2fa8f560 → 20c28b40; the pin goes 1 failed / 8 passed, naming init; restored to the HEAD blob with git diff HEAD empty.
  • The facade gate is the pin for the moves: with the five rows deleted it is red on origin/main (five members with a body and no row) and green at head.
  • @objectstack/objectql full suite: 554 files passed, 11,019 tests passed at head 2ea0deb9d (and the same counts before the branch moved onto c23eafa88).
  • pnpm --filter @objectstack/objectql typecheck exit 0 at head.

Acceptance notes

Verification

Head 2ea0deb9d, base origin/main c23eafa88.

Declaration-file proof
  • Base: origin/main c23eafa88's engine.ts and its three facet modules restored into the head tree, turbo run build --filter=@objectstack/objectql..., core.d.ts, index.d.ts and util-DJB5AN6K.d.ts copied aside (byte-equal to the first base build at 8e5fabe58, from which the types were copied).
  • Head: pnpm build in packages/objectql (tsup with DTS, then check-dts-emitted); cmp against the base copies: all three byte-equal (util-DJB5AN6K.d.ts sha256 7f1e928b2f3aceac…). The same held after the annotation commit alone, before the move.
  • The diff of the emitted declarations is empty.
Codemod proof
  • --members getStatus,triggerHooks,setDatasourceMapping,init,destroy plan, then --write: output tree sha256 ebff07ef5c50e416… both times; "5 moved method(s) … engine.ts 11321 -> 11223 lines; undoing the moves does rebuild the base engine.ts and its modules byte-for-byte once the 7 import binding(s) only moved bodies read are pruned from the base".
  • --members --verify --base 405373c08 (the annotation commit, on this base) exit 0 with the same reading.
Gates
  • node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at head 2ea0deb9d: 70 derived commands (change set: 7 paths, +262 / -168, under the 3,000 threshold). Each ran with its exit code recorded before any pipe; all 70 exit 0. --ran reconciles 70 derived, 70 run, 0 NOT-MEASURED, 0 UNRUN.
  • node scripts/check-facade-delegation-only.mjs: "5 facade class(es) in 3 file(s) hold delegations only, 56 named exception(s)", exit 0. Against origin/main's tree (--root a detached c23eafa88 worktree, --registry this head's): exit 1, five problems, one per moved member.
  • eslint --no-inline-config over the five changed source files exit 0 at head.

Generated by Claude Code

claude added 12 commits November 5, 2026 12:23
…ight protocol.ts doors kept on the facade

Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6
Co-authored-by: Claude <noreply@anthropic.com>
… is spelled and why the body stays

Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6
Co-authored-by: Claude <noreply@anthropic.com>
…he seed receipt's landed rows from main

Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6
Co-authored-by: Claude <noreply@anthropic.com>
…ctQL methods kept on the facade

Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6
Co-authored-by: Claude <noreply@anthropic.com>
…g, init and destroy into their facets with the codemod's fourth pass

Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6
Co-authored-by: Claude <noreply@anthropic.com>
@github-actions github-actions Bot added the size/m label Nov 5, 2026
@github-actions github-actions Bot added documentation Improvements or additions to documentation tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql, touching 13 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

  • content/docs/data-modeling/external-datasources.mdx (via datasourceMapping (symbol, a field of interface SecretsAndRoutingHost; a method of class ObjectQL), datasourceMapping (literal, a string literal in datasourceMapping; a string literal in setDatasourceMapping))
  • content/docs/getting-started/quick-start.mdx (via datasourceMapping (symbol, a field of interface SecretsAndRoutingHost; a method of class ObjectQL), datasourceMapping (literal, a string literal in datasourceMapping; a string literal in setDatasourceMapping))
  • content/docs/protocol/kernel/error-handling.mdx (via registerApp (symbol, a method of class ObjectQL))
What this run could not see
  • 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 80 pages)
  • 2 name(s) were too generic to anchor anything (single lowercase words)
  • the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 103 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
  • a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
  • a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 21 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json db04e5ce581a92f349a532f52786c95acd7ec4ac → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c092574efa4571caf807f6c774d941358b1d140d — the merge of head 2ea0deb9d1f7dcf0aca872e2b5543e96e372fb9a into base db04e5ce581a92f349a532f52786c95acd7ec4ac, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c092574efa4571caf807f6c774d941358b1d140d && git checkout c092574efa4571caf807f6c774d941358b1d140d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin db04e5ce581a92f349a532f52786c95acd7ec4ac 2ea0deb9d1f7dcf0aca872e2b5543e96e372fb9a && git checkout -B drift-repro db04e5ce581a92f349a532f52786c95acd7ec4ac && git merge --no-ff 2ea0deb9d1f7dcf0aca872e2b5543e96e372fb9a

node scripts/docs-audit/affected-docs.mjs --json db04e5ce581a92f349a532f52786c95acd7ec4ac

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs db04e5ce581a92f349a532f52786c95acd7ec4ac → pass the list as
args.docs, on the commit named under Which tree this was computed on.

@objectstack-fleet

Copy link
Copy Markdown
Contributor Author

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

席位意见:同意落地,作为 #30054 的 engine.ts 半边。registerApp、registerDriver、registerHook 三个方法体 codemod 搬不动,已另立工具卡 #30572;protocol.ts 的 8 个方法体等 #30518。这 11 行登记仍挂在 #30054 上,所以 #30054 保持打开,Blocked-by #30518 和 #30572,不在本 PR 里改挂登记表。

席位核对

Head 2ea0deb9d1f7dcf0aca872e2b5543e96e372fb9a · 2026-11-05T16:27Z

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

Labels

documentation Improvements or additions to documentation size/m tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant