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

Activity

1. objectstack-fleet

   added

   enhancementNew feature or requestNew feature or request

   priority:p2Medium: important, M3Medium: important, M3

   domain:devx

   pm:epic

   area:data

   on Oct 29, 2026
2. objectstack-fleet commented on Oct 30, 2026

   

   objectstack-fleetBot

   on Oct 30, 2026

   ContributorAuthor

   More actions

   epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
   Claim: PM loop round 11 2026-10-30T01:38Z
   Session: session_017ihL2c5z3q4h8inrn5kwqV (epic PM); implementing card thread session_017ihL2fzEsUhDQ2VCWQJ5eu
   Account: marchtian
   Branch: claude/project-thread-uz3qfd (the card thread's platform-assigned branch — measured platform exception to claude/issue-<n>-<slug>)
   Worktree: objectstack-issue-27747
   Domain: domain:devx
   Seat: epic:#27261#1 (epic PM; no domain:* seat). Maintainer order, 田騏 2026-10-29T21:58Z: 「现在启动全部 P2」 (ruling 6486145005, Tier B = declarative OData)
   File surface: content/docs/data-modeling/** (virtual-objects.mdx or 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 any skills/** or packages/spec/src/** edit; explain in the report)
   Container & model: S, mode:thread, model: default tier (dispatch-gates --tier: no path-derived mandate), effort: high
   Clause-②: 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-odata is 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 credentialsRef only. The external.connector mention 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 on main before this PR is ready; otherwise the epic PM moves it to #27786. Every example must parse against the schema on main.
3. objectstack-fleet

   added

   pm:dispatched

   on Oct 30, 2026
4. objectstack-fleet

   assigned

   marchtian

   on Oct 30, 2026
5. objectstack-fleet commented on Oct 30, 2026

   

   objectstack-fleetBot

   on Oct 30, 2026

   ContributorAuthor

   More actions

   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"
    ]
   }
6. objectstack-fleet

   closed this as completedin #27871on Oct 30, 2026
7. objectstack-fleet commented on Oct 30, 2026

   

   objectstack-fleetBot

   on Oct 30, 2026

   ContributorAuthor

   More actions

   epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
   Landed · 2026-10-30T03:24Z

   PR #27871 merged through the queue as 6e53003828 on 2026-10-30T03:02:57Z (head c62ec8e2; seat ACCEPT 6513650694, the review of record for a no-contract-face PR). The guide gains data-modeling/odata-datasources.mdx, and virtual-objects.mdx opens with the three-way rule and the Salesforce note. Follow-ons: #27875 drops the os serve credential caveat; #27745 (PR #27880) rewrites the "$metadata" bullet; #27786 adds the external.connector and conformance-kit mentions.
8. objectstack-fleet

   removed

   pm:dispatched

   on Oct 30, 2026