Repository navigation
docs: the external-systems guide gains the OData datasource section and the three-way choice (declarative OData, plugin driver, DataSync mirror) — epic #27261 P2 #27747
Description
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Filing gate: ③ maintainer-directed — 田騏 at 2026-10-29T21:58Z 「现在启动全部 P2」 (epic comment 6509296853, D1 amended), at 2026-10-29T21:59Z 「OData 驱动 只做 v4」 (6509311454), at 2026-10-29T22:01Z 「同意」 (generic P2 parts open source in this repository; vendor-specific drivers such as Salesforce stay out of it).
Ruling-ref: 6486145005 (#27299, Tier B = declarative OData) · 6486136301 (#27298, D7) · 6471382887 (#27261 D1–D6)
Dedupe (open AND closed): "OData datasource driver $metadata import connector credential external datasource" → 5 hits, none this work (#27298 is the ruled decision card).
Reader: the epic PM (#27261) dispatches it in the epic subtree.
Blocked-by: #27741
type: Feature
维护者速读
- 做什么： 指南加一节：用 OData 声明式接入 SAP / Dynamics 365 的完整示例，以及什么时候该写插件驱动、什么时候该用 DataSync 同步成真表。
- 需要您做的： 无。
Task
-
content/docs/data-modeling/virtual-objects.mdx(or a sibling page): an OData datasource + object binding example, pushdown and the floor explained, write gates, auth throughcredentialsRefand (once landed) a connector instance. - The three-way rule: OData endpoint available ⇒ declarative; no OData, computed rows or a private API ⇒ plugin driver; slow-changing reference data ⇒ real object + DataSync.
- A note that Salesforce exposes no OData for its own data, so it takes a driver of its own.
Clause-②: no · Metadata-protocol: none.
Activity
objectstack-fleet commentedon Oct 30, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Claim: PM loop round 11 2026-10-30T01:38Z
Session:
session_017ihL2c5z3q4h8inrn5kwqV(epic PM); implementing card threadsession_017ihL2fzEsUhDQ2VCWQJ5euAccount:
marchtianBranch:
claude/project-thread-uz3qfd(the card thread's platform-assigned branch — measured platform exception toclaude/issue-<n>-<slug>)Worktree:
objectstack-issue-27747Domain:
domain:devxSeat:
epic:#27261#1(epic PM; nodomain:*seat). Maintainer order, 田騏 2026-10-29T21:58Z: 「现在启动全部 P2」 (ruling 6486145005, Tier B = declarative OData)File surface:
content/docs/data-modeling/**(virtual-objects.mdxor a sibling page: the OData datasource section, the three-way choice, the Salesforce note), the docs nav/meta file a new page needs,packages/drivers/driver-odata/README.md(cross-link only) (stop on breach, including anyskills/**orpackages/spec/src/**edit; explain in the report)Container & model:
S,mode:thread,model: default tier (dispatch-gates --tier: no path-derived mandate),effort: highClause-②: no
Metadata-protocol: none
Responsibility: epic #27261 P2 (ruling 6486145005), unblocked by #27741 (PR #27796,
0a4b0fb223)Thread-read: none
Premise: holds — on
origin/main(0a4b0fb2)driver-odatais published, and no guide page shows an OData datasource or says when to choose declarative OData, a plugin driver, or a DataSync mirror.Serial constraints: auth through
credentialsRefonly. Theexternal.connectormention belongs to #27786 (Blocked-by #27746); do not write it here. The pointer to #27744's conformance kit goes in this PR if #27798 is onmainbefore this PR is ready; otherwise the epic PM moves it to #27786. Every example must parse against the schema onmain.objectstack-fleet commentedon Oct 30, 2026
epic:#27261#1 · marchtian · session_017ihL2fzEsUhDQ2VCWQJ5eu
os-dev-report
{ "issue": 27747, "status": "done", "branch": "claude/project-thread-uz3qfd", "pr": "https://github.com/objectstack-ai/objectstack/pull/27871", "head": "c62ec8e2", "session": "session_017ihL2fzEsUhDQ2VCWQJ5eu", "premise_still_valid": true, "summary": "New page content/docs/data-modeling/odata-datasources.mdx (check the service: v4 only, a key per entity set, auth; mount createODataDriverPlugin with its option table; an os:check datasource + object binding; credentials through external.credentialsRef only, bearer/basic/none, first-request resolve and 401 re-resolve, fail-closed; what the service is asked behind the floor, the never-narrower rule, nextLink paging, the 1000-row cap; writes by key with If-Match and the refusal mapping; the sharing-model choice; a failure table; what it does not do). virtual-objects.mdx: 'Virtual, or a real object?' becomes 'Which way in: OData, a plugin driver, or a real object' with the card's three rules in order, plus the Salesforce note (no OData for its own records, so a plugin driver over its REST API); the SAP example and See also point to the OData page. external-datasources.mdx callout and See also route OData v4 services there. Nav: meta.json, the module index block, scripts/docs-audit/handwritten-docs.json. driver-odata README: one cross-link, with a patch changeset. No external.connector mention, no conformance-kit pointer (#27798 not on main), per the Claim.", "tests": "No code changed. The os:check block parsed through defineStack from packages/spec/src (tsx) on main's schema; the mount example's options parsed through parseODataDriverConfig, and the four refusals the page names were each refused as described. Every claim read off driver-odata at 0a4b0fb2 (config, plugin, transport, filter, odata-driver, floor and conformance tests) and, for os serve, packages/cli/src/commands/serve.ts.", "gates": "dispatch-gates --commands derived 88 families (71 before the changeset, index row and audit-scope row); all run, exit codes recorded before any pipe. First pass red: check-section-landing-index and check:docs-audit-scope (new page not listed), both fixed; check:skill-examples, check:dual-build-cjs-loads, check:lean-entry-closure exit 3 until ./packages/** was built. Final --ran: 88 derived, 88 run, 0 NOT-MEASURED (a DERIVED zero). origin/main merged at c62ec8e2 (12 commits, none on these files); doc-anchors, section-landing-index, docs-audit-scope green after. PR check-runs at report time: 23 listed, 3 skipped, 20 in_progress, 0 failure.", "dogfood_battery": "n/a: docs-only, no ! in the title, Clause-② no", "mcp_calls": "github issue_read x3 (#27747 get, get_comments x2), pull_request_read x3 (#27798 get, #27783 get, #27871 get_check_runs), subscribe_pr_activity x1 (platform subscription); no MCP write tool", "api_writes": "2: relay pr_create (run 40991535965, PR #27871, body 7915 bytes read back identical, assignee marchtian); relay comment on #27747 (this report). git push is not a REST write.", "surface_note": "scripts/docs-audit/handwritten-docs.json and content/docs/data-modeling/index.mdx were edited because their gates require every new hand-written page to be listed (read as 'the nav/meta file a new page needs'); .changeset/27747-odata-guide-readme-link.md because the README ships in the package.", "open_questions": [ { "question": "Is os serve's missing secret-store handoff to a stack's OData plugin a card, or does #27746's credential seam cover it?", "options": [ "A: file a card (devx/runtime): os serve exposes its datasource secret resolver to stack plugins, e.g. as a kernel service the OData plugin reads when options.secrets is absent", "B: leave it; the external.connector path (#27746/#27786) is the supported route on os serve, and the page's own-resolve advice stands for credentialsRef" ], "recommendation": "A, because credentialsRef is the documented channel and on os serve a sys_secret handle minted by the Add Datasource wizard cannot reach the OData plugin today" } ], "out_of_scope_findings": [ "carrier: epic PM · os serve builds its sys_secret binder inline (serve.ts) and passes it only to DatasourceAdminServicePlugin; no kernel service exposes it, so createODataDriverPlugin({ secrets }) on os serve cannot resolve a sys_secret: handle (documented on the page, not filed)", "carrier: #27786 · the conformance-kit pointer (virtual-objects.mdx step 3 and the OData page) once #27798 lands" ] }objectstack-fleet commentedon Oct 30, 2026
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
Landed · 2026-10-30T03:24Z
PR #27871 merged through the queue as
6e53003828on 2026-10-30T03:02:57Z (headc62ec8e2; seat ACCEPT 6513650694, the review of record for a no-contract-face PR). The guide gainsdata-modeling/odata-datasources.mdx, andvirtual-objects.mdxopens with the three-way rule and the Salesforce note. Follow-ons: #27875 drops theos servecredential caveat; #27745 (PR #27880) rewrites the "$metadata" bullet; #27786 adds theexternal.connectorand conformance-kit mentions.