Repository navigation
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
Description
Blocked-by: #27276
Filing gate ③ (maintainer-directed). Ruling 6471382887 on #27261 (batch #423, maintainer 「立专题卡」 2026-10-28): the ontology-over-external-systems epic opens with Tier A (plugin driver, zero protocol change). Part of #27261. Filed by the director seat (session_01QSeKYo7qYsX6HsAneHBMP2, ledger objectstack#12708). ⛔ Not a claim; triage sets the lane and grade. Design: #27261 body; the first customer pull: #27130 (route d, design 6468011868).
Ruling-ref: 6471382887
维护者速读
- 改了什么： 指南：虚拟对象的完整配方（数据源、外部绑定对象、
current_user公式锁、beforeUpdatehook、视图）+ driver 骨架 + 五个业务例（港口排程、SAP 订单、HR 目录、设备实时状态、反例：慢变参考数据用真对象 + DataSync）+ 三分法 + driver 形状 pin 测试模板。 - 为什么改： 这是回复 object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level
apisource (read + write) #27130 客户的配方，也是 AI 作者照抄的样板。 - 风险与回滚： 纯文档；配方以 P0 的测试为可执行示例。
- 先看：
content/docs/（数据建模 / 集成）；P0 测试文件。 - 两分钟验证： docs-audit 通过；按配方在本地跑通 P0 测试的例子。
- 需要您做的： 文档落地后由分诊席在 object-gantt can no longer write back to a same-origin endpoint after #23082 — a measured producer of the retired view-level
apisource (read + write) #27130 线程用席位的话回复客户（不复述其指令形文字）。
Task
- Write the guide from the P0 test; the three-way rule (computed / must-not-land / real-time ⇒ virtual; slow reference data ⇒ real object + DataSync).
- Driver skeleton and the shape-pin test template.
- docs-audit affected-docs green.
Clause-②: no · Metadata-protocol: none. Size S. Lane: devx.
Epic: #27261 (parent; the epic PM dispatches pm:epic children). Dedupe: #27261, #27130, ADR-0015; no open card carries this slice.
Activity
objectstack-fleet commentedon Oct 28, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Lane
domain:devx, as the card declares ("Lane: devx",content/docs). Written by the epic PM on the maintainer's instruction (ruling 3 in the registration comment on #27261: 田騏, 「同意」, the epic PM's project thread). Stayspm:blockedon #27276: the guide is written from the P0 test.objectstack-fleet commentedon Oct 28, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
P0 readings for the guide (spike #27276, report 6476152968, PR #27330 @
680ce37b; the runtime spike test is the recipe's executable example):driver: 'spike_tree'withconfig: {}for a plugin publishingdriver.spike_tree;external.validation.checkOnBoot: falseis what lets a driver withoutintrospectSchemaboot.owner_id/created_by, which remote rows do not carry — filed as access: an external object on the default sharing model refuses every member edit (403) because the ownership checks readowner_id/created_by, which no remote row carries —os validatesays nothing (epic #27261, found by the P0 spike) #27332. The guide must tell authors to usesharingModel: 'public_read_write'and decide who may edit in thebeforeUpdatehook (the spike's pattern), or map an owner column.driver.updatereceives the patch plusid,updated_at,updated_byand any hook stamps; the driver skeleton should say what to do with columns the remote does not have.objectrides inside theDriverQuerypassed tofind/countalthough the type omits it.objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Unlock · 2026-10-29T01:07Z
Blocked-by: #27276is closed (PR #27330 merged as13f53603);pm:blockedremoved. The card stays in the epic subtree (pm:epic) and is dispatched by the epic PM once the maintainer answers the P1 go/no-go question in the epic PM thread. The P0 readings for this card are in the comment above.objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Claim: PM loop round 2 2026-10-29T01:24Z
Session:
session_017ihL2c5z3q4h8inrn5kwqVAccount:
marchtianBranch:
claude/project-thread-6ml89f(this container can push only its designated branch; restarted fromorigin/main6d7634a after PR #27316 merged — measured platform exception to theclaude/issue-<n>-<slug>convention)Worktree:
objectstack-issue-27278Domain:
domain:devxSeat:
epic:#27261#1(epic PM; nodomain:*seat)File surface:
content/docs/**(a new guide page undercontent/docs/data-modeling/plus navmeta.jsonand cross-links fromexternal-datasources.mdx/drivers.mdx) (stop on breach; explain in the report)Container & model:
S, not mechanical (writing judgment) → M treatment,mode:subagent,model: default tier (dispatch-gates --tier: no path-derived mandate),effort: highClause-②: no
Metadata-protocol: none
Responsibility:
n/a — not a defect cardThread-read: 6485035600
Premise: holds — on
origin/main6d7634a no page undercontent/docsgives the plugin-driver virtual-object recipe;content/docs/data-modeling/external-datasources.mdxanddrivers.mdxcover federated databases and drivers. The executable example is on main:packages/runtime/src/plugin-driver-external-object.spike.test.ts(PR #27330). #27277's "Driver shape pin test template in the guide (P1-2)" item is carried by this card.Serial constraints cleared: none (sibling #27277 touches
packages/objectql/srconly; the guide must not claim #27277's helper or row cap exists until it lands)objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
os-dev-report
{ "issue": 27278, "status": "done", "branch": "claude/project-thread-6ml89f", "pr": "https://github.com/objectstack-ai/objectstack/pull/27349", "session": "session_017ihL2c5z3q4h8inrn5kwqV", "premise_still_valid": true, "summary": "New page content/docs/data-modeling/virtual-objects.mdx: three-way rule table, plugin-driver recipe worked as a port berth plan (driver skeleton, plugin, one defineStack block with datasource / external object / current_user lock formula / beforeUpdate guard with declared refusals / gantt view / permission set), the driver-correctness rules (#27277 floor named as planned only), the sharing-model callout linking #27332, a measured what-the-driver-receives table, the driver shape-pin test template, five business examples. Linked from external-datasources.mdx, drivers.mdx, data-modeling/index.mdx and meta.json; handwritten-docs.json regenerated. Card prose 'DataSync' taught as the live mapping+job pull (DataSyncConfig is retired).", "tests": "Docs-only diff. Probes (deleted after): page's driver skeleton + plugin + defineStack block booted in the reference test's kernel harness behind an in-memory transport, 6/6 pass under lock (VERDICT command-exit 0): list read -> find(filter archived eq false, sort start_date asc, limit 50) + count; formula locked false planner / true admin; locked PATCH 409 RESOURCE_CONFLICT declaredCode PLAN_LOCKED; admin PATCH 403 PERMISSION_DENIED declaredCode NOT_PLANNER, no remote write; planner PATCH = 3 by-id reads + 1 patch with exactly start_date,end_date,plan_note; outsider list 403; driver-refused filter 500 INTERNAL_ERROR. Shape-pin template vs skeleton 5/5. Reference spike test on base 6d7634a9 12/12. Reverse verification of the two os:check blocks: injected type errors -> check:skill-examples exit 1 naming virtual-objects.mdx:140:17 and :288:7; restored via git checkout HEAD, blob hash equal. credentialsRef probe (service-datasource, base 6d7634a9): pre-registered driver -> already-registered, resolver calls 0 (with and without secret store); not pre-registered -> failed-credentials / connected (resolver calls 1). Head beadd67a.", "gates": { "head": "beadd67a", "derive": "node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack -> 53 families", "ran_reconciliation": "Run reconciliation — 53 derived, 53 run, 0 NOT-MEASURED, 0 UNRUN (exit 0)", "local": [ "node scripts/check-adr-links.mjs :: exit 0", "node scripts/check-adr-links.mjs --self-test :: exit 0", "node scripts/check-closing-keyword-parity.mjs :: exit 0", "node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0", "node scripts/check-comment-mask-corpus.mjs :: exit 0", "node scripts/check-doc-route-spelling.mjs --advisory :: exit 0", "node scripts/check-doc-route-spelling.mjs --self-test :: exit 0", "node scripts/check-docs-section-name.mjs :: exit 0", "node scripts/check-docs-section-name.mjs --self-test :: exit 0", "node scripts/check-section-landing-index.mjs :: exit 0", "node scripts/check-section-landing-index.mjs --self-test :: exit 0", "node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0", "node scripts/docs-audit/check-affected-docs.mjs :: exit 0", "node scripts/docs-audit/check-drift-comment.mjs :: exit 0", "pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0", "pnpm --filter @objectstack/lint run check:doc-security-posture :: exit 0", "pnpm --filter @objectstack/spec run check:docs :: exit 0", "pnpm --filter @objectstack/spec run check:empty-state :: exit 0", "pnpm --filter @objectstack/spec run check:liveness :: exit 0", "pnpm --filter @objectstack/spec run check:skill-examples :: exit 0", "pnpm --filter @objectstack/spec run check:strictness-ledger :: exit 0", "pnpm --filter @objectstack/spec run check:variant-docs :: exit 0", "pnpm --filter @objectstack/spec run check:yaml-examples :: exit 0", "pnpm check:agent-test-spelling :: exit 0", "pnpm check:bash32-floor :: exit 0", "pnpm check:ci-filter-parity :: exit 0", "pnpm check:cli-command-ids :: exit 0", "pnpm check:closed-ceremony-text :: exit 0", "pnpm check:corpus-claim-drift :: exit 0", "pnpm check:cross-package-test-inputs :: exit 0", "pnpm check:doc-anchors :: exit 0", "pnpm check:doc-authoring :: exit 0", "pnpm check:doc-frontmatter :: exit 0", "pnpm check:docs-audit-scope :: exit 0", "pnpm check:docs-redirects :: exit 0", "pnpm check:docs-single-h1 :: exit 0", "pnpm check:docs-spec-enumerations :: exit 0", "pnpm check:docs-transcript-drift :: exit 0", "pnpm check:driver-memory-census :: exit 0", "pnpm check:entry-guard :: exit 0", "pnpm check:gitlink-declared :: exit 0", "pnpm check:nul-bytes :: exit 0", "pnpm check:parse-guard :: exit 0", "pnpm check:pnpm-filter-targets :: exit 0", "pnpm check:pnpm-flag-spellings :: exit 0", "pnpm check:published-readme-links :: exit 0", "pnpm check:react-page-adapter-contract :: exit 0", "pnpm check:refd-timer-probe :: exit 0", "pnpm check:role-word :: exit 0", "pnpm check:scripts-symbol-anchors :: exit 0", "pnpm check:skill-identifier-liveness :: exit 0", "pnpm check:vendor-version-stamps :: exit 0", "pnpm check:watch-hint-literal :: exit 0" ], "notes": [ "first pass: check-section-landing-index exit 1 (index card missing) -> fixed in beadd67a; check:skill-examples exit 3 PREREQUISITE NOT MET until client-react closure built with declarations", "docs-audit affected-docs: node scripts/docs-audit/check-affected-docs.mjs exit 0; affected-docs.mjs origin/main exit 0, 0 docs (no packages change)" ], "ci_check_runs_at_report": { "Check Changeset": "skipped (skip-changeset label)", "Check PR Size": "queued", "Check Documentation Links": "in_progress", "Governed Surface Queue Guard": "in_progress", "PR-body guards": "in_progress", "Packed-tarball smoke (opt-in)": "skipped", "18.x upgrade harness (opt-in)": "skipped" } }, "dogfood_battery": "n/a — no ! in the PR title and no (narrowing) arm", "line_budget": "size S; +554 / -1 over 6 files (virtual-objects.mdx 541 lines new; cross-links +12/-1; handwritten-docs.json +1); under the 3000 human-merge threshold", "deviations": [ "branch claude/project-thread-6ml89f (PM-set container exception), not claude/issue-27278-slug", "PR footer is the PM-prescribed ending, not the os-dev session-URL footer form", "PR body names the final head beadd67a; pr_create landed while the remote head was a7adc6d7, beadd67a pushed 1 minute later (body unchanged, now accurate)", "labels skip-changeset sent at pr_create (docs-only, no package files[] ships content/docs); read back on the PR" ], "files_changed": [ "content/docs/data-modeling/virtual-objects.mdx", "content/docs/data-modeling/external-datasources.mdx", "content/docs/data-modeling/drivers.mdx", "content/docs/data-modeling/index.mdx", "content/docs/data-modeling/meta.json", "scripts/docs-audit/handwritten-docs.json" ], "mcp_calls": "6 — read only: issue_read get #27278, issue_read get_comments #27278, issue_read get #27332, issue_read get #27277, pull_request_read get #27349, pull_request_read get_check_runs #27349; zero write tools", "api_writes": "2 relay writes — fleet-write pr_create (PR #27349, read-back identical 8848 bytes, assignee marchtian, label skip-changeset) and this os-dev-report comment via post-stamped.mjs; plus 2 git pushes (not REST)", "open_questions": [ { "question": "Plugin-driver credentials: the epic's rule says credentials only through credentialsRef, but the connect step skips credential resolution for a driver a plugin already registered. The page states that fact and points to the plugin convention (host passes options). Which channel should Tier A use?", "options": [ "A: platform hands the resolved credentialsRef to a plugin driver (e.g. connect-time secret injection) and the page is updated", "B: bless host-composed plugin options as the Tier A channel and amend the standing rule", "C: refuse at boot a credentialsRef on a datasource whose driver is plugin-registered, so it is not silently ignored" ], "recommendation": "A plus C meanwhile, because the ruling's intent (no secrets in metadata, one channel) survives and the silent ignore closes" } ], "out_of_scope_findings": [ "class: b · Seam: spec:DatasourceSchema.external.credentialsRef -> runtime:DatasourceConnectionService.attemptConnect (already-registered return precedes credential resolution) · contract: external-datasources.mdx §4 'if a credentialsRef is declared but no secret store is configured ... the datasource is left unconnected with a clear error' · reach: seam-level vitest probe only, no public-door measurement · dedupe: credentialsRef plugin driver already-registered secret not resolved fail-closed", "carrier: epic #27261 (Tier A credentials rule) · noted in PR Acceptance notes, not filed" ] }objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Landing held · PR #27349 @
beadd67a· 2026-10-29T02:25ZACCEPT is on the PR (6486170157); every check on
beadd67ais green or skipped andmergeable_stateisclean. The landing stroke was refused before it ran, so nothing was written:node scripts/pm/fleet-write/dispatch.mjs --repo objectstack-ai/objectstack --actions-file Fwith[{"op":"pr_ready","pull":27349},{"op":"automerge_enable","pull":27349}]The seat stops here and asks the maintainer; no other spelling is tried. The PR stays draft until the maintainer says how to land it.
objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Ruling carried · 2026-10-29T04:01Z
The maintainer's #27277 ruling (6487532394) names three guide passages:
All three describe the floor that #27277 ships. PR #27349 stays as accepted (6486170157): it is correct for
main, where the floor is "planned". The passages land in #27277's PR, after #27349 merges (amendment on #27277). This card's scope is unchanged.objectstack-fleet commentedon Oct 29, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Landed · 2026-10-29T04:36Z
01516dc0270ff479f55456d093a764109962509f(merge queue), headbeadd67acompletedbyFixes #27278State:
pm:dispatchedremoved in the same act. Landed by the epic PM after seat ACCEPT 6486170157, on the maintainer's order (田騏, 2026-10-29T04:19Z): 「你应该使用 pm-dispatch 技能处理 issue 和 pr 落地」. Downstream: #27130's lastBlocked-byis closed; the customer reply there is the triage seat's (card 维护者速读). The three guide passages from the #27277 ruling land with #27277's PR (6487546052).