feat(m1.1): enforce canonical slug and content identity policy

Author: flyingrobots

README.md

@@ -43,7 +43,7 @@ npm run dev
 
 The tests create, destroy, and manipulate Git repositories. Running low-level plumbing commands on your host filesystem is risky - a typo could affect your local Git setup. That's why we built Docker isolation into everything.
 
-**Read more:** [TESTING_GUIDE.md](./TESTING_GUIDE.md) | [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md)
+**Read more:** [TESTING_GUIDE.md](./TESTING_GUIDE.md) | [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md) | [docs/CONTENT_ID_POLICY.md](./docs/CONTENT_ID_POLICY.md)
 
 ## Features
 

bin/git-cms.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import CmsService from '../src/lib/CmsService.js';
+import { canonicalizeSlug } from '../src/lib/ContentIdentityPolicy.js';
 
 async function main() {
   const [,, cmd, ...args] = process.argv;
@@ -12,8 +13,9 @@ async function main() {
   try {
     switch (cmd) {
       case 'draft': {
-        const [slug, title] = args;
-        if (!slug || !title) throw new Error('Usage: git cms draft <slug> "Title" < content.md');
+        const [rawSlug, title] = args;
+        if (!rawSlug || !title) throw new Error('Usage: git cms draft <slug> "Title" < content.md');
+        const slug = canonicalizeSlug(rawSlug);
 
         const chunks = [];
         for await (const chunk of process.stdin) chunks.push(chunk);
@@ -24,8 +26,9 @@ async function main() {
         break;
       }
       case 'publish': {
-        const [slug] = args;
-        if (!slug) throw new Error('Usage: git cms publish <slug>');
+        const [rawSlug] = args;
+        if (!rawSlug) throw new Error('Usage: git cms publish <slug>');
+        const slug = canonicalizeSlug(rawSlug);
 
         const res = await cms.publishArticle({ slug });
         console.log(`Published: ${res.sha} (${res.ref})`);
@@ -38,8 +41,9 @@ async function main() {
         break;
       }
       case 'show': {
-        const [slug] = args;
-        if (!slug) throw new Error('Usage: git cms show <slug>');
+        const [rawSlug] = args;
+        if (!rawSlug) throw new Error('Usage: git cms show <slug>');
+        const slug = canonicalizeSlug(rawSlug);
         const article = await cms.readArticle({ slug });
         console.log(`# ${article.title}\n\n${article.body}`);
         break;

docs/CONTENT_ID_POLICY.md

@@ -0,0 +1,83 @@
+# Content Identity Policy (v1.0.0)
+
+Status: Active  
+Effective Date: 2026-02-11  
+Applies To: CLI, HTTP API, `CmsService`
+
+## 1. Purpose
+
+Define one canonical contract for content identity so every ingress path behaves the same.
+
+In v1, `contentId` is slug-backed:
+
+- Canonical `contentId` = canonical `slug`
+- `contentId` is immutable for a given slug lineage
+
+## 2. Canonical Slug Rules
+
+A slug is canonicalized with:
+
+1. Unicode normalization: `NFKC`
+2. Trim surrounding whitespace
+3. Lowercase
+
+After canonicalization, it must satisfy:
+
+- Length: `1..64`
+- Pattern: `^[a-z0-9]+(?:-[a-z0-9]+)*$`
+- Reserved values forbidden
+
+Reserved slugs:
+
+- `.`, `..`
+- `admin`, `api`, `assets`, `chunks`
+- `draft`, `new`, `published`
+- `refs`, `root`
+
+## 3. Kind Rules
+
+Allowed content kinds:
+
+- `articles`
+- `published`
+- `comments`
+
+Any other kind is rejected.
+
+## 4. Collision Policy
+
+Because slugs are canonicalized before use, values that normalize to the same slug are the same identity.
+
+Examples:
+
+- `Hello-World` -> `hello-world`
+- ` hello-world ` -> `hello-world`
+
+Both target the same refs and same logical content lineage.
+
+## 5. contentId Semantics
+
+During snapshot save:
+
+- If no `trailers.contentId`/`trailers.contentid` is provided, system writes canonical slug as trailer `contentid`.
+- If `trailers.contentId` or `trailers.contentid` is provided, it must canonicalize to the same value as `slug`.
+- Mismatches are rejected.
+
+## 6. Rename Semantics (v1)
+
+Explicit rename is not implemented as a first-class operation yet.
+
+Operationally in v1:
+
+- A new slug creates/targets a different identity.
+- Moving history between slugs is out of scope for this policy and will be addressed with state-machine work (`M1.2+`).
+
+## 7. Error Contract
+
+Validation failures return `CmsValidationError` with:
+
+- `error`: human-readable message
+- `code`: machine-friendly code (`slug_invalid_format`, `slug_reserved`, etc.)
+- `field`: offending field (`slug`, `contentId`, `kind`, ...)
+
+HTTP API maps validation failures to `400`.

src/lib/CmsService.js

@@ -4,6 +4,11 @@ import { createMessageHelpers } from '@git-stunts/trailer-codec';
 import ContentAddressableStore from '@git-stunts/git-cas';
 import VaultResolver from './VaultResolver.js';
 import ShellRunner from '@git-stunts/plumbing/ShellRunner';
+import {
+  canonicalizeKind,
+  canonicalizeSlug,
+  resolveContentIdentity,
+} from './ContentIdentityPolicy.js';
 
 /**
  * @typedef {Object} CmsServiceOptions
@@ -43,14 +48,17 @@ export default class CmsService {
    * @private
    */
   _refFor(slug, kind = 'articles') {
-    return `${this.refPrefix}/${kind}/${slug}`;
+    const canonicalSlug = canonicalizeSlug(slug);
+    const canonicalKind = canonicalizeKind(kind);
+    return `${this.refPrefix}/${canonicalKind}/${canonicalSlug}`;
   }
 
   /**
    * Lists all articles of a certain kind.
    */
   async listArticles({ kind = 'articles' } = {}) {
-    const ns = `${this.refPrefix}/${kind}/`;
+    const canonicalKind = canonicalizeKind(kind);
+    const ns = `${this.refPrefix}/${canonicalKind}/`;
     let out = '';
     try {
       out = await this.plumbing.execute({ args: ['for-each-ref', ns, '--format=%(refname) %(objectname)'] });
@@ -84,10 +92,17 @@ export default class CmsService {
    * Saves a new version (snapshot) of an article.
    */
   async saveSnapshot({ slug, title, body, trailers = {} }) {
-    const ref = this._refFor(slug, 'articles');
+    const safeTrailers = trailers && typeof trailers === 'object' ? trailers : {};
+    const identity = resolveContentIdentity({ slug, trailers: safeTrailers });
+    const ref = this._refFor(identity.slug, 'articles');
     const parentSha = await this.graph.readRef(ref);
 
-    const finalTrailers = { ...trailers, status: 'draft', updatedAt: new Date().toISOString() };
+    const finalTrailers = {
+      ...safeTrailers,
+      contentid: identity.contentId,
+      status: 'draft',
+      updatedAt: new Date().toISOString(),
+    };
     const message = this.codec.encode({ title, body, trailers: finalTrailers });
 
     const newSha = await this.graph.commitNode({
@@ -104,11 +119,12 @@ export default class CmsService {
    * Publishes an article by fast-forwarding the 'published' ref.
    */
   async publishArticle({ slug, sha }) {
-    const draftRef = this._refFor(slug, 'articles');
-    const pubRef = this._refFor(slug, 'published');
+    const canonicalSlug = canonicalizeSlug(slug);
+    const draftRef = this._refFor(canonicalSlug, 'articles');
+    const pubRef = this._refFor(canonicalSlug, 'published');
 
     const targetSha = sha || await this.graph.readRef(draftRef);
-    if (!targetSha) throw new Error(`Nothing to publish for ${slug}`);
+    if (!targetSha) throw new Error(`Nothing to publish for ${canonicalSlug}`);
 
     const oldSha = await this.graph.readRef(pubRef);
     await this.repo.updateRef({ ref: pubRef, newSha: targetSha, oldSha });
@@ -120,6 +136,7 @@ export default class CmsService {
    * Uploads an asset and returns its manifest and CAS info.
    */
   async uploadAsset({ slug, filePath, filename }) {
+    const canonicalSlug = canonicalizeSlug(slug);
     const ENV = (process.env.GIT_CMS_ENV || 'dev').toLowerCase();
     const encryptionKeyRaw = await this.vault.resolveSecret({
       envKey: 'CHUNK_ENC_KEY',
@@ -130,14 +147,14 @@ export default class CmsService {
 
     const manifest = await this.cas.storeFile({
       filePath,
-      slug,
+      slug: canonicalSlug,
       filename,
       encryptionKey
     });
 
     const treeOid = await this.cas.createTree({ manifest });
 
-    const ref = `refs/_blog/chunks/${slug}@current`;
+    const ref = `refs/_blog/chunks/${canonicalSlug}@current`;
     const commitSha = await this.graph.commitNode({
       message: `asset:${filename}\n\nmanifest: ${treeOid}`,
     });

src/lib/ContentIdentityPolicy.js

@@ -0,0 +1,109 @@
+/**
+ * Canonical content identity policy for git-cms.
+ *
+ * Content IDs are slug-backed in v1: the canonical slug is also the contentId.
+ */
+
+export class CmsValidationError extends Error {
+  constructor(message, { code = 'validation_error', field = 'input' } = {}) {
+    super(message);
+    this.name = 'CmsValidationError';
+    this.code = code;
+    this.field = field;
+  }
+}
+
+export const CONTENT_ID_POLICY_VERSION = '1.0.0';
+export const SLUG_MIN_LENGTH = 1;
+export const SLUG_MAX_LENGTH = 64;
+
+const SLUG_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RESERVED_SLUGS = new Set([
+  '.',
+  '..',
+  'admin',
+  'api',
+  'assets',
+  'chunks',
+  'draft',
+  'new',
+  'published',
+  'refs',
+  'root',
+]);
+
+const ALLOWED_KINDS = new Set(['articles', 'published', 'comments']);
+
+function asString(value, field) {
+  if (typeof value !== 'string') {
+    throw new CmsValidationError(`${field} must be a string`, {
+      code: 'invalid_type',
+      field,
+    });
+  }
+  return value;
+}
+
+export function canonicalizeSlug(input, { field = 'slug' } = {}) {
+  const value = asString(input, field).normalize('NFKC').trim().toLowerCase();
+
+  if (value.length < SLUG_MIN_LENGTH) {
+    throw new CmsValidationError(`${field} cannot be empty`, {
+      code: 'slug_empty',
+      field,
+    });
+  }
+
+  if (value.length > SLUG_MAX_LENGTH) {
+    throw new CmsValidationError(
+      `${field} must be ${SLUG_MAX_LENGTH} characters or fewer`,
+      { code: 'slug_too_long', field }
+    );
+  }
+
+  if (!SLUG_REGEX.test(value)) {
+    throw new CmsValidationError(
+      `${field} must match ${SLUG_REGEX} (lowercase letters, numbers, single hyphens)`,
+      { code: 'slug_invalid_format', field }
+    );
+  }
+
+  if (RESERVED_SLUGS.has(value)) {
+    throw new CmsValidationError(`${field} "${value}" is reserved`, {
+      code: 'slug_reserved',
+      field,
+    });
+  }
+
+  return value;
+}
+
+export function canonicalizeKind(input, { field = 'kind' } = {}) {
+  const value = asString(input, field).trim().toLowerCase();
+  if (!ALLOWED_KINDS.has(value)) {
+    throw new CmsValidationError(
+      `${field} must be one of: ${Array.from(ALLOWED_KINDS).join(', ')}`,
+      { code: 'kind_invalid', field }
+    );
+  }
+  return value;
+}
+
+export function resolveContentIdentity({ slug, trailers = {} }) {
+  const canonicalSlug = canonicalizeSlug(slug, { field: 'slug' });
+  const candidate = trailers?.contentId ?? trailers?.contentid;
+
+  if (candidate == null || candidate === '') {
+    return { slug: canonicalSlug, contentId: canonicalSlug };
+  }
+
+  const canonicalContentId = canonicalizeSlug(candidate, { field: 'contentId' });
+  if (canonicalContentId !== canonicalSlug) {
+    throw new CmsValidationError(
+      `contentId "${canonicalContentId}" must match canonical slug "${canonicalSlug}"`,
+      { code: 'content_id_mismatch', field: 'contentId' }
+    );
+  }
+
+  return { slug: canonicalSlug, contentId: canonicalContentId };
+}