docs(skills): the datasources rule states that default is host-reserved, connected from OS_DATABASE_URL, and refused in a stack's datasources (#23768)

[objectstack-fleet]

Fixes #23768
Clause-②: no

What

skills/objectstack-data/rules/datasources.md L5–6 read "Most apps need only the default datasource; declare more to read/write a separate or external database." "Declare more" implies that default is declared too, which is the shape the stack's datasources collection now refuses. The two lines are replaced by four:

(default: `'default'`). `default` is host-reserved: the host connects it from
`OS_DATABASE_URL`, and a stack that declares a datasource named `default` is
refused. Declare a datasource under its own name only to read/write a
**separate** or **external** database.

Each clause checked against the base 0b1179f33 (origin/main when the branch was cut; one commit past the dispatch's 0a168a33e, in packages/services/service-storage — datasources.md and the ratchet script are byte-identical between the two):

• "Objects route to one via their datasource field (default: 'default')" stays: packages/spec/src/data/object.zod.ts L2482, datasource: z.string().optional().default('default').
• "default is host-reserved … a stack that declares a datasource named default is refused": packages/spec/src/stack.zod.ts, HOST_RESERVED_DATASOURCE_NAME = 'default' and refuseHostReservedDatasourceName, the superRefine on STACK_DEFINITION_COLLECTIONS_SHAPE.datasources (so defineStack, os validate and publish refuse it, located at datasources.N.name); packages/runtime/src/app-plugin.ts L1261–1266 refuses the same at boot ("that name is reserved for the host's primary datasource").
• "the host connects it from OS_DATABASE_URL": packages/runtime/src/default-datasource-plugin.ts (DefaultDatasourcePlugin declares and connects default); the spec's own refusal prescribes "set OS_DATABASE_URL and omit this entry". packages/runtime/src/resolve-project-database.ts resolves the host's database by priority — an explicit URL, then the environment (OS_DATABASE_URL), then a datasourceMapping rule { default: true, datasource: NAME } naming a datasource the stack declares under its own name (a rule naming default yields nothing there), then the unified default file. The sentence names the environment rung, the one the refusal prescribes; it does not say it is the only one.
• "Declare a datasource under its own name only to read/write a separate or external database": the card's Expected wording, and the refusal's remedy ("declare it under another name (e.g. 'app_primary') and route objects to it explicitly").

Nothing the spec does not declare is stated.

Token payment — two deletions in the same file, both restatements of the field reference

The added words cost more than the 8 tokens of headroom, so two sentences this file carried in duplicate of packages/spec/src/data/datasource.zod.ts (the field reference L8 points at; src/**/*.zod.ts is in @objectstack/spec's files[]) are deleted:

1. L17–18 (a blank line and "external settings are required when schemaMode !== 'managed'."). DatasourceSchema's superRefine refuses the omission itself — schemaMode='X' requires 'external' settings. — and the external field's TSDoc reads "Required when schemaMode !== 'managed'". An author who omits it is refused at authoring with the remedy; the skill loses no rule.
2. L58's second sentence, "Set autoConnect: true to force a live connection." Item 3 of the auto-connect list four lines above already names autoConnect: true as a trigger, and the field's describe() is "Force a live driver connection at boot even when managed + unrouted". L57 is byte-identical; L58 now ends at "not connected."

No re-wrap anywhere: L3–4 and L57 are byte-identical, the four new lines carry the inserted text, and the only line-count changes are the insertion (+2) and the deletion (−2).

Readings (skills/**)

reading	before (0b1179f33)	after (5dd8c0a8c)
datasources.md lines	80	80 (net 0; hard cap +1 unused)
datasources.md bytes	3609	3612
skills/objectstack-data/**/*.md lines (the package)	3717	3717
all ten skills/*/SKILL.md lines (the catalog)	4408	4408
check-skills-token-ratchet, datasources.md	903 tokens (ceiling 911; headroom 8)	903 tokens (ceiling 911; headroom 8)
check-skills-token-ratchet, bundle total	155020	155020

Verdict lines verbatim — before: ✓ check-skills-token-ratchet: skills/objectstack-data/rules/datasources.md is 903 tokens (ceiling 911; headroom 8). — after: ✓ check-skills-token-ratchet: skills/objectstack-data/rules/datasources.md is 903 tokens (ceiling 911; headroom 8). The CEILINGS row does not move. The four new lines are 79, 78, 71 and 38 characters, inside the file's existing range (its longest line is 107).

Changeset

.changeset/23768-datasources-default-host-reserved.md, @objectstack/skills patch, carrying Clause-②: no. Re-measured: packages/skills/package.json files[] is dist, and its build (packages/skills/scripts/sync-catalog.mjs) copies skills/** into dist/skills/**. After pnpm --filter @objectstack/skills build under the shared verify lock: ✓ @objectstack/skills: 65 file(s) across 10 skill(s) copied from skills/** into dist/skills and read back byte-identical. — host-reserved is in dist/skills/objectstack-data/rules/datasources.md (1 hit), Most apps need only is not (0 hits), and cmp against the source file is byte-identical.

Verification

Derived at 5dd8c0a8c by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (no paths; change set from the merge base 0b1179f33: 2 files, +14/−5): 41 commands — the dispatch's 29 plus the 12 the changeset adds. Each ran in the foreground with its exit code captured before any pipe (stdout and stderr redirected to a log file first, EXIT=$? read next, no pipe in between), then --ran reconciled the record: ✓ dispatch-gates --ran: 41 derived famil(ies) accounted for — 39 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3).

• 39 run, every one exit 0 — among them check-skills-token-ratchet and its --self-test, check:skill-identifier-liveness (Leg 1: 457 citations over 53 published files), check:skill-compatibility, check:skill-frame-sync, check:pm-skill-id-lint, check:doc-authoring (53 published skill files clean), check:nul-bytes, check:role-word, check-adr-0087-registration --base origin/main (1 non-breaking changeset seen), check-changeset-no-major --base origin/main, check-empty-changeset --base origin/main (1 declaring changeset added; none from the merge base modified), check:published-files, check:pm-changeset-deadline-census, check:objectui-changeset, and check:doc-formula-expressions (after pnpm turbo run build --filter=@objectstack/formula --filter=@objectstack/lint --concurrency=2 under the shared verify lock, together with the skills build: lock held 103 s, waited 0 s).
• 2 NOT MEASURED locally, declared: pnpm check:dual-build-cjs-loads and pnpm check:lean-entry-closure exit 3 (PREREQUISITE NOT MET — both load every package's built dist/, which only a whole-workspace build supplies; not built here for a markdown edit). CI's Lint & Repo Gates builds and runs them; its check-run is the reading.
• Control characters: grep -naP over both changed files finds none.
• No tested behaviour changed, so no ablation. No code, no packages/* source, no generated artifact.

CI runs the full farm; the os-dev-report comment on #23768 cites this PR's check-runs by name and conclusion.

Acceptance notes

• Out-of-scope findings: none filed. The only other catalog reference to this file is skills/objectstack-api/SKILL.md L354 (credentials route to rules/datasources.md), still true; nothing else under skills/ carries the replaced sentence (git grep at 0b1179f33: one hit, L5).
• Governed surface (skills/**), Tier H: this PR stays a draft until an authorized approval; the seat runs the contract review. No label written, as the dispatch order says; the changeset is present, so skip-changeset would not apply anyway.

维护者速读(草稿)

改了什么 — skills/objectstack-data/rules/datasources.md 开头段落。原句写「大多数应用只需要 default 数据源;要读写另一个或外部数据库就再声明几个」;现在改为「default 由宿主保留:宿主从 OS_DATABASE_URL 连接它,stack 里声明一个名为 default 的数据源会被拒绝;只有要读写另一个或外部数据库时,才以自己的名字声明一个数据源」。为了付 token 棘轮,同一文件里删掉两句字段参考(datasource.zod.ts)已经写明且由 schema 自己强制的话:「schemaMode 非 managed 时 external 必填」和「设 autoConnect: true 强制连接」(上面四行的列表第 3 项已经写了)。文件 80 行不变,903/911 token 不变;另加一个 @objectstack/skills 的 patch changeset。

为什么改 — 这份技能包随 npx skills add 发到客户项目,读者是写元数据的 AI。「再声明几个」暗示 default 也是声明出来的;而 #23757 合并后,stack 的 datasources 里出现名为 default 的条目会在 defineStack、os validate、发布和启动四处被拒绝。唯一实测过写出这个形状的生产者就是 AI。新句子陈述的是 spec 与运行时真实持有的规则,没有一句超出 spec 声明。

风险与代价(含回滚) — 纯文本改动,不改任何行为与代码。token 读数 903 → 903(上限 911,余量 8 → 8),上限不动,行数不动。回滚:revert 本 PR 即可,无数据或迁移影响。

席位意见 — (留空)

你要做的 — Tier H 面(skills/**):审阅上面四行英文是否准确,以及两处删句是否可接受;同意则给 APPROVED review,由席位落地。不需要其他动作。

---

Generated by Claude Code

[objectstack-fleet]

维护者速读

改了什么

• 改的是 skills/objectstack-data/rules/datasources.md 开头那段。原句「Most apps need only the default datasource; declare more …」，改为：
  • default 是宿主保留名，宿主从 OS_DATABASE_URL 连接它；
  • 在 stack 里声明名为 default 的数据源会被拒；
  • 只有读写独立或外部数据库时，才以自己的名字声明数据源。
• 另加一个 @objectstack/skills 的 patch changeset。文件行数不变（80 → 80），token 也不变（903 → 903，上限 911 不动）。

为什么改

• 原句「declare more」暗示 default 本身也要声明。PR feat(spec)!: a stack's datasources collection refuses a datasource named default, the host-reserved name #23757 合并后，这样写的 stack 会在 defineStack、os validate 和发布时被拒，启动时也一直被拒。
• 这份技能随 npx skills add 发到客户项目，读者是写元数据的 AI。原句等于教它写出一个必然被拒的配置，而实测唯一写出过这种配置的正是 agent。

风险与代价（含回滚）

• 纯文本，不改任何行为、代码或数据。
• 为付 token，删了两句与字段参考（datasource.zod.ts）重复的话：
  • 「external settings are required when schemaMode !== 'managed'」：schema 自己的 superRefine 会响亮地拒掉缺省，字段说明里也写着；
  • 「Set autoConnect: true to force a live connection」：上方自动连接列表第 3 条已经写了。
• 回滚：revert 本 PR 即可。

席位意见

• 建议批准。席位对着 main 逐句核过：
  • 新句的三个断言（宿主保留、OS_DATABASE_URL、声明即拒）分别有 stack.zod.ts 的 refuseHostReservedDatasourceName、serve.ts 的数据库地址读取和 app-plugin.ts 的启动拒绝作证；
  • 删掉的两句，规则都还在单一出处。
• 隔离的达档契约复核本轮由席位发起，PASS 在案前席位不会落地。你的批准可以先给。

你要做的

• 对 PR docs(skills): the datasources rule states that default is host-reserved, connected from OS_DATABASE_URL, and refused in a stack's datasources (#23768) #23793 给一个 APPROVED review。批准且达档复核 PASS 后，由席位落地（ready、入队），不需要其他动作。

席位核对

Seat domain:skills#2 · session_01VqGhCg9wdsBXPz54uAEWg7 (os-elon-musk) · read 2026-10-16T02:55Z · head 5dd8c0a8cf2886558385b20ca175cccb7efcc8e5 · verdict: ACCEPT (Tier H — stays draft for an authorized approval)

Implemented-by: claude/issue-23768-datasources-default-host-reserved
Reviewed-by: session_01VqGhCg9wdsBXPz54uAEWg7

1. Shape.
   • Draft PR against main. The body's first line is Fixes #23768, followed by Clause-②: no at line start, copied from claim 6206594559. The only closing keyword is that one.
   • The file list is skills/objectstack-data/rules/datasources.md (+5/−5) and .changeset/23768-datasources-default-host-reserved.md (new), the claimed surface. No content/docs/releases/. Merge base 0b1179f33, one commit past the dispatch's read, with the file byte-identical.
2. The text against main, read by the seat.
   • L5–8, the host-reserved sentence. default is host-reserved: refuseHostReservedDatasourceName, a superRefine on the stack's datasources collection (packages/spec/src/stack.zod.ts L548, L599). The host connects it from OS_DATABASE_URL (packages/cli/src/commands/serve.ts, the URL-driven driver selection). A declared default is refused at authoring by the same refinement and at boot by AppPlugin. 「Declare a datasource under its own name only to read/write a separate or external database」 matches the PR feat(spec)!: a stack's datasources collection refuses a datasource named default, the host-reserved name #23757 remedy.
   • Payment 1. 「external settings are required when schemaMode !== 'managed'」 survives at its single source: DatasourceSchema's superRefine (datasource.zod.ts L759–763, 「schemaMode='…' requires 'external' settings」) and the field docblock (L677). The file links that reference at L10. The rule stays loud at authoring.
   • Payment 2. 「Set autoConnect: true to force a live connection」 is item 3 of the auto-connect list two lines above it, so deleting it loses nothing.
   • No untouched line is re-wrapped. Lines 80 → 80; tokens 903 → 903, ceiling 911 unmoved.
3. Gates — check-runs pinned to head 5dd8c0a8c.
   • 38 check-runs: 31 success, 6 skipped and 1 in_progress (Test Core (1/6)).
   • success includes Lint & Repo Gates, TypeScript Type Check, Build Core, Check Changeset, Governed Surface Queue Guard, and every Lint and Type Check lane. Lint · repo & tooling gates reads the two families the dev's union left NOT MEASURED (check:dual-build-cjs-loads, check:lean-entry-closure).
   • The dev's local union at 5dd8c0a8c: 41 derived families, 39 run at exit 0, 2 NOT MEASURED, and --ran reconciled.
   • Ship-proof: the @objectstack/skills build copies skills/** into dist/skills, where the new sentence is present and the old one absent.
   • The pre-landing check re-reads every check-run on the head of the day.
4. Changeset, read by the seat. An @objectstack/skills patch, with Clause-②: no and one sentence per change, each matching the diff. 「No behaviour changes; nothing an author writes changes」 holds: the refusal itself landed with PR feat(spec)!: a stack's datasources collection refuses a datasource named default, the host-reserved name #23757.
5. Out of scope. Findings filed: none. The dev's observation (skills/objectstack-api/SKILL.md L354 routes credentialsRef here) still holds, so no card.
6. Landing (Tier H).
   • In this act: needs-user-decision and needs:contract-review are added, and review is requested from os-zhuang and hotlong. The isolated CONTRACT_REVIEW_TIER reviewer is launched on this head.
   • Landing needs both an authorized APPROVED review and the at-tier PASS. Then this seat runs the pre-landing checks and pr_ready + automerge_enable.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5dd8c0a8cf2886558385b20ca175cccb7efcc8e5
Local-runs: none
Scope: skills/objectstack-data/rules/datasources.md + packages/spec/src/stack.zod.ts, packages/spec/src/data/datasource.zod.ts, packages/spec/src/data/object.zod.ts, packages/runtime/src/app-plugin.ts, packages/runtime/src/default-datasource-plugin.ts, packages/runtime/src/resolve-project-database.ts, packages/runtime/src/standalone-stack.ts, packages/cli/src/commands/serve.ts, scripts/check-skills-token-ratchet.mjs, packages/skills/package.json, packages/skills/scripts/sync-catalog.mjs, skills/objectstack-data/SKILL.md, skills/objectstack-api/SKILL.md, .changeset/23768-datasources-default-host-reserved.md

Read at 2026-10-16T03:06Z: card #23768 (body and all six comments), ruling clause 6189356908 on #23634, PR #23793 (body, file list, net diff against the merge base 0b1179f33, which is the head's parent and on origin/main), and the 48 check-runs on the head. Every code citation below is read at 0b1179f33, byte-identical to the head for every file outside the diff. Nothing built, run or re-run.

① Derived judgments

The diff publishes text only: no schema, no runtime, no generated artifact. No published accept set moves. The one public surface that changes is dist/skills/objectstack-data/rules/datasources.md of @objectstack/skills (files[] is dist; build runs packages/skills/scripts/sync-catalog.mjs, which copies skills/**). Each sentence the hunks add or delete, against main:

1. L4–5 "Objects route to one via their datasource field (default: 'default')" — unchanged, still true: object.zod.ts L2482 datasource: z.string().optional().default('default'). Right.
2. L5 "default is host-reserved" — stack.zod.ts L546 HOST_RESERVED_DATASOURCE_NAME = 'default' with its header (L530–544); app-plugin.ts L1243–1247 (host-owned reserved name); default-datasource-plugin.ts record() registers name: 'default' as the host's own row. Right.
3. L5–6 "the host connects it from OS_DATABASE_URL" — serve.ts L3139 reads process.env.OS_DATABASE_URL, resolveStorageDefinition translates it, L3171 hands it to new DefaultDatasourcePlugin(...); the standalone path does the same through resolveProjectDatabaseUrl (standalone-stack.ts L639, L820), whose priority is explicit URL, then the environment (OS_DATABASE_URL / legacy DATABASE_URL / TURSO_DATABASE_URL), then a datasourceMapping rule { default: true, datasource: NAME } naming a datasource declared under its own name (a rule naming default yields nothing), then the unified default file. The spec's own header reads "from OS_DATABASE_URL or the dev fallback" (L531). The skill names the rung the refusal itself prescribes (L557 "set OS_DATABASE_URL and omit this entry") and the card's Acceptance asks for; it elides the explicit flag, the dev fallback and the mapping-rule rung, and does not say "only". The elision steers no author into a refused or silent shape. Right, as a simplification the 8-token headroom forces; the one sentence a reader could over-read, named here so the maintainer sees it.
4. L6–7 "a stack that declares a datasource named default is refused" — stack.zod.ts L598–599 .superRefine(refuseHostReservedDatasourceName) on STACK_DEFINITION_COLLECTIONS_SHAPE.datasources, so defineStack, os validate and publish refuse it at datasources.N.name (the map form arrives normalized key to name, L534–535; both forms pinned by PR feat(spec)!: a stack's datasources collection refuses a datasource named default, the host-reserved name #23757); app-plugin.ts L1261–1266 throws the same at boot in every posture. Both compare name === 'default' exactly; every other spelling is refused by DatasourceSchema.name's pattern. Right.
5. L7–8 "Declare a datasource under its own name only to read/write a separate or external database" — the refusal's remedy, spec (L557–559 "declare it under another name (e.g. 'app_primary') and route objects to it explicitly") and runtime (L1264–1265). "Only" holds for the catalog: the host-provisioned telemetry datasource is serve.ts's, never a stack's. Right.
6. Deletion of old L18 "external settings are required when schemaMode !== 'managed'" — datasource.zod.ts L759–764 refuses the omission at parse (schemaMode='X' requires 'external' settings.), the field's TSDoc L677 says it, and the file's L10 points at that reference. A rule stays enforced at authoring; the skill loses a forewarning, not a rule. Lossless. This is the one real reader-side trade of the payment: an author who omits the block learns it from one parse refusal that carries the remedy.
7. Deletion of old L58's second sentence "Set autoConnect: true to force a live connection." — item 3 of the auto-connect list four lines above (L54) names the same trigger, and the field's describe() (L666) is the same statement. Lossless.
8. Vocabulary and gates — "stack" is the catalog's word (defineStack in objectstack-data/SKILL.md L400, L425, data-hooks.md), "host" is objectstack-platform's. The published text carries no tracker number (check:doc-authoring green). Right.
9. Whole-package read — objectstack-data/SKILL.md L47 (index row) and L87 (datasource default 'default') stay true; objectstack-api/SKILL.md L353–354 routes defineDatasource, schemaMode, the external write gate and credentialsRef here, and all four are still in the file (L12–18, L46–58, L68–74, L76–80). git grep at the head: no other skills/** line names the default datasource, so no other line invites declaring it. Right.
10. Token ratchet — scripts/check-skills-token-ratchet.mjs is not in the diff; its CEILINGS row ['skills/objectstack-data/rules/datasources.md', 911] is unmoved. Readings re-measured on the two trees: 80 lines / 3609 bytes before, 80 / 3612 after; the hunks are +2 at L5–8, −2 at old L17–18, 0 at old L58; L3–4 and L57 are byte-identical, so no re-wrap bought room. The 903-token reading is Lint · repo & tooling gates (success). No control characters in either changed file. Right.
11. Value density from the reader's seat — the opening paragraph now states the one rule an author must not break, and its remedy, where the old sentence invited breaking it; the two deletions remove a restatement of a parse refusal and a restatement of a list item. Net value up at the same 80 lines and the same token count. Right.

② Semver level

.changeset/23768-datasources-default-host-reserved.md: '@objectstack/skills': patch, Clause-②: no. Right. The package ships skills/** through dist, and a text correction that changes no key and no behaviour is a patch — the same shape as .changeset/23615-grant-unique-index-skill.md and .changeset/23268-skills-lint-rules-row.md on main. Clause-②: no stands on the PR body's line 2 and in the changeset: no published accept set narrows or widens in this diff; the narrowing the text describes landed with PR #23757 under its own changeset. skip-changeset does not apply. Check Changeset success on all three runs; the title's (#23768) suffix follows 128 changesets on main.

③ Boundary flags

• open_questions: [] — none owed.
• Deviation (1), base drift 0a168a33e to 0b1179f33: git diff --stat between the two over skills/ and the ratchet script is empty; 0b1179f33 is on origin/main and is the head's parent. Holds.
• Deviation (2), sync-catalog.mjs path: packages/skills/scripts/sync-catalog.mjs exists and is what build calls. Holds.
• Deviation (3), check:dual-build-cjs-loads and check:lean-entry-closure NOT MEASURED locally: the CI reading stands, with the attribution corrected. Both steps live in ci.yml's Build Core job (L2643, L2667); lint.yml L5793–5796 records that Lint & Repo Gates never builds and Build Core hosts them for that reason. Build Core concluded success on the head. The PR body ("CI's Lint & Repo Gates builds and runs them") and the ACCEPT ("Lint · repo & tooling gates reads the two families") name the wrong job; the Verification section is not published text, so no republish is owed. For the seat's pre-landing read: cite Build Core.
• Deviation (4), no test:repo and no ablation: no test file and no package source is touched. Holds.
• Deviation (5), worktree removed after the PR opened: procedural, no bearing on the head.
• Out-of-scope observation (skills/objectstack-api/SKILL.md L354 routes credentialsRef here): verified at the head, still true; no card owed.
• Check-runs on 5dd8c0a8c, all 48 completed at the read: 36 success (every Lint, Type Check, Build Core, Test Core 1–6 and the aggregate, Check Changeset ×3, Governed Surface Queue Guard ×2, Dogfood Regression Gate, Check Documentation Links, the four claim and closing-keyword guards, Auto Label, Check PR Size, filter), 12 skipped (opt-in tarball smoke ×3, the label-triggered duplicate Auto Label and Check PR Size runs ×4, Dogfood shards, Build Docs, Console Pin Gate, Dogfood Verify CLI, Temporal Conformance), 0 failure, 0 in progress.
• Escalations: none. Tier H: the PR stays a draft until an authorized APPROVED review; this record is the at-tier PASS the seat lands it beside.

Implemented-by: claude/issue-23768-datasources-default-host-reserved
Reviewed-by: session_01VqGhCg9wdsBXPz54uAEWg7

VERDICT: PASS

---

Generated by Claude Code