|
5 | 5 | **Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (package as first-class citizen), [ADR-0005](./0005-metadata-customization-overlay.md) (artifact vs runtime overlay precedence), [ADR-0008](./0008-metadata-repository-and-change-log.md) (metadata repository, `MetaRef` identity), [ADR-0010](./0010-metadata-protection-model.md) (package provenance / `_packageId` stamping) |
6 | 6 | **Consumers**: `@objectstack/objectql` (`SchemaRegistry.registerItem`, `ObjectQL.registerApp`, install path), `@objectstack/console` / `objectui` (routing + metadata resolution), package authors, CLI/CI install path, the app marketplace registry. |
7 | 7 | **Surfaced by**: ADR-0046 review (doc naming) → generalised to all bare-named metadata → re-examined through the app-marketplace install lens. |
8 | | -**Addenda**: [2026-08-08 — publish-time / marketplace namespace exclusivity](#addendum-2026-08-08-publish-time--marketplace-namespace-exclusivity) (**Accepted** 2026-08-08 — maintainer ruling on #1825, [acceptance comment 5226411687](https://github.com/objectstack-ai/objectstack/issues/1825#issuecomment-5226411687), landed by PR #6671; additive to §3.2, supersedes nothing); [2026-11-06 — bare names resolved without a package hold one package](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed) (**Accepted**, ruling C on #30798, phase 1; narrows §3.4 for picklists, mappings, datasets, APIs, object-less actions, engine functions, flows, webhooks, connectors, email templates, agents and skills — phase 1 complete — supersedes nothing). |
| 8 | +**Addenda**: [2026-08-08 — publish-time / marketplace namespace exclusivity](#addendum-2026-08-08-publish-time--marketplace-namespace-exclusivity) (**Accepted** 2026-08-08 — maintainer ruling on #1825, [acceptance comment 5226411687](https://github.com/objectstack-ai/objectstack/issues/1825#issuecomment-5226411687), landed by PR #6671; additive to §3.2, supersedes nothing); [2026-11-06 — bare names resolved without a package hold one package](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed) (**Accepted**, ruling C on #30798, phase 1; narrows §3.4 for picklists, mappings, datasets, APIs, object-less actions, engine functions, flows, webhooks, connectors, email templates, agents and skills — phase 1 complete — and, by its dated note P1.10 (2026-11-08), tools; supersedes nothing). |
9 | 9 |
|
10 | 10 | --- |
11 | 11 |
|
@@ -268,26 +268,26 @@ package — stays covered by the `naming/namespace-prefix` lint in `os lint`. |
268 | 268 |
|
269 | 269 | > **Narrowed (2026-11-06) — picklists, mappings, datasets, APIs, object-less |
270 | 270 | > actions, engine functions, flows, webhooks, connectors, email templates, agents |
271 | | -> and skills are out of §3.4.** Their consumers resolve the name with no package — a field's |
| 271 | +> and skills are out of §3.4, and tools since 2026-11-08 (P1.10).** Their consumers resolve the name with no package — a field's |
272 | 272 | > `picklist`, an import's `mappingName`, a dashboard's `datasetName`, the |
273 | 273 | > endpoint matcher's one API per name, `/actions/global/NAME`, a flow `script` |
274 | 274 | > node's function, the automation engine's one armed flow per name, the |
275 | 275 | > dispatcher's one declared webhook per name, the connector picker's one |
276 | 276 | > connector per name, a send's `template`, `/meta/agent/NAME`, an MCP client's |
277 | | -> skill prompt — so with two holders every caller is |
| 277 | +> skill prompt, `/meta/tool/NAME` and a skill's `tools` — so with two holders every caller is |
278 | 278 | > served one of them, chosen by registration order, measured on a booted |
279 | 279 | > two-package deployment (#30803). Once the cold boot has sealed the registry, a |
280 | 280 | > package whose picklist, mapping, dataset, API, object-less action, flow, |
281 | | -> webhook, connector, email template, agent or skill bears a name another |
| 281 | +> webhook, connector, email template, agent, skill or tool bears a name another |
282 | 282 | > installed package holds is refused at managed install and at package registration (a built-in's |
283 | 283 | > name, at managed install), and a package whose handlers bring a function |
284 | 284 | > another package holds is refused at the hook binder's bind, each naming both |
285 | 285 | > holders and the rename. ⛔ The environment catalog is never a holder: an |
286 | 286 | > environment item under a package's name is the ADR-0005 overlay. ⛔ Nor is the |
287 | 287 | > email service's built-in template bundle: an app's same-named template |
288 | 288 | > overrides it by contract (ADR-0131 D6), so that package holds no template name |
289 | | -> and is refused none. Every other type keeps §3.4 as written, among them a |
290 | | -> `tool` and an action bound to an object. See |
| 289 | +> and is refused none. Every other type keeps §3.4 as written, among them an |
| 290 | +> action bound to an object. See |
291 | 291 | > [Addendum (2026-11-06)](#addendum-2026-11-06-bare-names-resolved-without-a-package-hold-one-package--34-narrowed). |
292 | 292 |
|
293 | 293 | ### 3.5 Namespace rename-on-install is deferred (non-goal) |
@@ -1069,7 +1069,8 @@ first, as the maintainer ordered on 2026-11-06 (all of them kept in #30803): the |
1069 | 1069 | data family (P1.1), the request family (P1.7), the flow family (P1.8) and, last, |
1070 | 1070 | the AI family — `agent` and `skill` (P1.9). P1.9's change closes phase 1. `tool` |
1071 | 1071 | and `rag_pipeline` were never in the ruling's list; P1.9 records what was |
1072 | | -measured of them. |
| 1072 | +measured of them. `tool` joined afterwards, on its own card and measurement |
| 1073 | +(P1.10, 2026-11-08); `rag_pipeline` stays out. |
1073 | 1074 |
|
1074 | 1075 | ### P1.6 Where it is implemented |
1075 | 1076 |
|
@@ -1203,13 +1204,51 @@ holders, the same envelope and rename. Neither is bundled, and neither has an |
1203 | 1204 | overridable baseline or a built-in name. An agent and a skill are two types: one |
1204 | 1205 | package's agent and another's skill under one name never meet. |
1205 | 1206 |
|
1206 | | -**Not in the list.** A `tool` is not covered — the ruling's types do not name it. |
1207 | | -Measured beside them: `/meta/tool/NAME` serves the first-registered package's |
1208 | | -tool as well; the readers that resolve a tool by name are the cloud's. A |
| 1207 | +**Not in the list.** A `tool` is not covered by this change — the ruling's types |
| 1208 | +do not name it. Measured beside them: `/meta/tool/NAME` serves the |
| 1209 | +first-registered package's tool as well. (It joined the list later, on its own |
| 1210 | +card and measurement: P1.10.) A |
1209 | 1211 | `rag_pipeline` cannot be declared through `defineStack` (the stack schema |
1210 | | -refuses `ragPipelines`) and registered nothing in the measurement. Both are left |
1211 | | -as §3.4 has them. |
| 1212 | +refuses `ragPipelines`) and registered nothing in the measurement. `rag_pipeline` is left |
| 1213 | +as §3.4 has it. |
1212 | 1214 |
|
1213 | 1215 | **The cold boot** reads the two with the registry's other holders, under P1.3's |
1214 | 1216 | switch (`'warn'`). This is the series' closing change: phase 1's list is |
1215 | 1217 | complete, and phase 2 (#30804, #30805) and phase 3 (#30806) follow. |
| 1218 | + |
| 1219 | +### P1.10 (2026-11-08) `tool` joins the list, after the AI family |
| 1220 | + |
| 1221 | +A dated note under this addendum; it narrows §3.4 for one more type. The |
| 1222 | +header's Addenda entry, §3.4's 2026-11-06 note, P1.5 and P1.9's "Not in the |
| 1223 | +list" name it beside the earlier types. The maintainer accepted a separate card for `tool` out of P1.9's |
| 1224 | +measurement (「以上都同意」, 2026-11-08, #31414): measure the readers that resolve a |
| 1225 | +tool by name, and if any carries no package, `tool` joins P1.2's list the way |
| 1226 | +the AI family did. |
| 1227 | + |
| 1228 | +**Measured** on objectstack `69244406`, beside P1.9's booted measurement: |
| 1229 | + |
| 1230 | +- `/meta/tool/NAME` serves the FIRST-registered package's tool, silently, in |
| 1231 | + either registration order (P1.9), and a third package installed after the boot |
| 1232 | + under that name installs (`200`) and is shadowed. |
| 1233 | +- Every reference to a tool carries its bare name and nothing else. A skill's |
| 1234 | + `tools` list admits only a snake_case name (the spec's `SkillSchema`, bound by |
| 1235 | + the cloud agent runtime); an AI tool definition and a tool call carry a name |
| 1236 | + and no package (`AIToolDefinition`, `ToolCallPart` in the AI service |
| 1237 | + contract); the MCP bridge registers each tool under its name and calls it by |
| 1238 | + that name, and an MCP server holds one tool per name (a second registration of |
| 1239 | + a name throws). An agent's guardrail matches a tool by its name. |
| 1240 | +- The cloud agent runtime (read by the cloud seat at objectstack-ai/cloud |
| 1241 | + `ba6f0fa`, #31414) resolves a tool by bare name too, for chat (a skill's |
| 1242 | + `tools`) and MCP alike, against an in-process tool registry keyed by the name |
| 1243 | + that plugins fill in code; the metadata `tool` item is a mirror for Studio and |
| 1244 | + reaches no handler there. So no reader on either side carries a package, and |
| 1245 | + one such reader is enough. |
| 1246 | + |
| 1247 | +**What is refused.** `tool` joins P1.2's list, last: the same two doors, the |
| 1248 | +same holders, the same envelope and rename. It is not bundled, and it has no |
| 1249 | +overridable baseline and no built-in name. An agent, a skill and a tool are |
| 1250 | +three types: one package's item of one and another package's item of another |
| 1251 | +under one name never meet. |
| 1252 | + |
| 1253 | +**The cold boot** reads it with the registry's other holders, under P1.3's |
| 1254 | +switch (`'warn'`). `rag_pipeline` stays as P1.9 left it. |
0 commit comments