@@ -0,0 +1,49 @@
+---
+'@objectstack/spec': minor
+'@objectstack/metadata': patch
+---
+
+feat(spec)!: `defineStack` refuses two entries of one named collection under one identity, naming the collection, the identity and every index — for 27 collections (#22934)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered stack-collection-duplicate-entry-refused -->
+
+**BREAKING**: an accept-set narrowing on a published authoring surface, shipped as `minor` under the launch-window convention for breaking changes.
+
+The runtime registers the entries of these collections under one identity each, and a stack could author two entries under one identity with nothing refusing it: `defineStack` and `objectstack validate` accepted the pair (exit 0, `valid: true`, no finding naming it). Measured on a source boot (`objectstack serve`, no build) and on `objectstack build` followed by an artifact-backed boot:
+
+- `objects`, `pages`, `dashboards`, `reports`, `datasets`, `flows`, `jobs`, `emailTemplates`, `books`, `positions`, `permissions`, `capabilities`, `sharingRules`, `webhooks`, `mappings`, `analyticsCubes`, `connectors`, `picklists`, `tools`, `skills`, `views`, `apis`, `apps` and `objectExtensions` kept only the LAST entry on both paths, with no notice at the default log level (for `apis`, the first entry's path answered 404);
+- `datasources`: the metadata described the last entry while the driver connected with the first one's configuration;
+- `hooks`: the metadata listed one hook while both handlers were bound and ran;
+- `docs`: `objectstack validate` and `objectstack build` refused the pair (`docs/duplicate-name`), while a source boot kept the last.
+
+**What is refused.** `defineStack`'s cross-reference pass refuses the stack with its existing envelope (`STACK_CROSS_REFERENCE_INVALID`, status 422, `defineStack cross-reference validation failed (N issues):`), one finding per collision, naming the collection, the identity and every index:
+
+```text
+✗ Datasource 'crm_external' is declared twice in `datasources`: stack.datasources[0] and stack.datasources[1]. …
+```
+
+The identity is what the runtime keys an entry by: its `name`; the `(name, locale)` pair for `emailTemplates` (one name across several locales is an i18n bundle, and an entry with no `locale` counts as `en-US`); the extended object (`extend`) for `objectExtensions`; and for `views` the object a container binds to (`object`, else `list.data.object`, else `form.data.object`, else its `name`). The check runs in an object-less stack too, and every entry counts, byte-identical twins included. `objectstack validate`, `objectstack build` and a source boot all load the config through `defineStack`, so all three refuse it at load. Like every cross-reference check it is skipped under `defineStack(…, { strict: false })`. On an `app` package, two apps under one name now get this refusal, which runs before the single-app count.
+
+**Unchanged.** Distinct identities; an email-template i18n bundle (one name, one entry per locale); the map form under distinct keys (two keys whose entries spell one explicit `name` are one identity, and are refused); the same name reused by another package of a multi-package project (`composeStacks(…, { manifest: 'preserve' })` keeps each package's collections in its own `packages[i]` body, which this check does not read); `plugins` (last-one-wins with a warning is the kernel's declared contract), `agents` (withdrawn for app packages) and `picklistExtensions` (merged by option value); and the existing `actions` and `functions` refusals.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `pages: [{ name: 'home', … }, { name: 'home', … }]` (any of the 24 name-keyed collections) | one entry per name: rename one (`home_admin`) and every reference that meant it, or merge the two into one entry |
+| `emailTemplates: [{ name: 'acme.welcome', … }, { name: 'acme.welcome', locale: 'en-US', … }]` | one entry per name and locale: give the second its own `locale` (`zh-CN`), or merge the two |
+| `datasources: [{ name: 'ext', config: a }, { name: 'ext', config: b }]` | one datasource per name — the driver used to connect `a` while the metadata described `b` |
+| `hooks: [{ name: 'audit', object: 'a', … }, { name: 'audit', object: 'b', … }]` | one hook with `object: ['a', 'b']`, or two hooks with two names |
+| `apis: [{ name: 'feed', path: '/api/v1/apps/x/a' }, { name: 'feed', path: '/api/v1/apps/x/b' }]` | give each endpoint its own name |
+| `views: [defineView({ object: 'task', list }), defineView({ object: 'task', form })]` | one container per object: `defineView({ object: 'task', list, form })` (named views go in `listViews` / `formViews`) |
+| `objectExtensions: [{ extend: 'task', fields: { a } }, { extend: 'task', fields: { b } }]` | one extension per target: `{ extend: 'task', fields: { a, b } }` |
+
+**The one-line fix: give each entry of a collection its own identity, or merge the duplicates into one entry.**
+
+No D2 conversion rewrites it: which entry keeps the identity, and what the other one becomes, is the author's call. Its D3 record is the semantic entry `stack-collection-duplicate-entry-refused` (protocol 18).
+
+**`@objectstack/metadata`.** `deriveViewContainerObject` — the "which object does a `views` container bind to" derivation the registrars file containers by — moved into `@objectstack/spec` (exported from its root and `./ui`), because the stack contract now judges the same slot. `@objectstack/metadata` re-exports that one declaration under the same name, from its root and from `@objectstack/metadata/view-container`; behaviour is unchanged. That subpath used to import nothing and now loads the `@objectstack/spec` root entry, which every in-repo importer of it already loads.
+
+**Who is affected, measured.** The four example apps (`examples/app-crm`, `app-todo`, `app-showcase`, `app-multi-package`) carry no duplicate under these identities. Deployed metadata and other repositories were not measured.
@@ -173,6 +173,7 @@
     "defineView": "src/ui/view.zod.ts#defineView (function)",
     "defineViewItem": "src/ui/view.zod.ts#defineViewItem (function)",
     "defineWebhook": "src/automation/webhook.zod.ts#defineWebhook (function)",
+    "deriveViewContainerObject": "src/ui/view-container-object.ts#deriveViewContainerObject (function)",
     "expandViewContainer": "src/ui/view.zod.ts#expandViewContainer (function)",
     "expandViewContainerWithDiagnostics": "src/ui/view.zod.ts#expandViewContainerWithDiagnostics (function)",
     "expression": "src/shared/expression.zod.ts#expression (function)",
 
@@ -496,6 +496,7 @@
     "defineView": "src/ui/view.zod.ts#defineView (function)",
     "defineViewItem": "src/ui/view.zod.ts#defineViewItem (function)",
     "deriveColumnSummary": "src/ui/view-grouping-query.ts#deriveColumnSummary (function)",
+    "deriveViewContainerObject": "src/ui/view-container-object.ts#deriveViewContainerObject (function)",
     "diagnoseViewMetadata": "src/ui/view.zod.ts#diagnoseViewMetadata (function)",
     "expandViewContainer": "src/ui/view.zod.ts#expandViewContainer (function)",
     "expandViewContainerWithDiagnostics": "src/ui/view.zod.ts#expandViewContainerWithDiagnostics (function)",
 
@@ -0,0 +1,49 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SemanticMigration } from '../../types.js';
+
+// #22934. An accept-set narrowing of the stack aggregate: two entries of one
+// of 27 named collections that the runtime registers under one identity are
+// refused by the cross-reference pass — the batch sibling of the duplicate
+// action-key refusal and of the `functions` array's duplicate-name refusal. No
+// D2 conversion: which entry keeps the identity, and what the other one
+// becomes, is the author's call.
+export const entry: SemanticMigration = {
+  id: 'stack-collection-duplicate-entry-refused',
+  // No backticks in `surface` — build-upgrade-guide renders it inside a code
+  // span already, and a nested backtick would close it.
+  surface:
+    'stack.objects, datasources, pages, dashboards, reports, datasets, flows, jobs, emailTemplates, books, '
+    + 'positions, permissions, capabilities, sharingRules, webhooks, hooks, mappings, analyticsCubes, '
+    + 'connectors, picklists, docs, tools, skills, views, apis, apps and objectExtensions — two or more '
+    + "entries of one collection under one identity, e.g. pages: [{ name: 'home', ... }, { name: 'home', ... }]",
+  replacement:
+    'One entry per identity in each collection. The identity is the entry name, the name and locale '
+    + 'for emailTemplates (one name across several locales is an i18n bundle; an entry with no locale '
+    + 'counts as en-US), the extended object (extend) for objectExtensions, and for views the object a '
+    + 'container binds to (object, else '
+    + 'list.data.object, else form.data.object, else its name). Rename one of the colliding entries (and '
+    + 'every reference that meant it), or merge them into a single entry: one container per object for '
+    + 'views, one extension per target object for objectExtensions, and a name of its own for each apis '
+    + 'endpoint. Distinct identities, an email-template i18n bundle, the map form under distinct keys, '
+    + 'and the same name reused by another package are unchanged.',
+  reason:
+    'The runtime registers each of these collections under one identity per entry, and a stack could '
+    + 'author two entries under one identity with nothing refusing it: defineStack and objectstack '
+    + 'validate accepted the pair (exit 0, valid true), and the boot then lost or split it silently. '
+    + 'Measured on a source boot and on objectstack build followed by an artifact-backed boot: 23 '
+    + 'collections and objectExtensions kept only the LAST entry on both paths, with no notice at the '
+    + 'default log level; for datasources the metadata described the last entry while the driver '
+    + 'connected with the first one\'s configuration; for hooks the metadata listed one hook while both '
+    + 'handlers were bound and ran; and for docs objectstack validate and objectstack build refused the '
+    + 'pair while a source boot kept the last. The stack aggregate now refuses the pair, in the same '
+    + 'cross-reference envelope as a duplicate action key, with one finding per collision naming the '
+    + 'collection, the identity and every index. Not convertible: which entry keeps the identity is a '
+    + 'fact only the author holds.',
+  acceptanceCriteria:
+    'os validate and os build load the stack without a STACK_CROSS_REFERENCE_INVALID finding of the form '
+    + '"X is declared twice in KEY: stack.KEY[i] and stack.KEY[j]". After renaming or merging, check that '
+    + 'what the runtime now serves is the entry you meant: the boot used to keep the last entry (and, for '
+    + 'datasources, connect the first), so the behaviour you observed may have come from a different entry '
+    + 'than the one you keep.',
+};
@@ -16,9 +16,10 @@
  * docs                                    : os validate / os build refuse (docs/duplicate-name), a source boot keeps the last
  * ```
  *
- * The identity is what the registrars key an entry by: `name` (25 keys),
- * `extend` (`objectExtensions`), and for `views` the object an aggregated
- * container binds to (`deriveViewContainerObject`). Out of the table, each
+ * The identity is what the registrars key an entry by: `name` (24 keys),
+ * `(name, locale)` (`emailTemplates`, whose i18n bundle is one name across
+ * several locales), `extend` (`objectExtensions`), and for `views` the object
+ * an aggregated container binds to (`deriveViewContainerObject`). Out of the table, each
  * for its own reason: `plugins`, `agents`, `picklistExtensions`, and `actions`
  * / `functions`, which have their own checks (`stack-duplicate-action-key`,
  * `stack-duplicate-function-name`).
@@ -119,7 +120,14 @@ const BATCH: readonly Row[] = [
   byName('datasets', 'Dataset', dataset),
   byName('flows', 'Flow', flow),
   byName('jobs', 'Job', { name: 'dupe_job', label: 'Job', schedule: { type: 'interval', intervalMs: 60000 }, body: { language: 'js', source: 'return 1;', capabilities: [] } }),
-  byName('emailTemplates', 'Email template', { name: 'dupe_mail', label: 'Mail', subject: 'Hi', bodyHtml: '<p>Hello</p>' }),
+  {
+    // An i18n bundle is one name across several locales: the identity is the
+    // pair, an untagged entry keyed as the floor tag `en-US`.
+    ...byName('emailTemplates', 'Email template', { name: 'dupe_mail', label: 'Mail', subject: 'Hi', bodyHtml: '<p>Hello</p>' }),
+    identity: 'dupe_mail',
+    sameIdentity: (e) => ({ ...e, label: 'Second', locale: 'en-US' }),
+    subject: "Email template 'dupe_mail' for locale 'en-US'",
+  },
   byName('books', 'Book', { name: 'dupe_book', label: 'Book', groups: [] }),
   byName('positions', 'Position', { name: 'dupe_pos', label: 'Pos' }),
   byName('permissions', 'Permission set', { name: 'dupe_perm', label: 'Perm', objects: {} }),
@@ -372,6 +380,20 @@ describe('defineStack - CONTROL: distinct identities and the out-of-batch collec
     },
   );
 
+  it('emailTemplates: one name across several locales is an i18n bundle, not a duplicate', () => {
+    const mail = (locale?: string) => ({
+      name: 'dupe_mail',
+      label: `Mail ${locale ?? 'floor'}`,
+      ...(locale === undefined ? {} : { locale }),
+      subject: 'Hi',
+      bodyHtml: '<p>Hello</p>',
+    });
+    expect(refusal({ manifest, objects: [thing], emailTemplates: [mail(), mail('zh-CN'), mail('ja-JP')] })).toBeNull();
+    const r = refusal({ manifest, objects: [thing], emailTemplates: [mail(), mail('zh-CN'), mail('zh-CN')] });
+    expectCrossReferenceEnvelope(r, 1);
+    findingFor(r, 'emailTemplates', "Email template 'dupe_mail' for locale 'zh-CN'", [1, 2]);
+  });
+
   it('the cross-scope action pair — one global, one object-bound, one name — stays accepted', () => {
     const act = { name: 'dupe_go', label: 'Go', type: 'script' as const, target: 'noop' };
     expect(refusal({ manifest, objects: [thing], actions: [act, { ...act, objectName: 'dupe_thing' }] })).toBeNull();
 
@@ -2306,11 +2306,13 @@ function collectDuplicateFunctionNameErrors(config: ObjectStackDefinition): stri
  * - `docs`: `os validate` and `os build` refused the pair (`docs/duplicate-name`)
  *   while a source boot kept the last.
  *
- * The identity is the string the registrars key an entry by: `name` for 25
- * collections, the extended object (`extend`) for `objectExtensions`, and for
- * `views` the slot every registrar files the entry under — an aggregated
- * container under the object it binds to ({@link deriveViewContainerObject}),
- * any other entry under its own `name`, falling back to the same derivation.
+ * The identity is the string the registrars key an entry by: `name` for 24
+ * collections, the `(name, locale)` pair for `emailTemplates` (an i18n bundle
+ * is one name across several locales), the extended object (`extend`) for
+ * `objectExtensions`, and for `views` the slot every registrar files the entry
+ * under — an aggregated container under the object it binds to
+ * ({@link deriveViewContainerObject}), any other entry under its own `name`,
+ * falling back to the same derivation.
  * An entry with no readable identity claims no slot and is not counted.
  *
  * Deliberately NOT in the table, each for a reason that is not "nobody looked":
@@ -2325,8 +2327,11 @@ function collectDuplicateFunctionNameErrors(config: ObjectStackDefinition): stri
  * map-supported collection reaches this check already normalized (key → `name`,
  * an explicit `name` winning), so two map keys whose entries spell one `name`
  * collide here too. Cross-package reuse of a name is untouched (ADR-0048 §3.4):
- * a composed project carries each package's collections in its own
- * `packages[i]` body, never at the top level this check reads.
+ * a multi-package project (`composeStacks(…, { manifest: 'preserve' })`)
+ * carries each package's collections in its own `packages[i]` body, which this
+ * check does not read. The same-package case is the one §3.4 leaves to
+ * authoring-time hygiene (`os lint`'s duplicate-name advisory); it is refused
+ * here at the contract, as the action-key check already does for actions.
  */
 interface SameStackEntryIdentity {
   /** The identity the registrars key this collection's entries by, or `undefined` when an entry has none. */
@@ -2376,7 +2381,29 @@ const SAME_STACK_ENTRY_IDENTITY = Object.freeze({
   datasets: lastWinsByName('Dataset', 'datasets'),
   flows: lastWinsByName('Flow', 'flows'),
   jobs: lastWinsByName('Job', 'jobs'),
-  emailTemplates: lastWinsByName('Email template', 'email templates'),
+  // An i18n bundle is one `name` across several `locale` tags, so the identity
+  // is the pair — the registry's `ITEM_KEY_DISCRIMINATORS` entry, keyed as
+  // `name@locale` with an untagged entry keyed as the floor tag (the schema's
+  // own default). Two entries collide only on one name AND one locale.
+  emailTemplates: {
+    identity: (entry) => {
+      const name = readEntryName(entry);
+      if (name === undefined) return undefined;
+      const locale = (entry as { locale?: unknown }).locale;
+      const tag = typeof locale === 'string' && locale.trim() ? locale.trim() : EMAIL_TEMPLATE_FLOOR_LOCALE;
+      return `${name}@${tag}`;
+    },
+    subject: (key) => {
+      const at = key.lastIndexOf('@');
+      return `Email template '${key.slice(0, at)}' for locale '${key.slice(at + 1)}'`;
+    },
+    consequence: () =>
+      'The runtime keys email templates by name and locale, so only the last of these entries is kept ' +
+      'for that locale and the others are silently dropped.',
+    remedy: () =>
+      'Rename one of them, give each its own `locale` (one entry per locale is an i18n bundle), or merge ' +
+      'them into a single entry.',
+  },
   books: lastWinsByName('Book', 'books'),
   positions: lastWinsByName('Position', 'positions'),
   permissions: lastWinsByName('Permission set', 'permission sets'),