[objectstack-fleet]

Requested by 田騏 · project thread

Fixes #27276

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:只加两份测试,零产品代码。一份在 runtime 里用插件发布的驱动起完整栈(REST、鉴权、权限集、共享),把卡上 (a)–(e)、(g) 逐步钉在驱动实际收到的调用上;一份在 plugin-gantt 里证 (f) 甘特树、锁和拖拽写回。
• 为什么改: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 要实测「虚拟对象挂插件驱动」这条路今天哪步通、哪步不通,作为 [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 的依据。七步都走得通,但第五步 (e) 要把对象设成 public_read_write;留在平台默认共享模型时,持有编辑权的成员也改不了任何外部行,现状钉在 (e3)。
• 风险与回滚:只有测试文件,不发布(两个包都只发 dist,构建产物里零命中、正控命中);回滚即删两文件。runtime 那份起整套内核,单文件约 30 秒。
• 先看:packages/runtime/src/plugin-driver-external-object.spike.test.ts 的 (e3) 段(默认共享下的缺口)和 (c) 段(驱动收到的 DriverQuery 原样);再看 ui/packages/plugin-gantt/src/ObjectGantt.pluginDriverTree.test.tsx。
• 两分钟验证:pnpm --filter @objectstack/runtime exec vitest run src/plugin-driver-external-object.spike.test.ts,预期 Tests 12 passed (12)。
• 需要你做的:无,席位落地。

What changes

Two test files, no product code.

• packages/runtime/src/plugin-driver-external-object.spike.test.ts (12 tests). A plugin publishes driver.spike_tree, an in-memory stand-in for a remote system that records every call it receives and refuses every method or operator outside the spike by name. defineStack declares a datasource on it (schemaMode: 'external', validation: { onMismatch: 'fail', checkOnBoot: false }, allowWrites: true, no introspectSchema on the driver) and two external objects: spike_node (a tree with parent, depends_on, a current_user formula locked, a beforeUpdate hook with a PLAN_LOCKED refusal, a gantt list view) and spike_owned (left on the platform's default sharing model). The kernel boots the real REST, auth, security and sharing plugins over it, and each step is asserted on what reached the driver, not on what the engine says it sent.
• ui/packages/plugin-gantt/src/ObjectGantt.pluginDriverTree.test.tsx (4 tests). The real GanttView over the records that read serves: the tree, the formula lock on the rendered bars, and the write a pointer drag produces.

Why

#27276 asks, before any platform change in #27261, which of the seven steps a virtual object on a plugin driver passes today. Each step is now a test; the one that does not pass is pinned as it behaves, so the change that lifts it turns that test red on purpose.

Tests

Step	Verdict	What the test pins
(a)	passes	driver: 'spike_tree' with config: {} resolves to the plugin's driver.spike_tree service; the engine routes spike_node to that instance; the connection service reports already-registered and leaves it alone; the boot calls connect once.
(b)	passes	The boot completes with onMismatch: 'fail' and checkOnBoot: false on a driver with no introspectSchema, and no syncSchema is sent. A later validateAll() reports spike_node ok: false, so the opt-out is what lets it boot.
(c)	passes	The plan view's filter and sort, sent as the console sends them, arrive at driver.find as { where: { archived: false }, orderBy: [{ field: 'start_date', order: 'asc' }], limit: 50, object: 'spike_node' }. No fields, no offset. A separate count with the same where follows.
(d)	passes	The formula over current_user.id is computed engine-side per caller: the same row reads locked: false for the planner and locked: true for the administrator.
(e)	passes on sharingModel: 'public_read_write'	A hook refusal answers 409 RESOURCE_CONFLICT, declaredCode: 'PLAN_LOCKED', with the catalogue message, and update is never sent. An allowed write reaches driver.update last with the patch, the hook's stamp, and the engine's id, updated_at, updated_by; the returned row is served with the formula recomputed.
(e3)	does not pass on the default sharing model	A member whose permission set grants allowEdit gets 403 PERMISSION_DENIED on every row of spike_owned: the sharing check reads owner_id and the ownership floor reads created_by, and no remote row carries either.
(f)	passes (unit)	The parent renders as a summary bar, the children as task bars, the dependency as a link; the formula lock removes the resize grips and blocks the drag; dragging the unlocked bar calls dataSource.update('spike_node', 'n_cut', { start_date, end_date }). The adapter's PATCH /data/:object/:id is pinned in packages/client/src/client.test.ts:2177.
(g)	passes	A user whose permission sets grant nothing on spike_node gets 403 on the list read with zero driver calls, and 403 on a PATCH after one by-id findOne and no write.

Acceptance notes

• (e3), the one step that does not pass. Smallest platform change: an os validate warning (a warning, since a defineStack refusal would narrow it) for an external object left on an owner-keyed sharing model with no owner column mapped, naming both ways out (public_read_write plus a hook, or a columnMap to an owner column). Left for the seat to file as a sub-card of [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.
• Read cost the spike measured, for 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: every PATCH reads the pre-image from the remote three times by id, and every list read is a find plus a separate count.
• Shape notes for the guide in 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: object rides inside the DriverQuery although the type omits it, and driver.update receives the audit stamps updated_at and updated_by plus id, so a driver's writable column set has to accept them or drop them.
• A denied PATCH still costs the remote one by-id read before the 403.

Verification

Head 680ce37b, branched from b4458075; main has since moved 11 commits, none in the paths this diff reaches, and the gate derivation on current main with this diff applied is the same 53 commands. Local runs on a shared box, so seconds are shared-box seconds.

Spike tests: 12/12 and 4/4

$ pnpm --filter @objectstack/runtime exec vitest run --maxWorkers=2 src/plugin-driver-external-object.spike.test.ts
 Test Files  1 passed (1)
      Tests  12 passed (12)
   Duration  29.86s
$ (cd ui/packages/plugin-gantt && npx vitest run --root ../.. packages/plugin-gantt/src/ObjectGantt.pluginDriverTree.test.tsx)
 Test Files  1 passed (1)
      Tests  4 passed (4)

Package suites and type-checks

$ pnpm --filter @objectstack/runtime exec vitest run --project local --maxWorkers=3   (at 44269895; the runtime file is unchanged since)
 Test Files  469 passed (469)
      Tests  7641 passed | 19 skipped (7660)
$ pnpm --filter @objectstack/runtime typecheck            (tsc + check:test-typecheck)   exit 0
$ pnpm exec turbo run type-check --filter=@object-ui/plugin-gantt   Tasks: 48 successful, 48 total   (at 44269895)
$ (cd ui/packages/plugin-gantt && npx tsc -p tsconfig.test.json)   exit 0   (at 680ce37b)
$ (cd ui/packages/plugin-gantt && pnpm test)   (at 44269895)
 Test Files  102 passed | 1 skipped (103)
      Tests  772 passed | 114 skipped (886)
$ eslint (root config, --no-inline-config) on both files   exit 0, no warnings

680ce37b changed only the gantt test's schema annotation (typed as ObjectGanttHandoff, so type: 'object-gantt'); its file and the test-program type-check were rerun there.

Derived gates: 53 of 53, all exit 0

Second pass at 680ce37b. node scripts/pm/dispatch-gates.mjs --ran on the recorded exit codes: 53 derived, 53 run, 0 NOT-MEASURED, 0 UNRUN (a derived zero).

The first pass at fbd9e598 had five non-zero exits. Two were this diff and are now green: check:slot-lookup (two lookups typed any; now typed with their contracts) and check:where-matcher (the lift pulled in a module-level declaration named in the matcher's message text; the text no longer names it). Two were exit 3, prerequisite not met (check-plugin-teardown-shape --self-test needed its pinned fixture fetched; check:dual-build-cjs-loads needed built dist/), and both pass on rerun. pnpm --dir ui exec vitest run scripts/ failed on 31 unresolved @objectstack/* imports before dist/ was built plus one 15s timeout under load; rerun after the build: 174 passed, 2 skipped (176 files, 4990 tests).

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (Not touched.)
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes. (Root eslint run on both files, exit 0.)
• 4. One issue, one branch off an up-to-date main, one pull request. (Branched at b4458075; main has moved 11 commits since, none in these paths.)
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (Nothing publishes: skip-changeset.)
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (Not touched.)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English. (The 维护者速读 block is Chinese by the seat's PR-body rule.)
• The Before Submitting list in CONTRIBUTING.md is done.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 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 — 0 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 cf43b6c38091eb15b5d0a4edcfc2080442018568 → packageMentionDocs.

[objectstack-fleet]

epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
ACCEPT · PR #27330 @ 680ce37bfed8ed3f4bba3f9127e01b9242eebfae · 2026-10-28T17:56Z

维护者速读

• 改了什么： 只加两个测试文件、零产品代码：在完整启动的内核里，用插件发布的自定义 driver 承载一个外部对象，逐步证明 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 的七步（数据源指向插件 driver、免内省启动、视图筛选排序到达 driver.find、按当前用户计算的锁公式、beforeUpdate 拒绝与放行、甘特拖动发出更新、权限集 403）。
• 为什么改： 它是 [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 专题与 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 客户方案的地基，也是指南 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 的可执行样例。
• 风险与回滚： 只有测试，两个包的 dist 里没有它们；还原即回滚。
• 先看： packages/runtime/src/plugin-driver-external-object.spike.test.ts 的 (e3) 用例，以及甘特侧的 ObjectGantt.pluginDriverTree.test.tsx。
• 两分钟验证： 单跑 runtime 的 spike 文件（12 例）与 plugin-gantt 的 spike 文件（4 例）。
• 需要你做的： 无，席位落地。

席位意见：ACCEPT。七步全部通过；第 (e) 步只在 public_read_write 下通过，默认共享模型下成员一律 403，已立 #27332。

席位核对

1. Shape: diff read by the seat (2 test files, +751/−0). The driver records every call; assertions are on what the remote is asked, not on the platform's self-report. The driver refuses unsupported operators by name instead of matching silently.
2. Premise measured: all seven card steps have a test; (e3) pins the default-sharing refusal as current behaviour, so the fix card 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 will flip it on purpose.
3. Gate check-runs on 680ce37b: 68 runs — 55 success, 13 skipped, 0 failed or pending; mergeable_state: clean. Dev local: 53 gate families derived and run, all exit 0.
4. Accepted deviations: branch claude/project-thread-ms6480 (platform exception, in the claim); step (f) is a plugin-gantt unit test with the adapter→PATCH hop cited from packages/client/src/client.test.ts.
5. Out of scope: (e3) filed as 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; performance and driver-contract readings carried as comments on 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 (6476230469) and 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 (6476246771). Clause-②: no · Metadata-protocol: none · Skills-docs: none — tests only.
6. Landing: not governed (check-governed-merges --pr 27330: 0 of 2 paths, 751 lines ≤ 3000). The seat's landing stroke on feat(studio): external-object fields show their datasource and write state; no DDL controls on an external object #27316 was refused by the session's permission classifier; this PR waits for the maintainer's landing call the same way.