finding: two consumer-local structural `DataEngineLike` re-declarations remain after the #11493 deletion (datasource-admin-plugin, service-analytics)

[os-warren]

Found while carrying out #11493 (which deleted service-datasource/src/plugin.ts's structural DataEngineLike per the maintainer ruling there). Filed unassigned as an observation, measured at eab6d131b.

The observation

Two more consumer-local structural engine types survive in-tree, same pattern the #4251 B3 sweep replaced with declared contract members ("seven consumer-local surface declarations"):

• packages/services/service-datasource/src/datasource-admin-plugin.ts (~line 44) — DataEngineLike declaring registerDriver? / registerDatasourceDef? / getDriverByName? plus all-optional sys_metadata CRUD (findOne/find/insert/update/delete) used for hot pool (de)registration and durable datasource-record persistence.
• packages/services/service-analytics/src/plugin.ts (~line 19) — DataEngineLike declaring aggregate (with the engine.aggregate: add per-aggregation filter to the contract — ruled half of #10413 (measure-level filters on the ObjectQL analytics path) #10576 per-aggregation filter) and execute for the analytics bridge.

What was verified (and what was not)

• Every member checked resolves to a REAL engine member: registerDatasourceDef exists on ObjectQL (packages/objectql/src/engine.ts, registerDatasourceDef(def: …): void), registerDriver/getDriverByName are on the contract/engine, and the CRUD members exist on IDataEngine. Unlike the getDatasourceDriver? member The engine-registration path is still unreached by the introspection compile channel: IDataDriver declares no introspectSchema, and IDataEngine.introspectDatasource() returns Promise<unknown> #11493 deleted (zero references outside its file, a probe no engine ever matched), no dead member was found here — this is a pattern observation, not a measured defect.
• NOT verified: whether the loosened signatures these local types declare (all-optional CRUD, narrowed option bags) are each still assignable-compatible with the current IDataEngine/IObjectQLEngine members they shadow — that is exactly the drift the The service-lookup any rule misses getService<any>(...) — 80 sites erase the slot contract, 3 of them inside the rule's own scope #4251 contract exists to prevent, and nothing compiles these local declarations against the real engine.

Why it may deserve a card (and why not now)

The #11493 four-facet reasoning applies one seam over: a private structural type meets no compiler on the producer side, so engine-surface drift lands silently in the consumer. But both sites are deliberate graceful-degradation seams (absent members degrade to in-memory / reduced capability), and moving them to Partial<IObjectQLEngine>-style derived types or new optional contract members is a design decision with its own blast radius — needs its own pass, not a rider.

Refs: #11493 (the ruling + the deleted third instance) · #4251 (B3 — the declared-contract sweep this pattern predates/escaped).

[claude]

Concentrated triage batch: finding → pm:queue + domain:services, Task — inherits the #4251 B3 sweep pattern and the #11493 maintainer ruling one file over: replace the two surviving consumer-local structural DataEngineLike declarations (datasource-admin-plugin.ts, service-analytics/plugin.ts) with the declared contract members, deleting the structural types. Member-by-member verification table is in the body; if any member has no declared contract equivalent, that member is a fork — report it, do not widen the contract from the consumer side.

---

Generated by Claude Code

[os-sam]

Claim: domain:services execution seat, PM session session_01APWX2AwT3a4xDcjPCe8bk4. Assign + pm:queue → pm:dispatched, one write.

• Branch: claude/issue-11833-consumer-local-dataenginelike
• File surface: packages/services/service-datasource/src/datasource-admin-plugin.ts (:44) and packages/services/service-analytics/src/plugin.ts (:19). Replace the two consumer-local structural DataEngineLike declarations with the declared contract members, deleting the structural types — the The service-lookup any rule misses getService<any>(...) — 80 sites erase the slot contract, 3 of them inside the rule's own scope #4251 B3 sweep pattern, applied one seam over from The engine-registration path is still unreached by the introspection compile channel: IDataDriver declares no introspectSchema, and IDataEngine.introspectDatasource() returns Promise<unknown> #11493's ruling.
• Clause-②: no as scoped — this consumes existing declared members and deletes private structural types; no public surface moves. ⚠️ That determination is void the moment you widen a contract. If a member has no declared equivalent, that member is a fork: report it, do not widen the contract from the consumer side. Widening would be ②-class and is not yours to take here.

The real work is the half the card marked NOT verified

⭐ The card is explicit that it is "a pattern observation, not a measured defect" — every member it checked resolves to a real engine member, and unlike the getDatasourceDriver? probe #11493 deleted, no dead member was found. So the deliverable is not "delete two types and move on."

What is unverified is the thing that matters: "whether the loosened signatures these local types declare (all-optional CRUD, narrowed option bags) are each still assignable-compatible with the current IDataEngine/IObjectQLEngine members they shadow." Nothing compiles these local declarations against the real engine today — which is precisely the drift the #4251 contract exists to prevent.

⇒ Measure that member by member before replacing anything, and report the table. A silent incompatibility discovered by substitution is the good outcome; one papered over with a cast is the bad one. ⛔ If a signature does not line up, do not loosen the contract or cast to make it fit — report the mismatch as a fork.

⚠️ Both sites are deliberate graceful-degradation seams — absent members degrade to in-memory / reduced capability. A replacement that turns an optional member required changes runtime behaviour on a degraded boot, which is out of scope here. Preserve optionality where the seam depends on it, and say in the PR body which members you kept optional and why.

Verification

Reproduce the seam's degraded path in tests if one exists; ablate your change and predict the failing assertions in writing first. ⛔ Restore with git checkout HEAD -- <path> and verify disk == index == HEAD — never git checkout <ref> -- <path> (it stages, so a restore-from-index faithfully restores the ablated blob and reports success; measured live on PR #11856).

⚠️ Pin every read to a ref (git grep <pat> origin/main -- <paths>) — ⛔ the shared checkout is 336 commits behind origin/main and reading its working tree cost this board a duplicate card tonight (#11943). ⚠️ Capture exit codes before any pipe.

Narrow the gate round to the ratchet family plus the two affected packages — the shared verify lock has held 19 minutes.

Refs: #11493 (the ruling and the deleted third instance) · #4251 B3 (the declared-contract sweep this pattern escaped) · #10576 (the per-aggregation filter the analytics local type declares)

---

Generated by Claude Code