[Decision] Ontology over external systems: virtual objects on ADR-0015 federation — two driver tiers (plugin code · declarative OpenAPI), pushdown/identity/catalog/cache rules, Studio and AI drafts (2026 ontology research + deep design) #27261

epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Epic PM session: session_017ihL2c5z3q4h8inrn5kwqV (project thread, account marchtian). Phase plan agreed with the maintainer in that thread; see the registration comment.

Ruled: 6471382887 · letters D1 both-in-order · D2 object.external · D3 non-goal · D4 off · D5 off · D6 P1/P2 · 2026-10-28T14:19Z

Epic: ontology over external systems (virtual objects on ADR-0015 federation) · pm:epic · opened by the director seat (summon #53, session_01QSeKYo7qYsX6HsAneHBMP2) on ruling 6471382887 (maintainer 「立专题卡」, then 「原则同意，按步骤推进。」 2026-10-28).

Territory (declared): packages/objectql/src (driver routing, in-memory query helper, row cap, refusal mapping), packages/spec/src/contracts/data-driver.ts (supports reading only; P2 adds object.external.operations / idField under packages/spec/src/data/object.zod.ts and external-catalog.zod.ts), packages/runtime/src/external-validation-plugin.ts, ui/packages/app-shell/src/views/metadata-admin (read-only marking; P2 datasource page), content/docs (the guide). P2 adds packages/drivers/driver-openapi when pulled.

Children

P0 (now)

• spike(objectql): a virtual object on a plugin driver — external-bound object boots without introspection, reads with filters, formula over current_user, beforeUpdate hook → driver.update, gantt drag writes (epic #27261 P0 · #27130 route d) #27276 spike: virtual object on a plugin driver — seven steps, one line each in the report · server · S · pm:epic (also the first step of object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level api source (read + write) #27130)

P1 — Tier A formal (P0 landed as PR #27330; #27279 → PR #27316; #27278 → PR #27349; #27332 → PR #27422; #27277 → PR #27403; #27425 → PR #27476; #27472 → PR #27639; #27471 → PR #27648)

• objectql: virtual-object correctness floor — applyDriverQueryInMemory helper, per-datasource row cap with a loud refusal, supports honoured for plugin drivers, refusal-envelope mapping for driver failures (epic #27261 P1) #27277 objectql: applyDriverQueryInMemory + row cap + supports honoured + refusal envelope · M
• docs: "a virtual object — rows from your server, shown in any view": plugin-driver recipe, five business examples, the three-way rule, driver shape-pin test; the #27130 customer reply (epic #27261 P1) #27278 docs: the virtual-object guide, five examples, three-way rule, shape-pin test; the object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level api source (read + write) #27130 customer reply · S
• access: an external object on the default sharing model refuses every member edit (403) because the ownership checks read owner_id / created_by, which no remote row carries — os validate says nothing (epic #27261, found by the P0 spike) #27332 access: an external object on the default sharing model refuses member edits — os validate warning (from the P0 (e3) step) · S
• ui(studio): external-object fields show their datasource and read-only state; no DDL affordances on an external object (epic #27261 P1, D6 first half) #27279 ui(studio): external-object fields marked with datasource and read-only; no DDL affordances · S · unblocked from spike(objectql): a virtual object on a plugin driver — external-bound object boots without introspection, reads with filters, formula over current_user, beforeUpdate hook → driver.update, gantt drag writes (epic #27261 P0 · #27130 route d) #27276 by the maintainer, runs beside P0
• sharing: a private external object whose driver serves owner_id without declaring it in fields gives every member every row — hasPhantomOwnerAnchor reads fields only, so the read filter goes unscoped (epic #27261, found by #27332's dev) #27425 security: a private external object whose driver serves an undeclared owner_id reads unscoped — fail closed · p1 · server · found by access: an external object on the default sharing model refuses every member edit (403) because the ownership checks read owner_id / created_by, which no remote row carries — os validate says nothing (epic #27261, found by the P0 spike) #27332's dev
• objectql: a plugin driver's by-name read refusal (the guide's refuse()) reaches the caller as 503 "may clear; retry later" with its message withheld — the floor maps every find throw to ERR_DATASOURCE_UNAVAILABLE (epic #27261, follow-up of #27277) #27471 objectql: a plugin driver's by-name read refusal surfaces as 503 "retry later" · follow-up of objectql: virtual-object correctness floor — applyDriverQueryInMemory helper, per-datasource row cap with a loud refusal, supports honoured for plugin drivers, refusal-envelope mapping for driver failures (epic #27261 P1) #27277
• lint: security-owd-unset's hint recommends sharingModel 'private' on a writable external object, the shape that refuses every member edit and that security-external-owner-unmapped warns against (epic #27261) #27472 lint: security-owd-unset recommends private on a writable external object · follow-up of access: an external object on the default sharing model refuses every member edit (403) because the ownership checks read owner_id / created_by, which no remote row carries — os validate says nothing (epic #27261, found by the P0 spike) #27332
• service-datasource: a runtime-origin or reconnected plugin-driver datasource loses the #27277 external-driver floor, because the connection service registers the datasource def without its driver id and unregisterDriver drops the stored one (epic #27261) #27666 service-datasource: a runtime-origin or reconnected plugin-driver datasource loses the floor (driver id not registered) · p2 · server · from fix(objectql)!: floor a plugin driver on an external datasource — the engine applies the query, up to 1000 rows #27403's post-landing record 6502877381
• spec: resolveInjectedColumnProvenance does not know the external.columnMap → owner_id arm plugin-sharing honours since #27425, so the #7858 convergence row and the two columnMap readers diverge (epic #27261) #27661 spec: one reader for "owner anchor provable" (columnMap → owner_id arm) · p3 · spec · from fix(plugin-sharing)!: an unproven owner anchor on a federated object narrows the read and bulk-write scopes, never leaves them unscoped #27476's post-landing record 6493803142 · by pull
• plugin-sharing: the #8418 phantom-anchor write-deny diagnostic goes silent on a federated object that maps owner_id through external.columnMap over a plugin driver that ignores the map (epic #27261) #27662 plugin-sharing: [裁定确认] #8119 的裁定是 A(什么都不做)还是 C(保持 deny + 加诊断)?联邦 phantom 锚上的写门拒绝是完全静默的,且现已知在每个方言上都如此 #8418 write-deny diagnostic silent on a mapped owner over a map-ignoring plugin driver · p3 · server · from 6493803142 · by pull

P2 — Tier B declarative OpenAPI (filed on the second customer pull, D1): spec external.operations + idField + catalog source: 'openapi' (S) · driver-openapi (L) · Studio datasource page + import (M) · generateObjectDraft for OpenAPI (S) · showcase example (S).

• [Decision] Ontology over external systems: an API-backed external datasource authenticates through a connector instance's credential (one Connect per vendor for actions and records), its own auth block, or static credentialsRef only (epic #27261) #27298 [Decision] how an API-backed datasource authenticates (connector credential / own auth block / credentialsRef only) · needs-user-decision
• [Decision] Ontology over external systems, Tier B: which declarative dialect — OpenAPI as designed, OData first (the dialect Salesforce Connect and Dataverse ship), or chosen per pull by the source's protocol (epic #27261, amends D2's premise) #27299 [Decision] Tier B's declarative dialect (OpenAPI as designed / OData first / per pull) · needs-user-decision; decide before P2's children are filed

Critical path: #27276 → #27277 / #27278 / #27279 (parallel) → #27130 unblocks on #27276 + #27278 (unblocked 2026-10-29). P1 remainder: #27425 (p1, security) first.

P3 — by pull, not filed (maintainer ruling 6487532394 on #27277, plus seat carries): verified-pushdown credential (conformance kit → the engine sends offset/limit to a trusted plugin driver); count reusing the candidate set; driver-memory converging on the engine evaluator; an engine semi-join so a controlled_by_parent external object (a ReadableIds leaf, refused today) can be read. P2 prerequisite: now card #27666 (the connection service registers datasource defs without driver, and unregisterDriver drops the stored id on reconnect).

Filing gate ③ (maintainer-directed). The maintainer, in the director summon (session_01QSeKYo7qYsX6HsAneHBMP2, 2026-10-28), after the #27130 route-d design: 「这个可以用来对接外部系统，定义本体吗？」 → 「你帮我深度设计一下，这个需求更大」 → 「你可以上网搜索调研一下目前主流的本体开发需求，以及和我们项目的匹配」. This card carries the research and the design; the maintainer rules on the decision points in §9. ⛔ Not a claim. No domain:*: triage sets (spec + server expected). Dedupe: ADR-0015 (external datasource federation, Accepted; Studio UI pending), #27130 (the first customer pull, route d), #8345 (unrelated), no open card designs API-backed federation or an OpenAPI datasource.

Ruling-ref: none yet (decision card). Prior rulings read: federation|external datasource|virtual|schemaMode|external_catalog → ADR-0015 §1–§6 (one Object shape; three gates; external_catalog; IExternalDatasourceService; non-goals: cross-datasource joins, distributed transactions, reverse DDL); ADR-0049; ruling C on #23082 (view-level api retired; the governed door wins); #27130 design 6468011868.

维护者速读

• 一句话： 把「行住在哪」从「我们的库 / 联邦数据库」扩到「任何有 API 的系统」，本体层（对象、关系、动作、权限、流程、Agent 工具）一个字不改；主流平台 2026 年的本体需求我们已有七成，缺的正是这一块加 Studio/AI 的「从外部系统生成本体草稿」。
• 要裁的： §9 的六个决策点（两档都做还是只代码档；声明档映射键放哪；跨源联查保持非目标；缓存默认关；写回默认关；Studio 范围）。
• 工作量： P0 spike S（object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level api source (read + write) #27130）；P1 代码档正式化约 3 个 M；P2 声明式 OpenAPI 数据源约 1 S + 2 M + 1 L；P3 增强按拉动。总计约 12–18 个 agent 天，分三次可独立交付。
• 推荐： D1 两档都做但按序（代码档先，声明档等第二个客户）；D2 映射放 object.external；D3 保持非目标；D4 关；D5 关；D6 Studio 先只读。

1. Research: mainstream ontology needs in 2026, and the match

Sources are search summaries quoting the vendors' docs; palantir.com and learn.microsoft.com are not reachable from this session's network, so their pages were read through those summaries only.

Positioning read. Palantir and Fabric IQ sit over lakehouses for analysis and decisions; Dataverse, ServiceNow and ObjectStack are OPERATIONAL ontologies — the ontology is the app (views, forms, flows, actions). Our differentiators hold: the ontology is written by AI and refused loudly when wrong, is diffable in the customer's repository, exportable, self-hostable. The one mainstream capability we lack in that operational class is the Dataverse "virtual table over an API with a custom provider" and its declarative OData sibling. That is exactly #27130's pull, generalized.

2. Goal and non-goals of this design

Goal. An external system's entities become ontology objects without moving data: rows are read through a driver (plugin code now; a declarative OpenAPI driver later), every consumer (views, reports, permissions, hooks, audit, MCP, SDK) sees a normal Object (ADR-0015 §3.1), writes go through the platform's gates. Non-goals (kept from ADR-0015 §2.2 and added): cross-datasource joins pushed down (reads across sources are id-based lookups and in-memory expands), distributed transactions, reverse DDL, replacing DataSync for bulk mirrors, an edits-overlay for read-only sources, natural-language rules, a lakehouse zero-copy engine.

3. Conceptual model (five layers, two driver tiers)

Ontology layer    object · field · relationship · action · permission · flow · agent/tool   (unchanged)
Binding layer     object.datasource → datasource.schemaMode ≠ managed → object.external { remoteName, writable, columnMap, [operations] }
Datasource layer  managed DB · federated DB (ADR-0015, driver-sql …) · API / computed (THIS: plugin driver, OpenAPI driver)
Driver layer      IDataDriver + supports (pushdown capabilities) + optional introspectSchema / registerExternalObject
Integration layer connectors (rest / openapi / mcp / imap / slack) — outbound actions from flows; unchanged, complementary

Tier A — plugin driver (code): a server plugin publishes driver.<name> (plugin.ts:1145–1158); find / findOne / count / update as the system allows; the rest refuse by name. Any system, any computation. (#27130's route d.)
Tier B — declarative OpenAPI driver: one platform driver openapi that reads a datasource config { driver: 'openapi', config: { spec: ref, baseUrl, auth: credentialsRef, pageStyle, rateLimit } } and an object binding external.operations { list, get, create?, update?, delete? } naming operationIds plus a idField; the driver maps DriverQuery to query parameters it can push down (declared per object: filterable / sortable / pageable fields) and does the rest in memory. Reuses connector-openapi's document parsing (ADR-0023). No code for the standard REST case.

4. Protocol surface (spec) — kept minimal

• Tier A: zero spec change. Everything is already in the contract: plugin-contributed driver ids (datasource.zod.ts:186), schemaMode external, external.allowWrites, external.validation.checkOnBoot (datasource.zod.ts:316), object.external (object.zod.ts:1296), IDataDriver.supports for pushdown.
• Tier B: two additive keys (Metadata-protocol: added, minor): object.external.operations (optional; refused unless the object's datasource driver is openapi; each entry an operationId that must exist in the referenced document — checked at build) and object.external.idField (optional; default id). The openapi driver's config shape lives in the driver's own config contract (driver/config-registry.zod.ts), not in the datasource schema. external_catalog gains source: 'openapi' with the document hash as the drift signal.
• Not added: any URL on a view or page element (ruling C stands); a parallel external_object type (ADR-0015 §3.1); a cache key on the object (caching is datasource config).

5. Runtime rules (the three ADR-0015 gates, extended to API sources)

1. DDL gate: unchanged — forbidden on external objects.
2. Boot validation: DB sources introspect; API sources validate the OpenAPI document hash against the catalog snapshot and, when checkOnBoot is true, perform one list probe with limit 1; a plugin driver with no introspectSchema is validated by its own contract test (the guide requires one "shape pin" test per driver).
3. Write gate: allowWrites (datasource) AND writable (object) AND, for Tier B, the operation named (update without operations.update refuses at build). Writes are per record, one system at a time; enforceTransactionOrigin keeps cross-datasource writes where ADR-0057 put them.
4. Pushdown and fallback: the driver's supports says what it pushes down (filters, sort, pagination, in, aggregate); the engine applies the remainder in memory through ONE shared helper (@objectstack/objectql exports applyDriverQueryInMemory), with a hard row cap per datasource (config.maxRows, default 1,000 — the ServiceNow figure) and a loud refusal above it: "narrow the filter or mirror via DataSync".
5. Identity: idField must be stable and unique in the source; columnMap maps names only. Relationships across sources are id-based lookups; expands batch through find with an in filter when supports.inFilter, else findOne per id under the row cap.
6. Caching: off by default; config.cache: { ttlSeconds } per datasource caches find results keyed by query for that TTL; writes invalidate. Never for managed.
7. Errors: driver / HTTP failures map to the platform refusal envelope (EXTERNAL_SOURCE_UNAVAILABLE, EXTERNAL_WRITE_REFUSED with the source's message), never a silent empty list.
8. Credentials: only external.credentialsRef; the egress allow-list per datasource host is a deployment setting, not metadata.
9. Permissions and audit: object permission sets and RLS apply unchanged; every external write is audited with the datasource name.

6. Studio and AI

• Studio (ADR-0015's pending half): a Datasources page listing managed / federated / API sources with health and catalog drift; an external object's fields shown read-only with their source; for Tier B an "import object from OpenAPI" flow that calls generateObjectDraft on the document's schema components (N6) and lets the author pick operations.
• AI: the same generateObjectDraft is an MCP tool (list_remote_tables / import_object are already in the service contract); the guide gives AI authors the three-way rule — computed rows, data that must not land, or real-time ⇒ virtual object; slow-changing reference data ⇒ real object + DataSync flow.

7. Phases and workload

Totals: P0 ≈ 0.5 agent-day; P1 ≈ 3–4; P2 ≈ 8–10; P3 by pull. About 12–15 agent-days through P2; calendar 4–6 weeks at two lanes. Each phase ships on its own: P1 serves the #27130 class of customer; P2 serves the no-code ERP / HR / MES integrations.

8. Risks

• Silent wrong rows when a driver ignores filters → the in-memory helper is applied by the ENGINE on anything the driver's supports does not claim; a driver cannot opt out of correctness, only of performance.
• Unbounded reads → the row cap refuses loudly; the guide names DataSync for mirrors.
• Source shape drift → catalog hash + boot probe (Tier B); shape pin test (Tier A).
• Credential leakage into metadata → only credentialsRef; the build refuses inline secrets (existing rule).
• Two doors for writes → none: the view-level api stays retired; all writes are driver.update under the gates.
• Over-building Tier B before a second customer → P2 is gated on pull (D1).

9. Decision points for the maintainer (defaults bold)

• D1 Tiers: both, in order — Tier A now (P0–P1), Tier B when a second customer asks for a no-code REST source / Tier A only / both now.
• D2 Tier B mapping keys live on object.external.operations + idField / on the datasource config.
• D3 Cross-datasource joins pushed down: stay a non-goal (ADR-0015 §2.2); id-based lookups and in-memory expands only.
• D4 Caching: off by default, opt-in TTL per datasource.
• D5 Writes: off by default (ADR-0015 double opt-in stands), per-operation for Tier B.
• D6 Studio: read-only field marking in P1; datasource page + OpenAPI import in P2 / all in P1.

os-decision-facets

• ① 项目长远合理性：本体层零改动、外部性仍是绑定的属性（ADR-0015 §3.1），两档 driver 补齐 Dataverse 式「虚拟表 + 自定义/OData 提供者」；不新增 api 视图源、不新增并行对象类型。
• ② 实际业务拉动：object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level api source (read + write) #27130 是第一个实测生产者（代码档）；声明档等第二个客户（ERP/HR/MES 的无代码接入）再建。
• ③ 防 AI 犯错：行、写回、锁定、权限全部是平台判定的元数据；driver 不能选择性忽略筛选（引擎兜底）；超行上限、形状漂移、缺操作映射全部响亮拒收。
• ④ 创业阶段不扩散：代码档零协议；声明档只加两个可选键；缓存、写回默认关；跨源联查、编辑覆盖层、自然语言规则不做。
  Prior rulings read: ADR-0015 §1–§6, ADR-0049, ADR-0057 §3.6, [Decision] Does a view's api data source adopt the page-element rule — a same-origin url and no headers written in metadata? #23082 C (6134088274), spec(ui): a page element dataSource can name an API endpoint (provider: 'api'), so a product page composes from a control-plane summary in metadata instead of a product-specific React widget (maintainer ruling 2026-10-12) #23016, object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level api source (read + write) #27130 (6467643796 / 6468011868) → 6 hits; thread: none.

After the ruling

D1 both-in-order ⇒ #27130 proceeds as ruled (P0 spike card first); this card becomes the P1/P2 epic parent (pm:epic) with P1 children filed after the spike passes and P2 children filed on the second pull; the guide card lands with P1. Tier-A-only ⇒ the same without P2. Both-now ⇒ P2 children filed at once, spec first.