@elytracms/studio 0.0.80 → 0.0.82

package/dist/lib/webhooks/tags.js

@@ -16,23 +16,41 @@
  *
  * ## Which events produce which tags
  *
- * - **Document publish/unpublish/delete/save** (`documents.publish`,
- *   `documents.unpublish`, `documents.pinVersion`, `documents.upsert`,
- *   `documents.delete`): the document's own
+ * The gate is **"can this operation change PUBLISHED output?"** — not "did this
+ * operation touch a document" (EC-501). Live delivery is published-only, so an
+ * operation that cannot move published state has no cache entry to drop and
+ * every tag it emits is waste by construction.
+ *
+ * - **Document publish/unpublish/pin/delete** (`documents.publish`,
+ *   `documents.unpublish`, `documents.pinVersion`, `documents.delete`): the
+ *   document's own
  *   `doc:<collection>:<id>` tag — dropping its detail page *and every cached
  *   list that actually contained it* (fetch-time tagging) — plus the coarse
  *   `collection:<name>:<locale>` membership tag for **all** configured
  *   locales, sweeping cached lists whose membership may have changed
  *   (new/removed/newly-matching documents).
+ * - **Document SAVE** (`documents.upsert`) fires **nothing** — see
+ *   {@link PUBLISHED_STATE_OPERATIONS}.
+ * - **Editorial redirect write** (`redirects.save`, `redirects.remove`,
+ *   EC-510): the whole-project sweep tag — deliberately coarse, see
+ *   {@link ROUTING_OPERATIONS}.
  * - **Asset edit** (`assets.upsert` of an existing asset, `assets.remove`,
  *   EC-227): the `asset:<id>` tag, dropping exactly the pages that *baked* that
  *   asset's delivery shape (alt/dimensions/url). An `assets.upsert` CREATE (no
  *   id in the summary — minted server-side) fires nothing: a brand-new asset is
  *   in no cached page yet.
  * - **Fallback**: when a `documents` (or `assets.remove`) event's input summary
- *   was truncated past the identity (EC-139 caps summaries at 160 chars; only
- *   very large upserts hit this), the project sweep tag is emitted — coarse,
- *   always correct, mirroring the EC-155 reference-index fallback.
+ *   was truncated past the identity (EC-139 caps summaries at 160 chars), the
+ *   project sweep tag is emitted — coarse, always correct, mirroring the EC-155
+ *   reference-index fallback. Since EC-501 the surviving document operations
+ *   all carry a small `{ projectId, ref }` input, so this is a defensive path
+ *   rather than a routine one — the routine truncation was the document-bearing
+ *   `documents.upsert`, which no longer reaches here at all.
+ *
+ * Every branch needs only the `projectId`, which serializes FIRST in every
+ * operation input (measured 2026-08-01 across the real `redirects.save`
+ * shapes), so {@link projectIdOfSummary}'s regex survives truncation even when
+ * the rest of the summary is cut mid-string.
  */
 function scoped(projectId, tag) {
     return `p:${projectId}:${tag}`;
@@ -53,17 +71,125 @@ export function assetWebhookTag(projectId, assetId) {
 export function projectSweepWebhookTag(projectId) {
     return scoped(projectId, 'project');
 }
-/** The operations whose success must reach the host's revalidate endpoint. */
-const DOCUMENT_OPERATIONS = new Set([
-    'documents.upsert',
+/**
+ * The document operations that can change **published** output, and therefore
+ * the ones whose success must reach the host's revalidate endpoint.
+ *
+ * EC-224: publish/unpublish/pinVersion move the version pointer; their
+ * `{ projectId, ref }` input drives the doc + per-locale collection tag set
+ * (the flat `documents.setState` op is gone). `documents.delete` removes the
+ * row outright, taking any pinned version with it.
+ *
+ * ## Why `documents.upsert` (a draft SAVE) is NOT here — EC-501
+ *
+ * A save writes the **draft row only**; published readers serve the *pinned
+ * version snapshot*, never the draft. That is structural, not a heuristic:
+ *
+ * - the operation hands the document straight to `cms.upsertDocument`
+ *   (`core/operations/documents.ts`), whose Convex arg list has no
+ *   `publishedVersion` field at all (`studio/convex/cms.ts` `upsertDocument`),
+ *   and whose in-memory twin re-attaches the previous pin verbatim with the
+ *   comment "only publish/unpublish move the pointer"
+ *   (`core/persistence/cms.ts`);
+ * - the published delivery snapshot skips every row without a pin and serves
+ *   the pinned snapshot, "never falling back to the draft"
+ *   (`studio/convex/delivery.ts`);
+ * - the Convex write-chokepoint trigger already encodes exactly this verdict
+ *   server-side — it schedules a revalidation only when `publishedVersion`
+ *   actually changed, "a plain draft save must not invalidate the published
+ *   host cache" (`studio/convex/triggers.ts`, EC-286/EC-146). This emitter was
+ *   simply the one path that never asked.
+ *
+ * Measured before the change (connected studio → capture endpoint, one short
+ * editing session): 12 `documents.upsert` deliveries to 1 `documents.publish`,
+ * and 7 of those 12 carried the **whole-project sweep** tag rather than the
+ * document's own — because a real document's `inputSummary` exceeds the EC-139
+ * 160-char cap, so the identity parse below fails and falls back to the sweep.
+ * A single keystroke-batch on a live page was dropping every cached page *and*
+ * every cached 404 on the site (EC-489 widened 404s to carry collection tags).
+ *
+ * ## The one documented exception (deliberate, not an oversight)
+ *
+ * `cms-data-sources` rows are the sole document class the published delivery
+ * snapshot reads from the **draft** side, on purpose — data sources are project
+ * config, so published bindings must resolve even when the defining row is not
+ * itself published (`studio/convex/delivery.ts`). A save to that system
+ * collection therefore *can* change published output and is now silent.
+ * Accepted because: (a) it is a retired-builder remnant (EC-166/167) with
+ * **zero writers** left in the studio — `provisionSource`/`removeSource` have
+ * no call sites; (b) it only ever invalidated *by accident*, through the
+ * truncated-summary sweep fallback, never through a precise tag; and (c) a
+ * collection-scoped carve-out cannot work here — the collection name is exactly
+ * what the truncated summary loses. If that data layer is ever revived, the fix
+ * belongs at the delivery trust boundary (serve sources published-only), not by
+ * re-broadening this set.
+ */
+const PUBLISHED_STATE_OPERATIONS = new Set([
     'documents.delete',
-    // EC-224: publish/unpublish/pinVersion move the version pointer; their
-    // `{ projectId, ref }` input drives the same doc + per-locale collection tag
-    // set (the flat `documents.setState` op is gone).
     'documents.publish',
     'documents.unpublish',
     'documents.pinVersion',
 ]);
+/**
+ * The **routing** operations (EC-510): editorial redirects, which EC-303 moved
+ * out of config and into the database. Every *enabled* redirect row is
+ * projected into the delivery snapshot the router and `resolvePage` consume
+ * (`studio/convex/delivery.ts`), in BOTH perspectives — so saving, retargeting,
+ * disabling or deleting one changes published output, exactly the question
+ * {@link PUBLISHED_STATE_OPERATIONS} asks. They belong to that question, not a
+ * parallel one; they are a separate set only because their tag is different.
+ *
+ * ## Why the coarse project sweep and NOT a targeted `route:<from>:<locale>`
+ *
+ * The tag vocabulary has `route:<pattern>:<locale>` and a redirect's `from` IS
+ * a route path, so a targeted tag looks available. It is not — it would be
+ * silently wrong in four independent ways, and a silent wrong invalidation is
+ * the exact failure family EC-489/EC-501/this ticket exist to remove:
+ *
+ * 1. **`redirects.remove` has no `from` at all.** Its input is
+ *    `{ projectId, id }` (`core/operations/redirects.ts`), so the path whose
+ *    cache entry must drop is not in the event. Precision is unobtainable, and
+ *    a delete is the single most important case to get right.
+ * 2. **A save can RENAME `from`.** The event carries only the NEW path; the OLD
+ *    one keeps serving a redirect that no longer exists. `OperationEvent` has
+ *    `operation`/`kind`/`status`/`inputSummary` and nothing else — no result,
+ *    no previous row (EC-501 rejected widening it for the same reason) — so the
+ *    emitter cannot even detect that a rename happened.
+ * 3. **Normalization would have to be mirrored.** The cached entry is tagged
+ *    with the resolver's `normalizePath(url)`; `from` is editor-typed free text
+ *    (`z.string().min(1)`), stored verbatim and normalized only at match time.
+ *    A trailing slash or a query string would produce a tag that matches
+ *    nothing — no error, no invalidation.
+ * 4. **The identity truncates.** MEASURED 2026-08-01 on the real schema: a
+ *    Konditorei-shaped migration redirect (legacy permalink → new path)
+ *    serializes to 226 chars and an EC-311 `meta` bag to 216, both past the
+ *    EC-139 160-char cap. A `from`-based tag would work on a demo-sized
+ *    redirect and degrade on the real one — EC-501's pathology in reverse.
+ *
+ * The sweep has none of those failure modes: it needs only `projectId`, which
+ * serializes first and therefore survives truncation, so **the truncation
+ * fallback and the primary answer are the same tag** — correct by design rather
+ * than by accident. `nextCacheTags` stamps `project` on every cached entry, so
+ * it is guaranteed to reach the affected URL whatever the redirect changed.
+ *
+ * ## The cost, and why it is affordable here (unlike EC-501)
+ *
+ * A sweep drops every cached entry, lazily on next read. That was intolerable
+ * for `documents.upsert` because it fired on every ~1s keystroke batch and
+ * *none* of those invalidations were necessary. A redirect write is an
+ * explicit form save on a rail with `inlineEdit: false` and no autosave
+ * (`redirects-collection-view-source.ts`), and every one of them IS a routing
+ * change. Measured on a connected studio: a session that deliberately exercised
+ * every mutation kind — create, retarget, disable, rename, delete — produced 5
+ * writes. The Convex-side path already sweeps the project on every document
+ * publish (`convex/revalidate.ts`, "the honest, reliable v1"), so this is
+ * strictly rarer than a cost the engine already pays.
+ *
+ * If a precise redirect tag is ever wanted, the place to get it is the Convex
+ * write chokepoint, where `change.oldDoc` holds the previous `from` — not here,
+ * where the information does not exist.
+ */
+const ROUTING_OPERATIONS = new Set(['redirects.save', 'redirects.remove']);
 /**
  * Asset-record mutations (EC-227): editing an asset (alt/dimensions/re-upload)
  * must drop the published pages that *baked* its delivery shape, which carry the
@@ -107,13 +233,19 @@ function documentRefOf(value) {
 export function webhookTagsForEvent(event, options) {
     if (event.status !== 'succeeded' || event.kind !== 'command')
         return null;
-    const isDocument = DOCUMENT_OPERATIONS.has(event.operation);
+    const isDocument = PUBLISHED_STATE_OPERATIONS.has(event.operation);
     const isAsset = ASSET_OPERATIONS.has(event.operation);
-    if (!isDocument && !isAsset)
+    const isRouting = ROUTING_OPERATIONS.has(event.operation);
+    if (!isDocument && !isAsset && !isRouting)
         return null;
     const projectId = projectIdOfSummary(event.inputSummary);
     if (projectId === undefined)
         return null;
+    // EC-510: one answer for every redirect write — see `ROUTING_OPERATIONS` for
+    // why the targeted `route:` tag is unobtainable and the sweep is the honest one.
+    if (isRouting) {
+        return { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] };
+    }
     if (isAsset)
         return assetTagsForEvent(projectId, event);
     const parsed = parseSummary(event.inputSummary);
@@ -126,9 +258,10 @@ export function webhookTagsForEvent(event, options) {
     for (const locale of options.locales) {
         tags.add(collectionWebhookTag(projectId, ref.collection, locale));
     }
-    // EC-207: routes/redirects are config-owned (a code deploy, which rebuilds the
-    // host) — they are no longer DB documents, so there is no route-document event
-    // to sweep the project for.
+    // EC-207: ROUTES are config-owned (a code deploy, which rebuilds the host), so
+    // a document event never needs a `route:` tag. Redirects are NOT — EC-303 made
+    // them editorial data and EC-510 gives their own operations the project sweep
+    // (see `ROUTING_OPERATIONS`); a *document* write still cannot change them.
     return { projectId, event: event.operation, tags: [...tags].sort() };
 }
 /** A non-empty string, else `undefined` (the asset id out of a summary). */

package/dist/lib/webhooks/tags.js.map

@@ -1 +1 @@
-{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/lib/webhooks/tags.ts"],"names":[],"mappings":"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","sourcesContent":["import type { OperationEvent } from '@elytracms/core/operations'\n\n/**\n * Pure tag computation for the EC-146 revalidation webhooks: map a succeeded\n * publish-shaped operation event onto the Next cache tags it invalidates.\n *\n * ## Tag format (mirror of `packages/next/src/cache.ts`)\n *\n * The canonical tag format lives in `@elytracms/next` (`src/cache.ts`). The\n * builder cannot depend on that package — it would drag the `next` peer\n * dependency into the studio bundle — so the three formatters are mirrored\n * here. Both sides pin the exact literal strings in their tests\n * (`tags.test.ts` here, `cache.test.ts` there) to keep them in lock-step.\n *\n * Every emitted tag is scoped `p:<projectId>:…` — the dispatcher always knows\n * the project id, and the scope keeps multi-project hosts from\n * cross-invalidating. Hosts must configure the same id as `cache.scope`.\n *\n * ## Which events produce which tags\n *\n * - **Document publish/unpublish/delete/save** (`documents.publish`,\n *   `documents.unpublish`, `documents.pinVersion`, `documents.upsert`,\n *   `documents.delete`): the document's own\n *   `doc:<collection>:<id>` tag — dropping its detail page *and every cached\n *   list that actually contained it* (fetch-time tagging) — plus the coarse\n *   `collection:<name>:<locale>` membership tag for **all** configured\n *   locales, sweeping cached lists whose membership may have changed\n *   (new/removed/newly-matching documents).\n * - **Asset edit** (`assets.upsert` of an existing asset, `assets.remove`,\n *   EC-227): the `asset:<id>` tag, dropping exactly the pages that *baked* that\n *   asset's delivery shape (alt/dimensions/url). An `assets.upsert` CREATE (no\n *   id in the summary — minted server-side) fires nothing: a brand-new asset is\n *   in no cached page yet.\n * - **Fallback**: when a `documents` (or `assets.remove`) event's input summary\n *   was truncated past the identity (EC-139 caps summaries at 160 chars; only\n *   very large upserts hit this), the project sweep tag is emitted — coarse,\n *   always correct, mirroring the EC-155 reference-index fallback.\n */\n\nfunction scoped(projectId: string, tag: string): string {\n  return `p:${projectId}:${tag}`\n}\n\n/** `p:<projectId>:doc:<collection>:<id>` — mirror of `docCacheTag`. */\nexport function docWebhookTag(projectId: string, collection: string, id: string): string {\n  return scoped(projectId, `doc:${collection}:${id}`)\n}\n\n/** `p:<projectId>:collection:<name>:<locale>` — mirror of `collectionCacheTag`. */\nexport function collectionWebhookTag(\n  projectId: string,\n  collection: string,\n  locale: string,\n): string {\n  return scoped(projectId, `collection:${collection}:${locale}`)\n}\n\n/** `p:<projectId>:asset:<id>` — mirror of `assetCacheTag` (EC-227). */\nexport function assetWebhookTag(projectId: string, assetId: string): string {\n  return scoped(projectId, `asset:${assetId}`)\n}\n\n/** `p:<projectId>:project` — mirror of `projectSweepTag`. */\nexport function projectSweepWebhookTag(projectId: string): string {\n  return scoped(projectId, 'project')\n}\n\n/** The operations whose success must reach the host's revalidate endpoint. */\nconst DOCUMENT_OPERATIONS = new Set([\n  'documents.upsert',\n  'documents.delete',\n  // EC-224: publish/unpublish/pinVersion move the version pointer; their\n  // `{ projectId, ref }` input drives the same doc + per-locale collection tag\n  // set (the flat `documents.setState` op is gone).\n  'documents.publish',\n  'documents.unpublish',\n  'documents.pinVersion',\n])\n/**\n * Asset-record mutations (EC-227): editing an asset (alt/dimensions/re-upload)\n * must drop the published pages that *baked* its delivery shape, which carry the\n * `asset:<id>` tag. `assets.remove` always carries `assetId`; `assets.upsert`\n * carries `asset.id` only on an EDIT (a CREATE mints the id server-side).\n */\nconst ASSET_OPERATIONS = new Set(['assets.upsert', 'assets.remove'])\n\n/** One computed webhook emission: which project, why, and which tags. */\nexport interface WebhookTagSet {\n  projectId: string\n  /** The operation name, carried verbatim as the webhook `event`. */\n  event: string\n  /** Sorted, deduplicated, fully scoped Next tag strings. */\n  tags: string[]\n}\n\n/** Tolerant parse of an EC-139 input summary (may be truncated past 160 chars). */\nfunction parseSummary(summary: string): Record<string, unknown> | undefined {\n  try {\n    const parsed: unknown = JSON.parse(summary)\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** Extract the projectId even from a truncated summary (it serializes first). */\nfunction projectIdOfSummary(summary: string): string | undefined {\n  const match = /\"projectId\":\"([^\"]+)\"/.exec(summary)\n  return match?.[1]\n}\n\nfunction documentRefOf(value: unknown): { collection: string; id: string } | undefined {\n  if (typeof value !== 'object' || value === null) return undefined\n  const candidate = value as { collection?: unknown; id?: unknown }\n  return typeof candidate.collection === 'string' &&\n    candidate.collection.length > 0 &&\n    typeof candidate.id === 'string' &&\n    candidate.id.length > 0\n    ? { collection: candidate.collection, id: candidate.id }\n    : undefined\n}\n\n/**\n * Compute the webhook tag set for one lifecycle event, or `null` when the\n * event is not a successful publish-shaped command (queries, failures, and\n * unrelated domains never fire webhooks).\n */\nexport function webhookTagsForEvent(\n  event: Pick<OperationEvent, 'operation' | 'kind' | 'status' | 'inputSummary'>,\n  options: { locales: readonly string[] },\n): WebhookTagSet | null {\n  if (event.status !== 'succeeded' || event.kind !== 'command') return null\n\n  const isDocument = DOCUMENT_OPERATIONS.has(event.operation)\n  const isAsset = ASSET_OPERATIONS.has(event.operation)\n  if (!isDocument && !isAsset) return null\n\n  const projectId = projectIdOfSummary(event.inputSummary)\n  if (projectId === undefined) return null\n\n  if (isAsset) return assetTagsForEvent(projectId, event)\n\n  const parsed = parseSummary(event.inputSummary)\n  const ref = documentRefOf(parsed?.['ref']) ?? documentRefOf(parsed?.['document'])\n  if (!ref) {\n    // Truncated summary (large upsert payload): honest coarse fallback.\n    return { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] }\n  }\n\n  const tags = new Set<string>([docWebhookTag(projectId, ref.collection, ref.id)])\n  for (const locale of options.locales) {\n    tags.add(collectionWebhookTag(projectId, ref.collection, locale))\n  }\n  // EC-207: routes/redirects are config-owned (a code deploy, which rebuilds the\n  // host) — they are no longer DB documents, so there is no route-document event\n  // to sweep the project for.\n  return { projectId, event: event.operation, tags: [...tags].sort() }\n}\n\n/** A non-empty string, else `undefined` (the asset id out of a summary). */\nfunction stringOf(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value : undefined\n}\n\n/**\n * Tags for an asset mutation (EC-227). The edit cases — `assets.remove` (carries\n * `assetId`) and `assets.upsert` of an existing asset (carries `asset.id`) —\n * emit exactly `asset:<id>`, dropping the pages that baked that asset. An\n * `assets.upsert` with **no** id is a CREATE: the id is minted server-side and a\n * brand-new asset cannot be baked into any existing page, so it invalidates\n * nothing (`null`, no webhook). A `remove` missing its id means a truncated\n * summary — sweep the project (coarse, always correct — the document fallback).\n */\nfunction assetTagsForEvent(\n  projectId: string,\n  event: Pick<OperationEvent, 'operation' | 'inputSummary'>,\n): WebhookTagSet | null {\n  const parsed = parseSummary(event.inputSummary)\n  const assetId =\n    event.operation === 'assets.remove'\n      ? stringOf(parsed?.['assetId'])\n      : stringOf((parsed?.['asset'] as { id?: unknown } | undefined)?.id)\n  if (assetId) {\n    return { projectId, event: event.operation, tags: [assetWebhookTag(projectId, assetId)] }\n  }\n  return event.operation === 'assets.remove'\n    ? { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] }\n    : null\n}\n"]}
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/lib/webhooks/tags.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,SAAS,MAAM,CAAC,SAAiB,EAAE,GAAW;IAC5C,OAAO,KAAK,SAAS,IAAI,GAAG,EAAE,CAAA;AAChC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,UAAkB,EAAE,EAAU;IAC7E,OAAO,MAAM,CAAC,SAAS,EAAE,OAAO,UAAU,IAAI,EAAE,EAAE,CAAC,CAAA;AACrD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,UAAkB,EAClB,MAAc;IAEd,OAAO,MAAM,CAAC,SAAS,EAAE,cAAc,UAAU,IAAI,MAAM,EAAE,CAAC,CAAA;AAChE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,OAAe;IAChE,OAAO,MAAM,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,OAAO,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAC;IACzC,kBAAkB;IAClB,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;CACvB,CAAC,CAAA;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,CAAA;AAWpE,mFAAmF;AACnF,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAC3C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAClD,CAAC,CAAE,MAAkC;YACrC,CAAC,CAAC,SAAS,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAS,kBAAkB,CAAC,OAAe;IACzC,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACnD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAA;IACjE,MAAM,SAAS,GAAG,KAA+C,CAAA;IACjE,OAAO,OAAO,SAAS,CAAC,UAAU,KAAK,QAAQ;QAC7C,SAAS,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAC/B,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ;QAChC,SAAS,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC;QACvB,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,UAAU,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE;QACxD,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA6E,EAC7E,OAAuC;IAEvC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAEzE,MAAM,UAAU,GAAG,0BAA0B,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAClE,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IACrD,MAAM,SAAS,GAAG,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IACzD,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAA;IAEtD,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IACxD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IAExC,6EAA6E;IAC7E,iFAAiF;IACjF,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAA;IACzF,CAAC;IAED,IAAI,OAAO;QAAE,OAAO,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;IAEvD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAC/C,MAAM,GAAG,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IACjF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,oEAAoE;QACpE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,EAAE,CAAA;IACzF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAChF,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAA;IACnE,CAAC;IACD,+EAA+E;IAC/E,+EAA+E;IAC/E,8EAA8E;IAC9E,2EAA2E;IAC3E,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAA;AACtE,CAAC;AAED,4EAA4E;AAC5E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CACxB,SAAiB,EACjB,KAAyD;IAEzD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;IAC/C,MAAM,OAAO,GACX,KAAK,CAAC,SAAS,KAAK,eAAe;QACjC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;QAC/B,CAAC,CAAC,QAAQ,CAAE,MAAM,EAAE,CAAC,OAAO,CAAkC,EAAE,EAAE,CAAC,CAAA;IACvE,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,CAAA;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC,SAAS,KAAK,eAAe;QACxC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,EAAE;QAClF,CAAC,CAAC,IAAI,CAAA;AACV,CAAC","sourcesContent":["import type { OperationEvent } from '@elytracms/core/operations'\n\n/**\n * Pure tag computation for the EC-146 revalidation webhooks: map a succeeded\n * publish-shaped operation event onto the Next cache tags it invalidates.\n *\n * ## Tag format (mirror of `packages/next/src/cache.ts`)\n *\n * The canonical tag format lives in `@elytracms/next` (`src/cache.ts`). The\n * builder cannot depend on that package — it would drag the `next` peer\n * dependency into the studio bundle — so the three formatters are mirrored\n * here. Both sides pin the exact literal strings in their tests\n * (`tags.test.ts` here, `cache.test.ts` there) to keep them in lock-step.\n *\n * Every emitted tag is scoped `p:<projectId>:…` — the dispatcher always knows\n * the project id, and the scope keeps multi-project hosts from\n * cross-invalidating. Hosts must configure the same id as `cache.scope`.\n *\n * ## Which events produce which tags\n *\n * The gate is **\"can this operation change PUBLISHED output?\"** — not \"did this\n * operation touch a document\" (EC-501). Live delivery is published-only, so an\n * operation that cannot move published state has no cache entry to drop and\n * every tag it emits is waste by construction.\n *\n * - **Document publish/unpublish/pin/delete** (`documents.publish`,\n *   `documents.unpublish`, `documents.pinVersion`, `documents.delete`): the\n *   document's own\n *   `doc:<collection>:<id>` tag — dropping its detail page *and every cached\n *   list that actually contained it* (fetch-time tagging) — plus the coarse\n *   `collection:<name>:<locale>` membership tag for **all** configured\n *   locales, sweeping cached lists whose membership may have changed\n *   (new/removed/newly-matching documents).\n * - **Document SAVE** (`documents.upsert`) fires **nothing** — see\n *   {@link PUBLISHED_STATE_OPERATIONS}.\n * - **Editorial redirect write** (`redirects.save`, `redirects.remove`,\n *   EC-510): the whole-project sweep tag — deliberately coarse, see\n *   {@link ROUTING_OPERATIONS}.\n * - **Asset edit** (`assets.upsert` of an existing asset, `assets.remove`,\n *   EC-227): the `asset:<id>` tag, dropping exactly the pages that *baked* that\n *   asset's delivery shape (alt/dimensions/url). An `assets.upsert` CREATE (no\n *   id in the summary — minted server-side) fires nothing: a brand-new asset is\n *   in no cached page yet.\n * - **Fallback**: when a `documents` (or `assets.remove`) event's input summary\n *   was truncated past the identity (EC-139 caps summaries at 160 chars), the\n *   project sweep tag is emitted — coarse, always correct, mirroring the EC-155\n *   reference-index fallback. Since EC-501 the surviving document operations\n *   all carry a small `{ projectId, ref }` input, so this is a defensive path\n *   rather than a routine one — the routine truncation was the document-bearing\n *   `documents.upsert`, which no longer reaches here at all.\n *\n * Every branch needs only the `projectId`, which serializes FIRST in every\n * operation input (measured 2026-08-01 across the real `redirects.save`\n * shapes), so {@link projectIdOfSummary}'s regex survives truncation even when\n * the rest of the summary is cut mid-string.\n */\n\nfunction scoped(projectId: string, tag: string): string {\n  return `p:${projectId}:${tag}`\n}\n\n/** `p:<projectId>:doc:<collection>:<id>` — mirror of `docCacheTag`. */\nexport function docWebhookTag(projectId: string, collection: string, id: string): string {\n  return scoped(projectId, `doc:${collection}:${id}`)\n}\n\n/** `p:<projectId>:collection:<name>:<locale>` — mirror of `collectionCacheTag`. */\nexport function collectionWebhookTag(\n  projectId: string,\n  collection: string,\n  locale: string,\n): string {\n  return scoped(projectId, `collection:${collection}:${locale}`)\n}\n\n/** `p:<projectId>:asset:<id>` — mirror of `assetCacheTag` (EC-227). */\nexport function assetWebhookTag(projectId: string, assetId: string): string {\n  return scoped(projectId, `asset:${assetId}`)\n}\n\n/** `p:<projectId>:project` — mirror of `projectSweepTag`. */\nexport function projectSweepWebhookTag(projectId: string): string {\n  return scoped(projectId, 'project')\n}\n\n/**\n * The document operations that can change **published** output, and therefore\n * the ones whose success must reach the host's revalidate endpoint.\n *\n * EC-224: publish/unpublish/pinVersion move the version pointer; their\n * `{ projectId, ref }` input drives the doc + per-locale collection tag set\n * (the flat `documents.setState` op is gone). `documents.delete` removes the\n * row outright, taking any pinned version with it.\n *\n * ## Why `documents.upsert` (a draft SAVE) is NOT here — EC-501\n *\n * A save writes the **draft row only**; published readers serve the *pinned\n * version snapshot*, never the draft. That is structural, not a heuristic:\n *\n * - the operation hands the document straight to `cms.upsertDocument`\n *   (`core/operations/documents.ts`), whose Convex arg list has no\n *   `publishedVersion` field at all (`studio/convex/cms.ts` `upsertDocument`),\n *   and whose in-memory twin re-attaches the previous pin verbatim with the\n *   comment \"only publish/unpublish move the pointer\"\n *   (`core/persistence/cms.ts`);\n * - the published delivery snapshot skips every row without a pin and serves\n *   the pinned snapshot, \"never falling back to the draft\"\n *   (`studio/convex/delivery.ts`);\n * - the Convex write-chokepoint trigger already encodes exactly this verdict\n *   server-side — it schedules a revalidation only when `publishedVersion`\n *   actually changed, \"a plain draft save must not invalidate the published\n *   host cache\" (`studio/convex/triggers.ts`, EC-286/EC-146). This emitter was\n *   simply the one path that never asked.\n *\n * Measured before the change (connected studio → capture endpoint, one short\n * editing session): 12 `documents.upsert` deliveries to 1 `documents.publish`,\n * and 7 of those 12 carried the **whole-project sweep** tag rather than the\n * document's own — because a real document's `inputSummary` exceeds the EC-139\n * 160-char cap, so the identity parse below fails and falls back to the sweep.\n * A single keystroke-batch on a live page was dropping every cached page *and*\n * every cached 404 on the site (EC-489 widened 404s to carry collection tags).\n *\n * ## The one documented exception (deliberate, not an oversight)\n *\n * `cms-data-sources` rows are the sole document class the published delivery\n * snapshot reads from the **draft** side, on purpose — data sources are project\n * config, so published bindings must resolve even when the defining row is not\n * itself published (`studio/convex/delivery.ts`). A save to that system\n * collection therefore *can* change published output and is now silent.\n * Accepted because: (a) it is a retired-builder remnant (EC-166/167) with\n * **zero writers** left in the studio — `provisionSource`/`removeSource` have\n * no call sites; (b) it only ever invalidated *by accident*, through the\n * truncated-summary sweep fallback, never through a precise tag; and (c) a\n * collection-scoped carve-out cannot work here — the collection name is exactly\n * what the truncated summary loses. If that data layer is ever revived, the fix\n * belongs at the delivery trust boundary (serve sources published-only), not by\n * re-broadening this set.\n */\nconst PUBLISHED_STATE_OPERATIONS = new Set([\n  'documents.delete',\n  'documents.publish',\n  'documents.unpublish',\n  'documents.pinVersion',\n])\n/**\n * The **routing** operations (EC-510): editorial redirects, which EC-303 moved\n * out of config and into the database. Every *enabled* redirect row is\n * projected into the delivery snapshot the router and `resolvePage` consume\n * (`studio/convex/delivery.ts`), in BOTH perspectives — so saving, retargeting,\n * disabling or deleting one changes published output, exactly the question\n * {@link PUBLISHED_STATE_OPERATIONS} asks. They belong to that question, not a\n * parallel one; they are a separate set only because their tag is different.\n *\n * ## Why the coarse project sweep and NOT a targeted `route:<from>:<locale>`\n *\n * The tag vocabulary has `route:<pattern>:<locale>` and a redirect's `from` IS\n * a route path, so a targeted tag looks available. It is not — it would be\n * silently wrong in four independent ways, and a silent wrong invalidation is\n * the exact failure family EC-489/EC-501/this ticket exist to remove:\n *\n * 1. **`redirects.remove` has no `from` at all.** Its input is\n *    `{ projectId, id }` (`core/operations/redirects.ts`), so the path whose\n *    cache entry must drop is not in the event. Precision is unobtainable, and\n *    a delete is the single most important case to get right.\n * 2. **A save can RENAME `from`.** The event carries only the NEW path; the OLD\n *    one keeps serving a redirect that no longer exists. `OperationEvent` has\n *    `operation`/`kind`/`status`/`inputSummary` and nothing else — no result,\n *    no previous row (EC-501 rejected widening it for the same reason) — so the\n *    emitter cannot even detect that a rename happened.\n * 3. **Normalization would have to be mirrored.** The cached entry is tagged\n *    with the resolver's `normalizePath(url)`; `from` is editor-typed free text\n *    (`z.string().min(1)`), stored verbatim and normalized only at match time.\n *    A trailing slash or a query string would produce a tag that matches\n *    nothing — no error, no invalidation.\n * 4. **The identity truncates.** MEASURED 2026-08-01 on the real schema: a\n *    Konditorei-shaped migration redirect (legacy permalink → new path)\n *    serializes to 226 chars and an EC-311 `meta` bag to 216, both past the\n *    EC-139 160-char cap. A `from`-based tag would work on a demo-sized\n *    redirect and degrade on the real one — EC-501's pathology in reverse.\n *\n * The sweep has none of those failure modes: it needs only `projectId`, which\n * serializes first and therefore survives truncation, so **the truncation\n * fallback and the primary answer are the same tag** — correct by design rather\n * than by accident. `nextCacheTags` stamps `project` on every cached entry, so\n * it is guaranteed to reach the affected URL whatever the redirect changed.\n *\n * ## The cost, and why it is affordable here (unlike EC-501)\n *\n * A sweep drops every cached entry, lazily on next read. That was intolerable\n * for `documents.upsert` because it fired on every ~1s keystroke batch and\n * *none* of those invalidations were necessary. A redirect write is an\n * explicit form save on a rail with `inlineEdit: false` and no autosave\n * (`redirects-collection-view-source.ts`), and every one of them IS a routing\n * change. Measured on a connected studio: a session that deliberately exercised\n * every mutation kind — create, retarget, disable, rename, delete — produced 5\n * writes. The Convex-side path already sweeps the project on every document\n * publish (`convex/revalidate.ts`, \"the honest, reliable v1\"), so this is\n * strictly rarer than a cost the engine already pays.\n *\n * If a precise redirect tag is ever wanted, the place to get it is the Convex\n * write chokepoint, where `change.oldDoc` holds the previous `from` — not here,\n * where the information does not exist.\n */\nconst ROUTING_OPERATIONS = new Set(['redirects.save', 'redirects.remove'])\n\n/**\n * Asset-record mutations (EC-227): editing an asset (alt/dimensions/re-upload)\n * must drop the published pages that *baked* its delivery shape, which carry the\n * `asset:<id>` tag. `assets.remove` always carries `assetId`; `assets.upsert`\n * carries `asset.id` only on an EDIT (a CREATE mints the id server-side).\n */\nconst ASSET_OPERATIONS = new Set(['assets.upsert', 'assets.remove'])\n\n/** One computed webhook emission: which project, why, and which tags. */\nexport interface WebhookTagSet {\n  projectId: string\n  /** The operation name, carried verbatim as the webhook `event`. */\n  event: string\n  /** Sorted, deduplicated, fully scoped Next tag strings. */\n  tags: string[]\n}\n\n/** Tolerant parse of an EC-139 input summary (may be truncated past 160 chars). */\nfunction parseSummary(summary: string): Record<string, unknown> | undefined {\n  try {\n    const parsed: unknown = JSON.parse(summary)\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/** Extract the projectId even from a truncated summary (it serializes first). */\nfunction projectIdOfSummary(summary: string): string | undefined {\n  const match = /\"projectId\":\"([^\"]+)\"/.exec(summary)\n  return match?.[1]\n}\n\nfunction documentRefOf(value: unknown): { collection: string; id: string } | undefined {\n  if (typeof value !== 'object' || value === null) return undefined\n  const candidate = value as { collection?: unknown; id?: unknown }\n  return typeof candidate.collection === 'string' &&\n    candidate.collection.length > 0 &&\n    typeof candidate.id === 'string' &&\n    candidate.id.length > 0\n    ? { collection: candidate.collection, id: candidate.id }\n    : undefined\n}\n\n/**\n * Compute the webhook tag set for one lifecycle event, or `null` when the\n * event is not a successful publish-shaped command (queries, failures, and\n * unrelated domains never fire webhooks).\n */\nexport function webhookTagsForEvent(\n  event: Pick<OperationEvent, 'operation' | 'kind' | 'status' | 'inputSummary'>,\n  options: { locales: readonly string[] },\n): WebhookTagSet | null {\n  if (event.status !== 'succeeded' || event.kind !== 'command') return null\n\n  const isDocument = PUBLISHED_STATE_OPERATIONS.has(event.operation)\n  const isAsset = ASSET_OPERATIONS.has(event.operation)\n  const isRouting = ROUTING_OPERATIONS.has(event.operation)\n  if (!isDocument && !isAsset && !isRouting) return null\n\n  const projectId = projectIdOfSummary(event.inputSummary)\n  if (projectId === undefined) return null\n\n  // EC-510: one answer for every redirect write — see `ROUTING_OPERATIONS` for\n  // why the targeted `route:` tag is unobtainable and the sweep is the honest one.\n  if (isRouting) {\n    return { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] }\n  }\n\n  if (isAsset) return assetTagsForEvent(projectId, event)\n\n  const parsed = parseSummary(event.inputSummary)\n  const ref = documentRefOf(parsed?.['ref']) ?? documentRefOf(parsed?.['document'])\n  if (!ref) {\n    // Truncated summary (large upsert payload): honest coarse fallback.\n    return { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] }\n  }\n\n  const tags = new Set<string>([docWebhookTag(projectId, ref.collection, ref.id)])\n  for (const locale of options.locales) {\n    tags.add(collectionWebhookTag(projectId, ref.collection, locale))\n  }\n  // EC-207: ROUTES are config-owned (a code deploy, which rebuilds the host), so\n  // a document event never needs a `route:` tag. Redirects are NOT — EC-303 made\n  // them editorial data and EC-510 gives their own operations the project sweep\n  // (see `ROUTING_OPERATIONS`); a *document* write still cannot change them.\n  return { projectId, event: event.operation, tags: [...tags].sort() }\n}\n\n/** A non-empty string, else `undefined` (the asset id out of a summary). */\nfunction stringOf(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value : undefined\n}\n\n/**\n * Tags for an asset mutation (EC-227). The edit cases — `assets.remove` (carries\n * `assetId`) and `assets.upsert` of an existing asset (carries `asset.id`) —\n * emit exactly `asset:<id>`, dropping the pages that baked that asset. An\n * `assets.upsert` with **no** id is a CREATE: the id is minted server-side and a\n * brand-new asset cannot be baked into any existing page, so it invalidates\n * nothing (`null`, no webhook). A `remove` missing its id means a truncated\n * summary — sweep the project (coarse, always correct — the document fallback).\n */\nfunction assetTagsForEvent(\n  projectId: string,\n  event: Pick<OperationEvent, 'operation' | 'inputSummary'>,\n): WebhookTagSet | null {\n  const parsed = parseSummary(event.inputSummary)\n  const assetId =\n    event.operation === 'assets.remove'\n      ? stringOf(parsed?.['assetId'])\n      : stringOf((parsed?.['asset'] as { id?: unknown } | undefined)?.id)\n  if (assetId) {\n    return { projectId, event: event.operation, tags: [assetWebhookTag(projectId, assetId)] }\n  }\n  return event.operation === 'assets.remove'\n    ? { projectId, event: event.operation, tags: [projectSweepWebhookTag(projectId)] }\n    : null\n}\n"]}

package/dist/lib/workspace/config-issues.d.ts

@@ -0,0 +1,56 @@
+import type { CollectionDef } from '@elytracms/core/cms-core';
+import type { CustomizationIssue } from '@elytracms/core/studio-core';
+/**
+ * EC-479 — project-level configuration findings for the section-rail foot.
+ *
+ * The engine used to fill a missing declaration with its own `cms-core` fixtures:
+ * `?? sampleFilterableCollections` in the CMS store, `?? sampleDocuments` beside
+ * it, `?? sampleLocaleConfig` in the locale store. A studio whose config never
+ * arrived therefore looked *configured* — it showed six documents about Ada
+ * Lovelace under a four-collection schema, in `en/de`, none of which the project
+ * had declared. The owner's ruling (2026-07-30): "fixtures should only show in the
+ * playground, but not be hard-wired in the engine".
+ *
+ * With the fallbacks retired the same state renders as an empty CMS, which on its
+ * own is the OTHER silent failure — the house rule bans both ("if you are writing
+ * a fallback that hides a broken state, that *is* the bug"). This module is the
+ * third option: say so, at the rail foot, where EC-467's reuse issues and EC-469's
+ * URL-map issues already report project-level problems, on every studio surface.
+ *
+ * Pure and deterministic — no config-holder reads, no React. The caller supplies
+ * the resolved config (`resolveDeploymentCollections()`), which is also what makes
+ * this testable against a synthetic project instead of the live one.
+ */
+/**
+ * The extension-point name stamped on these issues. Not a customization registry
+ * like `'sidebar'`/`'fieldRenderers'` — the finding is about the project's own
+ * declarations, so it locates the config, not an override list.
+ */
+export declare const PROJECT_CONFIG_POINT = "project";
+/**
+ * Catalog keys for the issues below (EC-478). Named here, next to the producer, so
+ * the studio's i18n parity test asserts coverage against the producer rather than a
+ * hand-copied list — the same shape as `default-modules.tsx`'s `KEYSPACE_KEYS`.
+ */
+export declare const PROJECT_CONFIG_ISSUE_KEYS: {
+    readonly noCollections: "customization.issue.noCollections";
+};
+/**
+ * Report what the project has NOT declared but the studio cannot work without.
+ *
+ * Today that is exactly one thing: collections. A studio with none has no content
+ * model at all — the CMS rail expands to nothing, every list is empty, and before
+ * EC-479 the store quietly substituted the engine's sample schema so none of that
+ * was visible. The remedy is one line in `elytra.config.ts`, which is why the
+ * message names the file.
+ *
+ * Deliberately NOT reported here: an absent locale config. A `Project` only exists
+ * for a config-declared project and `resolveWorkspaceConfig` gives every one of
+ * them a `locales` array, so "no locales" is unreachable from the rail's vantage
+ * point; the CMS session guards it directly instead (`CmsProvider`), where it is
+ * both reachable and actionable. Reporting an unreachable state would be copy
+ * nobody can trigger. Since EC-490 (owner-ratified 2026-08-01) that unreachability
+ * is STRUCTURAL rather than incidental: a config declaring no `locales` is rejected
+ * outright, so there is no resolved project behind which the question could hide.
+ */
+export declare function projectConfigIssues(collections: readonly CollectionDef[]): CustomizationIssue[];

package/dist/lib/workspace/config-issues.js

@@ -0,0 +1,72 @@
+/**
+ * EC-479 — project-level configuration findings for the section-rail foot.
+ *
+ * The engine used to fill a missing declaration with its own `cms-core` fixtures:
+ * `?? sampleFilterableCollections` in the CMS store, `?? sampleDocuments` beside
+ * it, `?? sampleLocaleConfig` in the locale store. A studio whose config never
+ * arrived therefore looked *configured* — it showed six documents about Ada
+ * Lovelace under a four-collection schema, in `en/de`, none of which the project
+ * had declared. The owner's ruling (2026-07-30): "fixtures should only show in the
+ * playground, but not be hard-wired in the engine".
+ *
+ * With the fallbacks retired the same state renders as an empty CMS, which on its
+ * own is the OTHER silent failure — the house rule bans both ("if you are writing
+ * a fallback that hides a broken state, that *is* the bug"). This module is the
+ * third option: say so, at the rail foot, where EC-467's reuse issues and EC-469's
+ * URL-map issues already report project-level problems, on every studio surface.
+ *
+ * Pure and deterministic — no config-holder reads, no React. The caller supplies
+ * the resolved config (`resolveDeploymentCollections()`), which is also what makes
+ * this testable against a synthetic project instead of the live one.
+ */
+/**
+ * The extension-point name stamped on these issues. Not a customization registry
+ * like `'sidebar'`/`'fieldRenderers'` — the finding is about the project's own
+ * declarations, so it locates the config, not an override list.
+ */
+export const PROJECT_CONFIG_POINT = 'project';
+/** The file a developer fixes these findings in — interpolated, never localized. */
+const CONFIG_FILE = 'elytra.config.ts';
+/**
+ * Catalog keys for the issues below (EC-478). Named here, next to the producer, so
+ * the studio's i18n parity test asserts coverage against the producer rather than a
+ * hand-copied list — the same shape as `default-modules.tsx`'s `KEYSPACE_KEYS`.
+ */
+export const PROJECT_CONFIG_ISSUE_KEYS = {
+    noCollections: 'customization.issue.noCollections',
+};
+/**
+ * Report what the project has NOT declared but the studio cannot work without.
+ *
+ * Today that is exactly one thing: collections. A studio with none has no content
+ * model at all — the CMS rail expands to nothing, every list is empty, and before
+ * EC-479 the store quietly substituted the engine's sample schema so none of that
+ * was visible. The remedy is one line in `elytra.config.ts`, which is why the
+ * message names the file.
+ *
+ * Deliberately NOT reported here: an absent locale config. A `Project` only exists
+ * for a config-declared project and `resolveWorkspaceConfig` gives every one of
+ * them a `locales` array, so "no locales" is unreachable from the rail's vantage
+ * point; the CMS session guards it directly instead (`CmsProvider`), where it is
+ * both reachable and actionable. Reporting an unreachable state would be copy
+ * nobody can trigger. Since EC-490 (owner-ratified 2026-08-01) that unreachability
+ * is STRUCTURAL rather than incidental: a config declaring no `locales` is rejected
+ * outright, so there is no resolved project behind which the question could hide.
+ */
+export function projectConfigIssues(collections) {
+    if (collections.length > 0)
+        return [];
+    return [
+        {
+            code: 'missing-configuration',
+            severity: 'error',
+            message: `This project declares no content collections. Add them to "${CONFIG_FILE}" — the studio shows your schema or none, never sample content.`,
+            messageRef: {
+                key: PROJECT_CONFIG_ISSUE_KEYS.noCollections,
+                vars: { file: CONFIG_FILE },
+            },
+            point: PROJECT_CONFIG_POINT,
+        },
+    ];
+}
+//# sourceMappingURL=config-issues.js.map

package/dist/lib/workspace/config-issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-issues.js","sourceRoot":"","sources":["../../../src/lib/workspace/config-issues.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAA;AAE7C,oFAAoF;AACpF,MAAM,WAAW,GAAG,kBAAkB,CAAA;AAEtC;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,aAAa,EAAE,mCAAmC;CAC1C,CAAA;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAAqC;IAErC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAA;IACrC,OAAO;QACL;YACE,IAAI,EAAE,uBAAuB;YAC7B,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,8DAA8D,WAAW,iEAAiE;YACnJ,UAAU,EAAE;gBACV,GAAG,EAAE,yBAAyB,CAAC,aAAa;gBAC5C,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;aAC5B;YACD,KAAK,EAAE,oBAAoB;SAC5B;KACF,CAAA;AACH,CAAC","sourcesContent":["import type { CollectionDef } from '@elytracms/core/cms-core'\nimport type { CustomizationIssue } from '@elytracms/core/studio-core'\n\n/**\n * EC-479 — project-level configuration findings for the section-rail foot.\n *\n * The engine used to fill a missing declaration with its own `cms-core` fixtures:\n * `?? sampleFilterableCollections` in the CMS store, `?? sampleDocuments` beside\n * it, `?? sampleLocaleConfig` in the locale store. A studio whose config never\n * arrived therefore looked *configured* — it showed six documents about Ada\n * Lovelace under a four-collection schema, in `en/de`, none of which the project\n * had declared. The owner's ruling (2026-07-30): \"fixtures should only show in the\n * playground, but not be hard-wired in the engine\".\n *\n * With the fallbacks retired the same state renders as an empty CMS, which on its\n * own is the OTHER silent failure — the house rule bans both (\"if you are writing\n * a fallback that hides a broken state, that *is* the bug\"). This module is the\n * third option: say so, at the rail foot, where EC-467's reuse issues and EC-469's\n * URL-map issues already report project-level problems, on every studio surface.\n *\n * Pure and deterministic — no config-holder reads, no React. The caller supplies\n * the resolved config (`resolveDeploymentCollections()`), which is also what makes\n * this testable against a synthetic project instead of the live one.\n */\n\n/**\n * The extension-point name stamped on these issues. Not a customization registry\n * like `'sidebar'`/`'fieldRenderers'` — the finding is about the project's own\n * declarations, so it locates the config, not an override list.\n */\nexport const PROJECT_CONFIG_POINT = 'project'\n\n/** The file a developer fixes these findings in — interpolated, never localized. */\nconst CONFIG_FILE = 'elytra.config.ts'\n\n/**\n * Catalog keys for the issues below (EC-478). Named here, next to the producer, so\n * the studio's i18n parity test asserts coverage against the producer rather than a\n * hand-copied list — the same shape as `default-modules.tsx`'s `KEYSPACE_KEYS`.\n */\nexport const PROJECT_CONFIG_ISSUE_KEYS = {\n  noCollections: 'customization.issue.noCollections',\n} as const\n\n/**\n * Report what the project has NOT declared but the studio cannot work without.\n *\n * Today that is exactly one thing: collections. A studio with none has no content\n * model at all — the CMS rail expands to nothing, every list is empty, and before\n * EC-479 the store quietly substituted the engine's sample schema so none of that\n * was visible. The remedy is one line in `elytra.config.ts`, which is why the\n * message names the file.\n *\n * Deliberately NOT reported here: an absent locale config. A `Project` only exists\n * for a config-declared project and `resolveWorkspaceConfig` gives every one of\n * them a `locales` array, so \"no locales\" is unreachable from the rail's vantage\n * point; the CMS session guards it directly instead (`CmsProvider`), where it is\n * both reachable and actionable. Reporting an unreachable state would be copy\n * nobody can trigger. Since EC-490 (owner-ratified 2026-08-01) that unreachability\n * is STRUCTURAL rather than incidental: a config declaring no `locales` is rejected\n * outright, so there is no resolved project behind which the question could hide.\n */\nexport function projectConfigIssues(\n  collections: readonly CollectionDef[],\n): CustomizationIssue[] {\n  if (collections.length > 0) return []\n  return [\n    {\n      code: 'missing-configuration',\n      severity: 'error',\n      message: `This project declares no content collections. Add them to \"${CONFIG_FILE}\" — the studio shows your schema or none, never sample content.`,\n      messageRef: {\n        key: PROJECT_CONFIG_ISSUE_KEYS.noCollections,\n        vars: { file: CONFIG_FILE },\n      },\n      point: PROJECT_CONFIG_POINT,\n    },\n  ]\n}\n"]}

package/dist/lib/workspace/index.d.ts

@@ -4,6 +4,7 @@ import type { SidebarNode } from '../../components/app-views/module.js';
 import type { CustomFieldRenderer, StudioConfig } from '../../components/app-views/studio-config.js';
 import type { GeneratedPreviewLookup } from '../../components/builder/blocks-model.js';
 import type { WorkspaceState } from './workspace-source.js';
+export { PROJECT_CONFIG_ISSUE_KEYS, PROJECT_CONFIG_POINT, projectConfigIssues, } from './config-issues.js';
 export { resolveWorkspaceState } from './workspace-source.js';
 export type { WorkspaceSources, WorkspaceState } from './workspace-source.js';
 export { isSingleProjectWorkspace, launcherAutoForwardTarget, persistedProjects, selectSwitcherProjects, soleWorkspaceProject, unprovisionedProjects, } from './switcher-source.js';
@@ -145,6 +146,14 @@ export declare function resolveDeploymentSidebar(): SidebarNode[] | undefined;
  * body, kit `tokensCss` only). Studio-wide, like the rail and field renderers.
  */
 export declare function resolveDeploymentCanvasTheme(): StudioConfig['canvas'];
+/**
+ * The reusable-elements declaration from the studio config (EC-467): WHICH
+ * component is the project's reuse embed. Studio-only (from `defineStudio`, never
+ * the delivery bundle); `undefined` when none — the studio then INFERS the embed
+ * from the manifests + collections exactly as it always has (absence means infer,
+ * not off). Studio-wide, like the rail and field renderers.
+ */
+export declare function resolveDeploymentReuse(): StudioConfig['reuse'];
 /**
  * The resolved URL routes of the active config project (EC-207, "routes as
  * code"). Routes are config-sourced: the studio reads the materialized
@@ -162,14 +171,21 @@ export declare function resolveDeploymentRoutes(): RouteRecord[];
  */
 export declare function resolveDeploymentLocales(): string[];
 /**
- * The active config project's locales as a `LocaleConfig` (EC-357 finding #3).
- * Locales are structure and structure is code: when `elytra.config.ts` declares
- * them, they drive the studio's ambient locale switcher in EVERY mode — the CMS
- * surface must not fall back to the sample `en/de` fixture (playground, or a
- * connected first run with nothing persisted) when the config says otherwise.
- * `undefined` when no config project is active or it declares no locales (env-only
- * wiring keeps the existing kit/sample fallbacks). A missing/invalid explicit
- * default falls back to the first declared locale.
+ * The active config project's `LocaleConfig` (EC-357 finding #3). Locales are
+ * structure and structure is code: when `elytra.config.ts` declares them, they
+ * drive the studio's ambient locale switcher in EVERY mode — the CMS surface must
+ * not fall back to the sample `en/de` fixture (playground, or a connected first
+ * run with nothing persisted) when the config says otherwise. `undefined` when no
+ * config project is active (env-only wiring keeps the existing kit/sample
+ * fallbacks).
+ *
+ * EC-519: this used to REASSEMBLE the config's flat `locales` + `defaultLocale`
+ * pair into a `LocaleConfig`, and had grown its own repair rule — an absent or
+ * out-of-set default fell back to `locales[0]`. That is a fourth place a locale
+ * could be invented, in the surface furthest from the author. The resolver now
+ * hands over the same `LocaleConfig` the delivery host takes, so there is nothing
+ * to reassemble and nothing to repair: a default outside the set is a config
+ * ERROR (`default-locale-not-in-locales`) and the project never resolves.
  */
 export declare function resolveDeploymentLocaleConfig(): LocaleConfig | undefined;
 /**

package/dist/lib/workspace/index.js

@@ -1,6 +1,7 @@
 import { frontendUrlForEnvironment } from '@elytracms/core/studio-core';
 import { provideStudioEnv } from '../persistence/backend-mode.js';
 import { resolveWorkspaceState } from './workspace-source.js';
+export { PROJECT_CONFIG_ISSUE_KEYS, PROJECT_CONFIG_POINT, projectConfigIssues, } from './config-issues.js';
 export { resolveWorkspaceState } from './workspace-source.js';
 export { isSingleProjectWorkspace, launcherAutoForwardTarget, persistedProjects, selectSwitcherProjects, soleWorkspaceProject, unprovisionedProjects, } from './switcher-source.js';
 let cached = null;
@@ -217,6 +218,16 @@ export function resolveDeploymentSidebar() {
 export function resolveDeploymentCanvasTheme() {
     return studioConfig?.canvas;
 }
+/**
+ * The reusable-elements declaration from the studio config (EC-467): WHICH
+ * component is the project's reuse embed. Studio-only (from `defineStudio`, never
+ * the delivery bundle); `undefined` when none — the studio then INFERS the embed
+ * from the manifests + collections exactly as it always has (absence means infer,
+ * not off). Studio-wide, like the rail and field renderers.
+ */
+export function resolveDeploymentReuse() {
+    return studioConfig?.reuse;
+}
 /**
  * The resolved URL routes of the active config project (EC-207, "routes as
  * code"). Routes are config-sourced: the studio reads the materialized
@@ -238,28 +249,27 @@ export function resolveDeploymentRoutes() {
  * (e.g. `/de`, `/fr`), never just the default. `[]` when wired by env alone.
  */
 export function resolveDeploymentLocales() {
-    return activeConfigProject()?.locales ?? [];
+    return activeConfigProject()?.locales.locales ?? [];
 }
 /**
- * The active config project's locales as a `LocaleConfig` (EC-357 finding #3).
- * Locales are structure and structure is code: when `elytra.config.ts` declares
- * them, they drive the studio's ambient locale switcher in EVERY mode — the CMS
- * surface must not fall back to the sample `en/de` fixture (playground, or a
- * connected first run with nothing persisted) when the config says otherwise.
- * `undefined` when no config project is active or it declares no locales (env-only
- * wiring keeps the existing kit/sample fallbacks). A missing/invalid explicit
- * default falls back to the first declared locale.
+ * The active config project's `LocaleConfig` (EC-357 finding #3). Locales are
+ * structure and structure is code: when `elytra.config.ts` declares them, they
+ * drive the studio's ambient locale switcher in EVERY mode — the CMS surface must
+ * not fall back to the sample `en/de` fixture (playground, or a connected first
+ * run with nothing persisted) when the config says otherwise. `undefined` when no
+ * config project is active (env-only wiring keeps the existing kit/sample
+ * fallbacks).
+ *
+ * EC-519: this used to REASSEMBLE the config's flat `locales` + `defaultLocale`
+ * pair into a `LocaleConfig`, and had grown its own repair rule — an absent or
+ * out-of-set default fell back to `locales[0]`. That is a fourth place a locale
+ * could be invented, in the surface furthest from the author. The resolver now
+ * hands over the same `LocaleConfig` the delivery host takes, so there is nothing
+ * to reassemble and nothing to repair: a default outside the set is a config
+ * ERROR (`default-locale-not-in-locales`) and the project never resolves.
  */
 export function resolveDeploymentLocaleConfig() {
-    const project = activeConfigProject();
-    if (!project || project.locales.length === 0)
-        return undefined;
-    const fallback = project.locales[0];
-    const explicit = project.defaultLocale;
-    return {
-        default: explicit && project.locales.includes(explicit) ? explicit : fallback,
-        locales: [...project.locales],
-    };
+    return activeConfigProject()?.locales;
 }
 /**
  * The active project's components reference (EC-194, AD-11): where the consuming