From 5dd8c0a8cf2886558385b20ca175cccb7efcc8e5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 02:34:09 +0000 Subject: [PATCH] docs(skills): the datasources rule states default is host-reserved, connected from OS_DATABASE_URL, and refused in a stack's datasources MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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" — an invitation to the shape the stack's `datasources` collection refuses (`defineStack`, `os validate`, publish) and AppPlugin refuses at boot. The sentence now states the rule the spec and runtime hold: `default` is host-reserved, the host connects it from `OS_DATABASE_URL`, a stack that declares a datasource named `default` is refused, and a datasource is declared under its own name only for a separate or external database. Token ratchet paid inside the file by deleting two restatements of the field reference: "`external` settings are required when `schemaMode !== 'managed'`" (the schema's own superRefine refuses the omission) and "Set `autoConnect: true` to force a live connection" (item 3 of the auto-connect list above it). 903/911 tokens before and after; 80 lines before and after. Changeset: @objectstack/skills patch — skills/** ships through packages/skills dist via sync-catalog. Claude-Session: https://claude.ai/code/session_01VqGhCg9wdsBXPz54uAEWg7 Co-authored-by: Claude --- .changeset/23768-datasources-default-host-reserved.md | 9 +++++++++ skills/objectstack-data/rules/datasources.md | 10 +++++----- 2 files changed, 14 insertions(+), 5 deletions(-) create mode 100644 .changeset/23768-datasources-default-host-reserved.md diff --git a/.changeset/23768-datasources-default-host-reserved.md b/.changeset/23768-datasources-default-host-reserved.md new file mode 100644 index 00000000000..249058a77d2 --- /dev/null +++ b/.changeset/23768-datasources-default-host-reserved.md @@ -0,0 +1,9 @@ +--- +'@objectstack/skills': patch +--- + +docs(skills): the `objectstack-data` datasources rule states that `default` is host-reserved — the host connects it from `OS_DATABASE_URL`, and a stack that declares a datasource named `default` is refused (#23768) + +Clause-②: no + +`skills/objectstack-data/rules/datasources.md`'s opening paragraph read "Most apps need only the `default` datasource; declare more to read/write a separate or external database." "Declare more" implied that `default` is declared too, and a stack whose `datasources` collection carries an entry named `default` is refused at `defineStack`, `os validate`, publish and boot: the host declares and connects `default` itself. The sentence is replaced by the rule the spec and runtime hold: `default` is host-reserved, the host connects it from `OS_DATABASE_URL`, a stack that declares a datasource named `default` is refused, and a datasource is declared under its own name only to read/write a separate or external database. The added words are paid for inside the same file by deleting two restatements of the field reference: "`external` settings are required when `schemaMode !== 'managed'`" (the schema refuses the omission itself) and "Set `autoConnect: true` to force a live connection" (the auto-connect list two lines above already names it). No behaviour changes; nothing an author writes changes. diff --git a/skills/objectstack-data/rules/datasources.md b/skills/objectstack-data/rules/datasources.md index 4e8310862bc..f39634a1381 100644 --- a/skills/objectstack-data/rules/datasources.md +++ b/skills/objectstack-data/rules/datasources.md @@ -2,8 +2,10 @@ A **datasource** (`defineDatasource`, a `*.datasource.ts` metadata file) is a connection to a data store. Objects route to one via their `datasource` field -(default: `'default'`). Most apps need only the `default` datasource; declare more -to read/write a **separate** or **external** database. +(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. Full field reference: `node_modules/@objectstack/spec/src/data/datasource.zod.ts`. @@ -15,8 +17,6 @@ Full field reference: `node_modules/@objectstack/spec/src/data/datasource.zod.ts | `external` | A mature external DB ObjectStack does **not** own; DDL forbidden; boot mismatch **fails**. | | `validate-only` | Like `external`, but a mismatch **warns** instead of failing boot. | -`external` settings are **required** when `schemaMode !== 'managed'`. - ## Federated (external) objects An object on an external datasource binds to its remote table via `external`: @@ -55,7 +55,7 @@ objects' read metadata registered **automatically at boot** — no `onEnable` / 4. a **`datasourceMapping` rule routes at least one object to it**. A `managed` datasource that nothing routes to stays **metadata-only** — visible but -not connected. Set `autoConnect: true` to force a live connection. +not connected. ⚠️ A `datasourceMapping` rule is **routing, not a hint**. A rule pointing at a datasource that cannot be connected fails the boot, and a query against a mapped