@glw907/cairn-cms 0.24.0 → 0.29.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to this project are recorded here, most recent first.
+
+## 0.29.0
+
+Consolidated the URL-identity model. A content entry's id, slug, date, and permalink are now derived in
+one place (`entryIdentity`), so the content index and the manifest cannot drift on an entry's URL, and a
+site's concept descriptors are resolved through one path shared by the admin runtime and the delivery
+layer. No public surface changed.
+
+The YAML URL policy is now validated at build. A permalink pattern must be root-relative and use only the
+tokens `:slug`, `:year`, `:month`, and `:day`, a date token is valid only on a dated concept, a
+`datePrefix` must be `year`, `month`, or `day`, and a policy keyed to an undeclared concept fails the
+build.
+
+Behavior note: a site whose `content:` URL policy was malformed and silently defaulted will now fail the
+build with a named error. A valid policy is unaffected.
+
+## 0.28.0
+
+### Security
+Closed the render attribute-sink residual by construction. A new post-dispatch guard runs last in
+`createRenderer` and neutralizes the sinks a component `build()` could route a raw author attribute
+value into, including the unsafe URL schemes `javascript:`, `data:`, and `vbscript:` in `href`,
+`src`, `srcset`, `xlink:href`, `poster`, `formaction`, `action`, `object`'s `data`, and
+`background`, the inline `on*` event handlers, and inline `style`, which is stripped wholesale. Safe
+schemes, relative URLs, anchors, and the `cairn:` token are preserved. The guard is gated by the
+existing `unsafeDisableSanitize` switch.
+
+Behavior note: a site whose component `build()` emits a non-standard URL scheme, an `on*` handler,
+or inline `style` will see that output neutralized. Route dynamic styling through a class or an
+inert `data-*` attribute instead.
+
+## 0.27.0
+
+### Changed (breaking)
+Narrowed the public export surface so each symbol has one canonical home. The `.` root and
+`/sveltekit` no longer re-export another subpath's symbols, and the internal GitHub, signing, and
+hast helpers left the public API. No symbol changed behavior; only where it exports from.
+
+- Consumers must: import the delivery read helpers (`createContentIndex`, `createSiteIndexes`, the
+  feed, sitemap, robots, SEO, and pagination builders, `permalink`) from `@glw907/cairn-cms/delivery/data`
+  instead of the `.` root.
+- Consumers must: import the public route loaders and the `*Response` helpers (`createPublicRoutes`,
+  `rssResponse`, `jsonFeedResponse`, `sitemapResponse`, `robotsResponse`) and the public route types
+  (`PublicRoutesDeps`, the public `ListData`, `TagData`, `TagIndexData`, `EntryData`) from
+  `@glw907/cairn-cms/delivery` instead of the `.` root or `/sveltekit`.
+- Consumers must: stop importing the internal helpers that left the public API (`appJwt`,
+  `installationToken`, `signingSelfTest`, `appCredentials`, `treeUrl`, `contentsUrl`, `readRaw`,
+  `fileSha`, `listMarkdown`, `markdownFilesIn`, `commitFile`, `isElement`, `strProp`, `markFirstList`);
+  the engine wires GitHub token minting and the render pipeline internally, so no consumer needs them.
+
+## 0.26.0
+
+### Added
+- A `cairnManifest()` Vite plugin (`@glw907/cairn-cms/vite`) verifies the committed content manifest on
+  every build and fails the build with a diff naming what drifted. The check runs outside the prerender
+  lifecycle, so `handleHttpError` cannot mask it. Consumers must: add `cairnManifest({ configModule,
+  content, manifestPath })` to the Vite config.
+- A `cairn-manifest` bin regenerates the committed manifest from a Vite context. Consumers must: set the
+  regenerate script to `"cairn:manifest": "cairn-manifest"` and delete the hand-written
+  `scripts/build-manifest.mjs`.
+- A node-safe `@glw907/cairn-cms/delivery/data` entry exposes the pure delivery projections with no
+  `@sveltejs/kit` in the graph. Consumers must: move any plain-Node import of a delivery data helper
+  (such as `buildSiteManifest`) from `@glw907/cairn-cms/delivery` to `@glw907/cairn-cms/delivery/data`.
+
+### Changed
+- `verifyManifest` now throws an error that names the added, removed, and changed entries. Consumers
+  must: nothing. The message is strictly more informative.
+
+## 0.25.0
+
+### Changed (breaking)
+- `composeRuntime` now takes a single object, `composeRuntime({ adapter, siteConfig, extensions? })`,
+  and derives the per-concept URL policy from `siteConfig`. The loose third `urlPolicy` argument is
+  gone, and a missing `siteConfig` throws. Consumers must: pass the parsed site config to every
+  `composeRuntime` call and drop any hand-passed URL policy.
+
+### Changed
+- `createRenderer()` now defaults its registry to the empty registry, so a plain-prose site calls
+  `createRenderer()` with no argument. Consumers must: nothing; passing a built registry is unchanged.
+
+### Docs
+- A render sanitize-floor reference (`docs/render-sanitize-floor.md`) states what the floor keeps,
+  strips, and rewrites, including the `target="_blank"` rel policy.
+- An upgrade guide (`docs/upgrading.md`) collects the `0.x` renames with a consumer action each.
+
+## 0.24.0
+
+### Added
+- `headRow(title, icon?)` builds the icon-plus-heading component head, exported beside `cardShell` and
+  `iconSpan`.
+- A `createRenderer` `anchorRel` option sets the `rel` value forced on `target="_blank"` anchors
+  (default `'noopener noreferrer'`), or disables the injection when set to `false`.
+
+### Changed
+- A component's `defaultIconByRole` default now reaches the build through the declared `type: 'icon'`
+  attribute (`ctx.attributes`), so a role default no longer needs a hardcoded fallback in the build. A
+  component using `defaultIconByRole` must declare a `type: 'icon'` attribute.
+- The engine drops an unclaimed directive `[label]` when a component has no `title` slot, so a stray
+  `[]` no longer renders an empty paragraph.
+
+### Removed
+- The internal `data-icon` marker, which no build read. The resolved icon now travels on the declared
+  attribute path.
+
+## 0.23.0
+
+### Changed (breaking)
+- A `date` field now validates a real `YYYY-MM-DD` calendar date. A site adopting this version whose
+  committed content holds a malformed or impossible date will see it fail validation, which is the loud
+  failure this restores.
+- A `tags` field now enforces its declared `options` as a closed vocabulary. A committed value outside
+  the list fails validation. Use a `freetags` field for free-form tags.
+- `normalizeConcepts` now throws when a `summaryFields` key names no declared field, so a typo fails at
+  config load instead of silently producing an empty list card.
+
+### Changed
+- `AttributeField.options` is now `readonly string[]`, so a site can share one frozen `as const`
+  vocabulary across components. Read-only by use, so no call site changes.
+
+## 0.22.0
+
+### Added
+- `ContentSummary.concept` and `EntryData.concept`: the read model carries its resolved concept id, so a
+  list or page branches per concept without re-deriving it from `entry.date`.
+- A `summaryFields` knob on a concept config surfaces named frontmatter keys on `ContentSummary.fields`,
+  so a list card reads an authored field with no per-entry detail read.
+- The package root re-exports the delivery route loaders (`createPublicRoutes`) and the response helpers
+  (`rssResponse`, `jsonFeedResponse`, `sitemapResponse`, `robotsResponse`).
+
+### Changed (breaking)
+- `CairnHead` moved off the `@glw907/cairn-cms/delivery` barrel to its own `@glw907/cairn-cms/delivery/head`
+  entry, so a node-environment data import from `/delivery` stays component-free. Update the import:
+  `import { CairnHead } from '@glw907/cairn-cms/delivery/head'`.

package/README.md

@@ -1,32 +1,33 @@
 # cairn-cms
 
 An embedded, **magic-link**, GitHub-committing CMS for SvelteKit + Cloudflare sites.
-Non-technical authors log in by email (no GitHub account, no password), edit **raw
-markdown** in a [Carta](https://github.com/BearToCode/carta) editor, and save. Each save
-commits to `main` via a **GitHub App** (committer = `cairn-cms[bot]`, author = the editor)
-and auto-deploys.
+Non-technical authors log in by email (no GitHub account, no password), edit **raw markdown**
+in a client-only CodeMirror editor with a live preview, and save. Each save commits to `main`
+via a **GitHub App** (committer = `cairn-cms[bot]`, author = the editor) and auto-deploys.
 
-It is **design-agnostic**: each consumer site supplies an adapter (collections, slug
-convention, frontmatter schema, and its own `renderPreview(md)`), so the same engine drives
-sites with completely different markdown pipelines (e.g. [ecnordic.ski](https://ecnordic.ski)
-(remark→rehype directive pipeline) and [907.life](https://907.life) (plain `remark-html`)).
+It is **design-agnostic**. Each consumer site supplies an adapter (the content contract through
+`defineAdapter`/`defineFields`, the slug and permalink rules, and its render configuration), so the
+same engine drives sites with completely different markdown pipelines. Two run in production today:
+[ecnordic.ski](https://ecnordic.ski) (a remark-to-rehype directive pipeline) and
+[907.life](https://907.life) (the engine's own `createRenderer`). Content is a fixed set of
+first-class concepts (Posts and Pages), not open-ended collections.
 
 ## Status
 
-**`0.4.x`: auth on [better-auth](https://better-auth.com); API not yet frozen.** The core was
-built *inside ecnordic.ski first* (the richer proving ground) with the cairn-core ↔ site-adapter
-seams designed in from day one, then extracted into this package and validated on a second design
-(907.life). Editor auth runs on **better-auth (Cloudflare D1 + magic-link)** behind a scanner-safe
-**POST-confirm** flow, with two-tier `owner`/`editor` roles; the GitHub-App commit signer stays
-bespoke. The GitHub commit path, Carta preview, the adapter contract, and the shared admin shell
-(`/sveltekit` server logic + `/components` Svelte UI + `/auth`) all run on both sites. Pin a caret
-range and expect 0.x churn.
-
-> **Breaking in `0.4.0`** (from `0.3.x`): editor auth moved off the hand-rolled magic-link/KV/
-> signed-cookie stack onto better-auth. Each site now needs a **D1 binding** (`AUTH_DB`) +
-> committed migrations, an `AUTH_SECRET`, a `/api/auth/[...all]` catch-all + `/admin/auth/confirm`
-> shims, and the new `better-auth` + `drizzle-orm` peer deps. Magic links are now POST-confirm
-> (a confirm page, not a GET link).
+cairn-cms runs two production sites today, [ecnordic.ski](https://ecnordic.ski) and
+[907.life](https://907.life). It is `0.x` and breaks between minor versions. The author is
+still working through the core-feature roadmap, and the project stays closely held until that
+core lands. See the [ROADMAP](./ROADMAP.md) for what is planned and the
+[CHANGELOG](./CHANGELOG.md) for what changed.
+
+Editor auth is self-owned: an atomic single-use magic-link token, a POST-confirm flow, opaque
+D1-backed session rows, and two-tier `owner`/`editor` roles. There is no better-auth, Drizzle,
+or ORM. Pin a caret range and read the CHANGELOG before bumping; every breaking entry carries a
+"Consumers must" line.
+
+A contributor who feels inspired is welcome to open an issue or a discussion to start a
+conversation. There is no formal contribution process yet, so this is not an open call for
+pull requests.
 
 ## Install
 
@@ -34,23 +35,35 @@ range and expect 0.x churn.
 npm install @glw907/cairn-cms
 ```
 
-Peers: `svelte@^5`, `@sveltejs/kit@^2`, and `carta-md@^4.11` (the editor component). Each site
-implements a `CairnAdapter` (see `docs/PLAN.md`) and mounts thin `/admin` route shims around
-`@glw907/cairn-cms/sveltekit` (server logic) and `@glw907/cairn-cms/components` (the admin UI).
+Peer dependencies: `svelte@^5` and `@sveltejs/kit@^2`. A consumer site implements a `CairnAdapter`
+and mounts thin `/admin` route shims around the package subpaths:
 
-## How it's developed
+- `@glw907/cairn-cms`: the core engine and adapter contract.
+- `@glw907/cairn-cms/sveltekit`: the server load and action logic.
+- `@glw907/cairn-cms/components`: the admin Svelte UI.
+- `@glw907/cairn-cms/delivery` and `/delivery/data`: the public read model (indexes, feeds,
+  sitemap, SEO head). The `/delivery/data` barrel is node-safe, with no `@sveltejs/kit` in its graph.
+- `@glw907/cairn-cms/vite`: the `cairnManifest()` Vite plugin, paired with the `cairn-manifest` bin,
+  that builds and verifies the committed content manifest at build time.
 
-This repo lives in a dev meta-workspace alongside its consumer sites:
+Each site binds a Cloudflare D1 database as `AUTH_DB` (the editor allowlist, sessions, and single-use
+magic tokens) and a `[[send_email]]` binding named `EMAIL`. The worked reference for every shape is
+`examples/showcase`.
 
-```
-~/Projects/cairn/                 # npm workspace root (not a git repo)
-  cairn-cms/        ← this repo
-  ecnordic-ski/     ← consumer (first proving ground)
-  907-life/         ← consumer (second design, validates the abstraction)
-```
+## Documentation
+
+The [`docs/`](./docs/README.md) tree is organized in four arms: a tutorial that builds a first
+site end to end, how-to guides for each setup task, a reference for every package export, and
+explanation pages for the architecture and design rules. Start at the
+[documentation index](./docs/README.md). The [security policy](./SECURITY.md) covers reporting
+and the security posture.
+
+## How it's developed
 
-npm workspaces symlink `cairn-cms` into each site's `node_modules` for zero-publish local
-dev. In CI, each site pins a published version so deploys stay reproducible.
+This is a standalone repo. Consumer sites install the published package from the npm registry by
+version range. The library's own development proves changes against `examples/showcase`, a
+self-contained SvelteKit site that consumes the package through the relative `file:../..` path, so a
+change is exercised end to end before it publishes.
 
-See **`docs/PLAN.md`** for the full architecture, locked decisions, phased passes, and
-risk register.
+The historical rebuild plan and the early architecture writeups live under `docs/internal/`.
+They are kept for history and are not current.

package/dist/auth/crypto.d.ts

@@ -16,4 +16,3 @@ export declare function generateToken(): string;
 export declare function generateSessionId(): string;
 /** The lowercase hex SHA-256 of a token, for storage and lookup. */
 export declare function hashToken(token: string): Promise<string>;
-//# sourceMappingURL=crypto.d.ts.map

package/dist/auth/store.d.ts

@@ -40,4 +40,3 @@ export declare function setEditorRole(db: D1Database, email: string, role: Role)
  * `removeOwnerIfNotLast`). Returns false (and writes nothing) when this is the last owner.
  */
 export declare function demoteOwnerIfNotLast(db: D1Database, email: string): Promise<boolean>;
-//# sourceMappingURL=store.d.ts.map

package/dist/auth/types.d.ts

@@ -22,4 +22,3 @@ export interface AuthEnv {
         }): Promise<void>;
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/components/AdminLayout.svelte.d.ts

@@ -16,4 +16,3 @@ interface Props {
 declare const AdminLayout: import("svelte").Component<Props, {}, "">;
 type AdminLayout = ReturnType<typeof AdminLayout>;
 export default AdminLayout;
-//# sourceMappingURL=AdminLayout.svelte.d.ts.map

package/dist/components/ComponentForm.svelte.d.ts

@@ -17,4 +17,3 @@ interface Props {
 declare const ComponentForm: import("svelte").Component<Props, {}, "">;
 type ComponentForm = ReturnType<typeof ComponentForm>;
 export default ComponentForm;
-//# sourceMappingURL=ComponentForm.svelte.d.ts.map

package/dist/components/ComponentInsertDialog.svelte.d.ts

@@ -17,4 +17,3 @@ interface Props {
 declare const ComponentInsertDialog: import("svelte").Component<Props, {}, "">;
 type ComponentInsertDialog = ReturnType<typeof ComponentInsertDialog>;
 export default ComponentInsertDialog;
-//# sourceMappingURL=ComponentInsertDialog.svelte.d.ts.map

package/dist/components/ConceptList.svelte.d.ts

@@ -10,4 +10,3 @@ interface Props {
 declare const ConceptList: import("svelte").Component<Props, {}, "">;
 type ConceptList = ReturnType<typeof ConceptList>;
 export default ConceptList;
-//# sourceMappingURL=ConceptList.svelte.d.ts.map

package/dist/components/ConfirmPage.svelte.d.ts

@@ -14,4 +14,3 @@ interface Props {
 declare const ConfirmPage: import("svelte").Component<Props, {}, "">;
 type ConfirmPage = ReturnType<typeof ConfirmPage>;
 export default ConfirmPage;
-//# sourceMappingURL=ConfirmPage.svelte.d.ts.map

package/dist/components/DeleteDialog.svelte.d.ts

@@ -18,4 +18,3 @@ interface Props {
 declare const DeleteDialog: import("svelte").Component<Props, {}, "">;
 type DeleteDialog = ReturnType<typeof DeleteDialog>;
 export default DeleteDialog;
-//# sourceMappingURL=DeleteDialog.svelte.d.ts.map

package/dist/components/EditPage.svelte.d.ts

@@ -33,4 +33,3 @@ interface Props {
 declare const EditPage: import("svelte").Component<Props, {}, "">;
 type EditPage = ReturnType<typeof EditPage>;
 export default EditPage;
-//# sourceMappingURL=EditPage.svelte.d.ts.map

package/dist/components/EditorToolbar.svelte.d.ts

@@ -12,4 +12,3 @@ interface Props {
 declare const EditorToolbar: import("svelte").Component<Props, {}, "">;
 type EditorToolbar = ReturnType<typeof EditorToolbar>;
 export default EditorToolbar;
-//# sourceMappingURL=EditorToolbar.svelte.d.ts.map

package/dist/components/IconPicker.svelte.d.ts

@@ -21,4 +21,3 @@ interface Props {
 declare const IconPicker: import("svelte").Component<Props, {}, "">;
 type IconPicker = ReturnType<typeof IconPicker>;
 export default IconPicker;
-//# sourceMappingURL=IconPicker.svelte.d.ts.map

package/dist/components/LinkPicker.svelte.d.ts

@@ -15,4 +15,3 @@ interface Props {
 declare const LinkPicker: import("svelte").Component<Props, {}, "">;
 type LinkPicker = ReturnType<typeof LinkPicker>;
 export default LinkPicker;
-//# sourceMappingURL=LinkPicker.svelte.d.ts.map

package/dist/components/LoginPage.svelte.d.ts

@@ -18,4 +18,3 @@ interface Props {
 declare const LoginPage: import("svelte").Component<Props, {}, "">;
 type LoginPage = ReturnType<typeof LoginPage>;
 export default LoginPage;
-//# sourceMappingURL=LoginPage.svelte.d.ts.map

package/dist/components/ManageEditors.svelte.d.ts

@@ -20,4 +20,3 @@ interface Props {
 declare const ManageEditors: import("svelte").Component<Props, {}, "">;
 type ManageEditors = ReturnType<typeof ManageEditors>;
 export default ManageEditors;
-//# sourceMappingURL=ManageEditors.svelte.d.ts.map

package/dist/components/MarkdownEditor.svelte.d.ts

@@ -21,4 +21,3 @@ interface Props {
 declare const MarkdownEditor: import("svelte").Component<Props, {}, "value">;
 type MarkdownEditor = ReturnType<typeof MarkdownEditor>;
 export default MarkdownEditor;
-//# sourceMappingURL=MarkdownEditor.svelte.d.ts.map

package/dist/components/NavTree.svelte.d.ts

@@ -14,4 +14,3 @@ interface Props {
 declare const NavTree: import("svelte").Component<Props, {}, "">;
 type NavTree = ReturnType<typeof NavTree>;
 export default NavTree;
-//# sourceMappingURL=NavTree.svelte.d.ts.map

package/dist/components/RenameDialog.svelte.d.ts

@@ -17,4 +17,3 @@ interface Props {
 declare const RenameDialog: import("svelte").Component<Props, {}, "">;
 type RenameDialog = ReturnType<typeof RenameDialog>;
 export default RenameDialog;
-//# sourceMappingURL=RenameDialog.svelte.d.ts.map

package/dist/components/index.d.ts

@@ -12,4 +12,3 @@ export { default as NavTree } from './NavTree.svelte';
 export { default as LinkPicker } from './LinkPicker.svelte';
 export { default as DeleteDialog } from './DeleteDialog.svelte';
 export { default as RenameDialog } from './RenameDialog.svelte';
-//# sourceMappingURL=index.d.ts.map

package/dist/components/link-completion.d.ts

@@ -13,4 +13,3 @@ export declare function linkCompletions(targets: LinkTarget[], query: string): C
  *  whole `[[query` with the chosen link, and sets filter:false because linkCompletions already
  *  filtered by the query (CodeMirror would otherwise re-filter against the literal `[[query`). */
 export declare function cairnLinkCompletionSource(targets: LinkTarget[]): CompletionSource;
-//# sourceMappingURL=link-completion.d.ts.map

package/dist/components/markdown-format.d.ts

@@ -30,4 +30,3 @@ export declare function unwrapCairnLink(doc: string, href: string): string;
  * last to first, replacing only the `](oldHref` run so the label and title stay exact.
  */
 export declare function rewriteCairnLink(doc: string, oldHref: string, newHref: string): string;
-//# sourceMappingURL=markdown-format.d.ts.map

package/dist/content/adapter.d.ts

@@ -1,4 +1,3 @@
 import type { CairnAdapter } from './types.js';
 /** Declare a site's adapter while preserving each concept's concrete schema type for typed reads. */
 export declare function defineAdapter<const A extends CairnAdapter>(adapter: A): A;
-//# sourceMappingURL=adapter.d.ts.map

package/dist/content/compose.d.ts

@@ -1,7 +1,17 @@
-import type { CairnAdapter, CairnExtension, CairnRuntime, ConceptUrlPolicy } from './types.js';
+import type { CairnAdapter, CairnExtension, CairnRuntime } from './types.js';
+import type { SiteConfig } from '../nav/site-config.js';
+/** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
+ *  always derived from one source and can never be silently dropped. `extensions` fold in after the
+ *  adapter's concepts. */
+export interface ComposeInput {
+    adapter: CairnAdapter;
+    siteConfig: SiteConfig;
+    extensions?: CairnExtension[];
+}
 /**
- * Fold an adapter and any extensions into the composed runtime (seam 2). Extension concepts
- * merge after the adapter's. The asset slot (seam 4) passes through untouched.
+ * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
+ * is derived from the site config, the same source the delivery path uses, so the runtime and
+ * delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The asset slot
+ * (seam 4) passes through untouched.
  */
-export declare function composeRuntime(adapter: CairnAdapter, extensions?: CairnExtension[], urlPolicy?: Record<string, ConceptUrlPolicy | undefined>): CairnRuntime;
-//# sourceMappingURL=compose.d.ts.map
+export declare function composeRuntime({ adapter, siteConfig, extensions }: ComposeInput): CairnRuntime;

package/dist/content/compose.js

@@ -1,9 +1,13 @@
-import { normalizeConcepts } from './concepts.js';
+import { resolveConcepts } from './concepts.js';
 /**
- * Fold an adapter and any extensions into the composed runtime (seam 2). Extension concepts
- * merge after the adapter's. The asset slot (seam 4) passes through untouched.
+ * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
+ * is derived from the site config, the same source the delivery path uses, so the runtime and
+ * delivery permalinks cannot diverge. Extension concepts merge after the adapter's. The asset slot
+ * (seam 4) passes through untouched.
  */
-export function composeRuntime(adapter, extensions = [], urlPolicy = {}) {
+export function composeRuntime({ adapter, siteConfig, extensions = [] }) {
+    if (!siteConfig)
+        throw new Error('composeRuntime needs a site config to derive the URL policy');
     const content = { ...adapter.content };
     const adminPanels = [];
     const fieldTypes = [];
@@ -19,7 +23,7 @@ export function composeRuntime(adapter, extensions = [], urlPolicy = {}) {
     }
     return {
         siteName: adapter.siteName,
-        concepts: normalizeConcepts(content, urlPolicy),
+        concepts: resolveConcepts(content, siteConfig),
         backend: adapter.backend,
         sender: adapter.sender,
         render: adapter.render,

package/dist/content/concepts.d.ts

@@ -1,4 +1,5 @@
 import type { ConceptConfig, ConceptDescriptor, ConceptUrlPolicy, RoutingRule } from './types.js';
+import { type SiteConfig } from '../nav/site-config.js';
 /**
  * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
  * pages are plain navigable structure. Not in adapter config. A future Fragments adds one
@@ -13,6 +14,11 @@ export declare const CONCEPT_ROUTING: Readonly<Record<string, RoutingRule>>;
  * a new concept attaches additively; production passes the default `CONCEPT_ROUTING`.
  */
 export declare function normalizeConcepts(content: Record<string, ConceptConfig | undefined>, urlPolicy?: Record<string, ConceptUrlPolicy | undefined>, routing?: Readonly<Record<string, RoutingRule>>): ConceptDescriptor[];
+/**
+ * Resolve a site's concept descriptors from its content map and parsed site config. The admin runtime
+ * (composeRuntime) and the delivery layer (siteDescriptors) both call this, so the per-concept URL
+ * policy is derived once from the YAML and the runtime and delivery permalinks cannot diverge.
+ */
+export declare function resolveConcepts(content: Record<string, ConceptConfig | undefined>, siteConfig: SiteConfig): ConceptDescriptor[];
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */
 export declare function findConcept(concepts: ConceptDescriptor[], id: string): ConceptDescriptor | undefined;
-//# sourceMappingURL=concepts.d.ts.map

package/dist/content/concepts.js

@@ -1,3 +1,4 @@
+import { urlPolicyFrom } from '../nav/site-config.js';
 /**
  * Concept-fixed routing, keyed by concept id (spec §7.2). Posts are dated feed entries;
  * pages are plain navigable structure. Not in adapter config. A future Fragments adds one
@@ -17,6 +18,37 @@ function defaultLabel(id) {
 function defaultPermalink(id) {
     return id === 'pages' ? '/:slug' : `/${id}/:slug`;
 }
+/** Permalink tokens the resolver understands. */
+const KNOWN_TOKENS = new Set(['slug', 'year', 'month', 'day']);
+/** The date-bearing tokens; valid only for a dated concept. */
+const DATE_TOKENS = new Set(['year', 'month', 'day']);
+/** The valid date-prefix granularities. A runtime check, since the YAML is untyped. */
+const DATE_PREFIXES = new Set(['year', 'month', 'day']);
+/**
+ * Validate one concept's URL policy at build, so a misconfigured permalink or datePrefix fails loudly
+ * here rather than emitting a wrong or defaulted URL at render. The permalink must be root-relative and
+ * use only known tokens, a date token requires a dated concept, and the datePrefix must be in range.
+ */
+function validateUrlPolicy(id, policy, dated) {
+    if (policy.permalink !== undefined) {
+        const pattern = policy.permalink;
+        if (!pattern.startsWith('/')) {
+            throw new Error(`cairn: concept "${id}" permalink "${pattern}" must start with "/"`);
+        }
+        for (const match of pattern.matchAll(/:(\w+)/g)) {
+            const token = match[1];
+            if (!KNOWN_TOKENS.has(token)) {
+                throw new Error(`cairn: concept "${id}" permalink "${pattern}" uses unknown token ":${token}"`);
+            }
+            if (DATE_TOKENS.has(token) && !dated) {
+                throw new Error(`cairn: concept "${id}" is not dated, so permalink "${pattern}" cannot use the date token ":${token}"`);
+            }
+        }
+    }
+    if (policy.datePrefix !== undefined && !DATE_PREFIXES.has(policy.datePrefix)) {
+        throw new Error(`cairn: concept "${id}" datePrefix "${policy.datePrefix}" must be one of year, month, day`);
+    }
+}
 /**
  * Normalize an adapter's declared concepts into uniform descriptors (seam 1). URL policy
  * (`permalink`, `datePrefix`) comes from the YAML site-config, passed here as `urlPolicy` keyed by
@@ -26,6 +58,12 @@ function defaultPermalink(id) {
  */
 export function normalizeConcepts(content, urlPolicy = {}, routing = CONCEPT_ROUTING) {
     const descriptors = [];
+    const declaredConcepts = new Set(Object.keys(content).filter((key) => content[key] !== undefined));
+    for (const key of Object.keys(urlPolicy)) {
+        if (!declaredConcepts.has(key)) {
+            throw new Error(`cairn: URL policy names concept "${key}", which is not declared under content`);
+        }
+    }
     for (const [id, config] of Object.entries(content)) {
         if (!config)
             continue;
@@ -35,12 +73,14 @@ export function normalizeConcepts(content, urlPolicy = {}, routing = CONCEPT_ROU
         if (undeclared !== undefined) {
             throw new Error(`cairn: concept "${id}" summaryFields key "${undeclared}" is not a declared field`);
         }
+        const conceptRouting = routing[id] ?? DEFAULT_ROUTING;
         const policy = urlPolicy[id] ?? {};
+        validateUrlPolicy(id, policy, conceptRouting.dated);
         descriptors.push({
             id,
             label: config.label ?? defaultLabel(id),
             dir: config.dir,
-            routing: routing[id] ?? DEFAULT_ROUTING,
+            routing: conceptRouting,
             permalink: policy.permalink ?? defaultPermalink(id),
             datePrefix: policy.datePrefix ?? 'day',
             fields: config.schema.fields,
@@ -50,6 +90,14 @@ export function normalizeConcepts(content, urlPolicy = {}, routing = CONCEPT_ROU
     }
     return descriptors;
 }
+/**
+ * Resolve a site's concept descriptors from its content map and parsed site config. The admin runtime
+ * (composeRuntime) and the delivery layer (siteDescriptors) both call this, so the per-concept URL
+ * policy is derived once from the YAML and the runtime and delivery permalinks cannot diverge.
+ */
+export function resolveConcepts(content, siteConfig) {
+    return normalizeConcepts(content, urlPolicyFrom(siteConfig));
+}
 /** Look up a normalized concept by id, or undefined when the site does not enable it. */
 export function findConcept(concepts, id) {
     return concepts.find((concept) => concept.id === id);

package/dist/content/frontmatter.d.ts

@@ -23,4 +23,3 @@ export declare function parseMarkdown(source: string): {
     frontmatter: Record<string, unknown>;
     body: string;
 };
-//# sourceMappingURL=frontmatter.d.ts.map

package/dist/content/identity.d.ts

@@ -0,0 +1,23 @@
+import type { ConceptDescriptor } from './types.js';
+/** A content entry's resolved URL identity. */
+export interface EntryIdentity {
+    id: string;
+    slug: string;
+    date?: string;
+    permalink: string;
+}
+/** A present, non-empty string, else undefined. The read-model string coercion. */
+export declare function asString(value: unknown): string | undefined;
+/** A YYYY-MM-DD date. An unquoted YAML date parses as a JS Date; a string is sliced to its date head. */
+export declare function asDate(value: unknown): string | undefined;
+/** Tags as an array, empty when the file declares none. */
+export declare function asTags(value: unknown): string[];
+/** A content entry's id: its filename stem (the date prefix is part of a dated id). */
+export declare function entryId(path: string): string;
+/**
+ * Resolve a content entry's URL identity from its concept descriptor, its file path, and its parsed
+ * frontmatter. The slug strips the leading date prefix for a dated concept and is the id verbatim for
+ * an undated one. The permalink is the one resolver every reader shares. The caller parses the markdown
+ * once and passes the frontmatter, so there is no second parse here.
+ */
+export declare function entryIdentity(descriptor: ConceptDescriptor, path: string, frontmatter: Record<string, unknown>): EntryIdentity;

package/dist/content/identity.js

@@ -0,0 +1,43 @@
+// cairn-cms: a content entry's URL identity in one place (engine-hardening pass 3). The id, the
+// slug, the date, and the permalink are computed here, so the content index and the manifest cannot
+// drift on what an entry's URL is. A cairn: link resolves through the manifest in the admin preview
+// and through the content index in the public build, so the two must agree by construction.
+import { idFromFilename, slugFromId } from './ids.js';
+import { permalink } from './permalink.js';
+/** The basename of a glob path: the segment after the last slash, or the whole path. */
+function basename(path) {
+    const slash = path.lastIndexOf('/');
+    return slash >= 0 ? path.slice(slash + 1) : path;
+}
+/** A present, non-empty string, else undefined. The read-model string coercion. */
+export function asString(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+/** A YYYY-MM-DD date. An unquoted YAML date parses as a JS Date; a string is sliced to its date head. */
+export function asDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+    if (typeof value === 'string')
+        return value.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+    return undefined;
+}
+/** Tags as an array, empty when the file declares none. */
+export function asTags(value) {
+    return Array.isArray(value) ? value.map(String) : [];
+}
+/** A content entry's id: its filename stem (the date prefix is part of a dated id). */
+export function entryId(path) {
+    return idFromFilename(basename(path));
+}
+/**
+ * Resolve a content entry's URL identity from its concept descriptor, its file path, and its parsed
+ * frontmatter. The slug strips the leading date prefix for a dated concept and is the id verbatim for
+ * an undated one. The permalink is the one resolver every reader shares. The caller parses the markdown
+ * once and passes the frontmatter, so there is no second parse here.
+ */
+export function entryIdentity(descriptor, path, frontmatter) {
+    const id = entryId(path);
+    const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
+    const date = asDate(frontmatter.date);
+    return { id, slug, date, permalink: permalink(descriptor, { id, slug, date }) };
+}

package/dist/content/ids.d.ts

@@ -35,4 +35,3 @@ export declare function composeDatedId(date: string, slug: string, datePrefix: D
  * newSlug. The caller validates newSlug with isValidId first.
  */
 export declare function renameId(oldId: string, newSlug: string, datePrefix: DatePrefix | null): string;
-//# sourceMappingURL=ids.d.ts.map