Skip to content

docs: retire the stale "Where this is headed" federation forecast on extend-existing-systems - #257

Merged
os-bill merged 1 commit into
mainfrom
claude/issue-254-extend-existing-systems-federation-ships
Sep 2, 2026
Merged

docs: retire the stale "Where this is headed" federation forecast on extend-existing-systems#257
os-bill merged 1 commit into
mainfrom
claude/issue-254-extend-existing-systems-federation-ships

Conversation

@os-bill

@os-bill os-bill commented Sep 2, 2026

Copy link
Copy Markdown
Collaborator

Fixes #254

content/docs/extend-existing-systems.mdx told readers that turn-key external
datasource federation — one-step schema import, externally owned schema binding,
built-in safety gates — was "in active design" under ADR-0015 with status
Proposed, and that "until it lands" the manual path was the supported way. Every
one of those claims is stale at the source.

Measured on objectstack origin/main @ 87ad30c

The card's table was taken at 2514d49; upstream moved, so each leg was re-run at
the current tip rather than carried over. All five hold, at the same line numbers.

Claim on the page State at the source
"status: Proposed" ADR-0015 line 3: **Status**: Accepted — backend/REST/CLI implemented; Studio UI + extra dialect drivers pending
"one-step schema import" packages/cli/src/commands/datasource/{introspect,validate,list-tables}.ts all present; ADR-0062 R7 row reads ✅ shipped
"externally owned schema binding" SchemaModeSchema at packages/spec/src/data/datasource.zod.ts:238, wired at :651; ObjectExternalBindingSchema at packages/spec/src/data/object.zod.ts:1262, wired at :1919; ADR-0062 R1 row reads ✅ shipped
"built-in safety gates" packages/runtime/src/external-validation-plugin.ts present; ADR-0062 R6 and R5c rows both read ✅ shipped
"in active design … until it lands" The framework ships the guide at content/docs/data-modeling/external-datasources.mdx, whose stated headline guarantee is "declare an external datasource and it is visible, auto-connected, validated at boot, and queryable — with no application code"

One leg initially returned zero hits and was control-probed rather than reported:
the rollout ADR is docs/adr/0062-external-datasource-runtime.md, not the
-rollout filename the search assumed. Re-run against the real file, the four
rows above are present.

Why the section is deleted rather than rewritten

This page already routes the reader correctly, so a replacement paragraph would
have been the third page describing one surface. Verified on current main, not
assumed:

  • the "Start here" list links /docs/configure/data-sources (the body links it
    twice more, at "Connect the existing database as a datasource" and under
    "Generating objects with a coding agent");
  • configure/data-sources.mdx carries the pointer to the framework guide as of
    1034f5f — confirmed by rendering that page locally, where
    data-modeling/external-datasources appears in the served HTML.

So the reader reaches the owning guide in two hops, and this page makes no
federation claim of its own to go stale again. That follows #250's adjudication as
landed in 1034f5f: the mirror follows, it does not lead.

Nothing unique is lost. The section's closing clause ("the documented path —
connect, model, bind, query") restates "The shape of the move" at the top of the
same page, which is unchanged.

Per the card, the diff makes no claim about which dialect drivers or Studio
surfaces remain pending
. That forecast is what this lane keeps deleting, and a
smaller version of it here would be the third occurrence.

Locale siblings deliberately untouched

The seven siblings (.de, .es, .fr, .ja, .ko, .zh-Hans, .zh-Hant) are
byte-identical to base — each one's blob sha at HEAD equals its blob sha at
origin/main. They are generated artifacts, AGENTS.md forbids hand-editing them,
and what to do about the stale claim they inherit is an open decision on #256 that
governs them as a class across both pages. Not this PR's call, and left alone
deliberately rather than by oversight.

They were already stale before this diff, so the freshness gate's report is not
a new debt: the recorded source_sha in the siblings' frontmatter
(42c3777f…) does not match the sha256 of the English page at origin/main
(e2431d53…). Per AGENTS.md that staleness is reported, not blocking.

Local gates — all at 76579e5, this PR's head

Union re-run after the final commit, on a tree where git status is empty (so the
tested tree is exactly the committed one). Quoting each gate's own verdict line,
not a bare exit code:

Gate Its own conclusion
apps/docs/scripts/gen-zh-hant.mjs --check ✓ zh-Hant: 73 generated file(s) match the zh-Hans sources byte for byte.
check-translations.mjs ✓ translations gate passed
check-translation-ownership.mjs This PR touches 0 translation artifact(s) and 1 other file(s). — report-only, TRANSLATION_BOT_LOGIN is unset
check-node-floor.mjs --self-test ✓ self-test: 17 rule case(s), 24 satisfies case(s) and 18 range case(s) — every rule demonstrated able to fail
check-node-floor.mjs ✅ Every declared floor clears what the dependency tree requires, and the declarations agree.
turbo run type-check --continue Tasks: 1 successful, 1 total (tsc --noEmit executed on the pre-commit run of the identical tree; cache hit at 76579e5)
turbo run build Tasks: 1 successful, 1 total (same: executed pre-commit, cache hit at 76579e5)
check-locale-surface.mjs ✓ every advertised URL has a source file and every source file is advertisedsitemap.xml 409 read / 409 expected / 0 unexpected / 0 missing
turbo run test Tasks: 1 successful, 1 total; ✓ self-test: 18 case(s) over 10 rule(s) and 3 artifact(s) — every rule demonstrated able to fail

Build emits Failed to load dynamic font … self-signed certificate in certificate chain for the OG-card fonts. That is this container's egress proxy, unrelated to
the diff, and the build task still reports success.

Render check

Dev server on port 3254, page fetched over HTTP (HTTP 200, 114042 bytes). After the
edit the served HTML contains zero occurrences of Where this is headed,
turn-key federation, Proposed, in active design, and
0015-external-datasource-federation. Those zeros were control-probed against the
twin page served from the same process, where the same needles return 2 — so the
zeros are real absences, not a grep that cannot match. Rendered h2 ids are now
the-shape-of-the-move, why-this-works-without-a-rewrite,
generating-objects-with-a-coding-agent, what-you-get-on-day-one, start-here.
No file in the repo references the removed #where-this-is-headed anchor.

No changeset: this repo has no .changeset/ directory and publishes no packages.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ChPQM8jamxLUfUAxwFpJ8S


Generated by Claude Code

`extend-existing-systems.mdx` told readers that turn-key external
datasource federation — one-step schema import, externally owned schema
binding, built-in safety gates — was "in active design" under ADR-0015
with status *Proposed*. Every one of those claims is stale at the source
(objectstack `origin/main` @ 87ad30c):

- ADR-0015's own status line reads "Accepted — backend/REST/CLI
  implemented".
- One-step schema import: `packages/cli/src/commands/datasource/`
  {introspect,validate,list-tables}.ts; ADR-0062 R7 marked shipped.
- Externally owned schema binding: `SchemaModeSchema`
  (`spec/src/data/datasource.zod.ts:238`, wired at :651) and
  `ObjectExternalBindingSchema` (`spec/src/data/object.zod.ts:1262`,
  wired at :1919); ADR-0062 R1 marked shipped.
- Safety gates: `runtime/src/external-validation-plugin.ts` (R6) and the
  double opt-in write gate (R5c), both marked shipped.

The section is removed rather than rewritten. The page already routes the
reader correctly: "Start here" links /docs/configure/data-sources, and
that page carries the pointer to the framework guide that owns this
surface. Re-describing federation here would make this the third page
describing it — the mirror follows, it does not lead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ChPQM8jamxLUfUAxwFpJ8S
@os-bill
os-bill marked this pull request as ready for review September 2, 2026 19:47
@os-bill
os-bill merged commit ea9405b into main Sep 2, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[finding] extend-existing-systems.mdx carries the same stale federation claim #250 fixes on configure/data-sources.mdx

2 participants