canopycms 0.0.68-int.98 → 0.1.0

package/dist/config/validation.js

@@ -6,11 +6,15 @@
  * the same checks. Exported so the test suite can exercise them directly.
  */
 import { CanopyConfigSchema } from './schemas/config.js';
+import { mdxAllowlistSchema } from './schemas/field.js';
+import { isMarkdownField, markdownFieldOptionsError } from '../validation/mdx-allowlist.js';
 import { normalizePathValue } from './flatten.js';
 // Leaf module, NOT the `operating-mode` barrel: the barrel re-exports the
 // client-unsafe strategy (node:fs/node:path) and this file is reachable from
 // `canopycms/client` (the generated editor page imports the adopter's config).
 import { resolveOperatingMode } from '../operating-mode/mode-env.js';
+import { isPathFieldName } from '../editor/canopy-path.js';
+import { ITEM_KEY } from '../item-keys.js';
 /**
  * Recursively check that all select fields have options defined.
  * Throws an error if a select field is missing options.
@@ -37,6 +41,33 @@ export const ensureSelectFieldsHaveOptions = (fields) => {
         }
     }
 };
+/**
+ * Check that every data field's name can be spelled as a field path segment (`isPathFieldName`):
+ * the form, the preview's marks, validation errors and comment threads all name a field by its
+ * path. An inline group's own name is not part of any path, so only its children are checked.
+ * `ITEM_KEY` is reserved too, since every list item and block carries it.
+ */
+export const ensureFieldNamesSpellInPaths = (fields) => {
+    if (!Array.isArray(fields))
+        return;
+    for (const field of fields) {
+        const f = field;
+        if (f?.type !== 'group' && typeof f?.name === 'string' && !isPathFieldName(f.name)) {
+            throw new Error(`Field "${f.name}": field names can't be empty, all digits, or contain '.', '[' or ']'; they're used in field paths`);
+        }
+        if (f?.type !== 'group' && f?.name === ITEM_KEY) {
+            throw new Error(`Field "${ITEM_KEY}": the name is reserved for the key CanopyCMS gives each list item and block. Rename the field, and the key in your content files with it.`);
+        }
+        if (f?.type === 'group' || f?.type === 'object') {
+            ensureFieldNamesSpellInPaths(f.fields);
+        }
+        if (f?.type === 'block' && Array.isArray(f.templates)) {
+            for (const template of f.templates) {
+                ensureFieldNamesSpellInPaths(template.fields);
+            }
+        }
+    }
+};
 /**
  * Recursively check that all reference fields have at least one of `collections` or `entryTypes`.
  * Throws an error if a reference field has neither.
@@ -78,9 +109,11 @@ export const forEachReferenceField = (fields, visit) => {
     }
 };
 /**
- * Check that every `itemTitleField` sits on a `list: true` object and names a direct child
- * of type `string` or `number`, the only values the card heading shows as typed (a reference
- * would show its raw id, a select its stored value). Throws an error when it does not.
+ * Check that every `itemLabel` is non-blank text and, like every `itemTitleField`, sits on a
+ * `list: true` object, and that every `itemTitleField` names a direct child of type `string` or
+ * `number`, the only values the card heading shows as typed (a reference would show its raw id, a
+ * select its stored value). Throws an error when it does not. Entry schemas reach the editor
+ * through these checks, not the zod field schema.
  */
 export const ensureItemTitleFieldsExist = (fields) => {
     if (!Array.isArray(fields))
@@ -89,6 +122,15 @@ export const ensureItemTitleFieldsExist = (fields) => {
         const f = field;
         if (f?.type === 'object') {
             const children = Array.isArray(f.fields) ? f.fields : [];
+            if (f.itemLabel !== undefined) {
+                const label = `Object field "${f.name ?? 'unknown'}" has itemLabel`;
+                if (f.list !== true) {
+                    throw new Error(`${label}, but itemLabel applies only to list: true objects`);
+                }
+                if (typeof f.itemLabel !== 'string' || f.itemLabel.trim() === '') {
+                    throw new Error(`${label}, which must be non-blank text`);
+                }
+            }
             if (f.itemTitleField !== undefined) {
                 const label = `Object field "${f.name ?? 'unknown'}" has itemTitleField "${String(f.itemTitleField)}"`;
                 if (f.list !== true) {
@@ -210,6 +252,77 @@ export const ensureNoGroupsInsideComplexFields = (fields) => {
     };
     checkFields(Array.isArray(fields) ? fields : undefined);
 };
+/**
+ * Check that `stampOnPublish` sits only on an entry's own top-level `datetime` field (an inline
+ * group's members count, since groups carry no data) that is neither `list: true` nor
+ * `required: true`. The submit that stamps sets one top-level value, and a required field can
+ * never be saved empty, so it would never be stamped. Throws on the first problem.
+ */
+export const ensureStampOnPublishPlacement = (fields, scopeLabel = 'entry schema') => {
+    const refuse = (f, why) => {
+        throw new Error(`${scopeLabel}: field "${f.name ?? 'unknown'}" has stampOnPublish, ${why}`);
+    };
+    const check = (scopeFields, nestedIn) => {
+        if (!Array.isArray(scopeFields))
+            return;
+        for (const field of scopeFields) {
+            const f = field;
+            if (f?.stampOnPublish !== undefined && typeof f.stampOnPublish !== 'boolean') {
+                refuse(f, 'which must be true or false');
+            }
+            if (f?.stampOnPublish === true) {
+                if (nestedIn)
+                    refuse(f, `but it is inside ${nestedIn}; only a top-level field is stamped`);
+                if (f.type !== 'datetime')
+                    refuse(f, `but it is type "${String(f.type)}", not "datetime"`);
+                if (f.list === true)
+                    refuse(f, 'but it is list: true; only a single date is stamped');
+                if (f.required === true) {
+                    refuse(f, 'but it is required: true, so it can never be saved empty to be stamped');
+                }
+            }
+            if (f?.type === 'group')
+                check(f.fields, nestedIn);
+            if (f?.type === 'object')
+                check(f.fields, `object field "${String(f.name)}"`);
+            if (f?.type === 'block' && Array.isArray(f.templates)) {
+                for (const template of f.templates) {
+                    check(template.fields, `block field "${String(f.name)}"`);
+                }
+            }
+        }
+    };
+    check(fields, undefined);
+};
+/**
+ * Check every markdown and mdx field's `mdxAllow` against its schema and its `renderAs`,
+ * `mdxAllow` and `executable` against each other. Throws on the first problem.
+ */
+export const ensureMarkdownFieldOptions = (fields) => {
+    for (const field of fields) {
+        if (isMarkdownField(field)) {
+            if (field.mdxAllow !== undefined) {
+                const parsed = mdxAllowlistSchema.safeParse(field.mdxAllow);
+                if (!parsed.success) {
+                    const [first] = parsed.error.issues;
+                    const where = first?.path.join('.') ?? '';
+                    throw new Error(`Field "${field.name}": mdxAllow${where === '' ? '' : `.${where}`} ${first?.message ?? 'is invalid'}`);
+                }
+            }
+            const message = markdownFieldOptionsError(field);
+            if (message !== undefined)
+                throw new Error(message);
+        }
+        if (field.type === 'group' || field.type === 'object') {
+            if ('fields' in field && Array.isArray(field.fields))
+                ensureMarkdownFieldOptions(field.fields);
+        }
+        if (field.type === 'block' && 'templates' in field && Array.isArray(field.templates)) {
+            for (const template of field.templates)
+                ensureMarkdownFieldOptions(template.fields);
+        }
+    }
+};
 /**
  * Validate and normalize a CanopyConfig object.
  * Performs Zod validation and normalizes paths. Field-shape validation for

package/dist/content-id-index.js

@@ -165,8 +165,8 @@ export class ContentIdIndex {
                             `embed this ID. Keeping "${kept}" for ID-based lookups (reads, references, ` +
                             `listings); "${dropped}" is excluded from those lookups for now but has NOT ` +
                             `been deleted -- it is still on disk at that path, and saves addressed to it are ` +
-                            `refused until this is resolved. An admin can resolve this via ` +
-                            `the repair-content-duplicates admin action for this branch, which archives ` +
+                            `refused until this is resolved. An admin can resolve this in System health ` +
+                            `(Branches tab), whose repair-content-duplicates action archives ` +
                             `"${dropped}" with a dot-prefixed name so future scans stop flagging it. ` +
                             `Root: ${this.root}`);
                     }

package/dist/content-index-generation.d.ts

@@ -1,6 +1,6 @@
 /**
  * Absolute path of the generation marker for a branch-clone root.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export declare function contentIndexGenerationPath(root: string): string;
 /**

package/dist/content-index-generation.js

@@ -20,7 +20,7 @@ import { SCHEMA_GENERATION_RESOURCE } from './branch-schema-cache.js';
 const RESOURCE = 'content-index';
 /**
  * Absolute path of the generation marker for a branch-clone root.
- * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ * @internal No importer; deletion candidate in safeinsights/canopycms#725.
  */
 export function contentIndexGenerationPath(root) {
     return resourceGenerationPath(root, RESOURCE);

package/dist/content-listing.d.ts

@@ -152,6 +152,12 @@ export interface ListingReferenceResolver {
     cache: ReferenceResolveCache;
     access: ReferenceTargetAccess | undefined;
 }
+/**
+ * A collection's listed entries minus those of an `unavailable` entry type, for the listings
+ * adopter pages render: data whose shape the running code does not know renders wrong rather
+ * than failing. The editor's own listing keeps them, so it can say why they cannot be opened.
+ */
+export declare const withoutUnavailableEntries: (items: CollectionListItem[], collection: CollectionSchemaItem) => CollectionListItem[];
 /**
  * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
  *
@@ -203,5 +209,8 @@ export interface SkippedListingFile {
  * -- a `README.md`, a colocated sibling artifact -- is always dropped with a debug-gated
  * `log.warn` and never passed to `onSkip`. Optional and purely diagnostic: `listEntries` uses
  * it to turn the skip into a hard build-time failure instead of a silent one.
+ *
+ * `readsId`, when given, leaves out every entry whose ContentId it rejects before its file is
+ * read, so a caller wanting a few entries does not pay for the rest.
  */
-export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem, onSkip?: (file: SkippedListingFile) => void) => Promise<CollectionListItem[]>;
+export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem, onSkip?: (file: SkippedListingFile) => void, readsId?: (id: ContentId) => boolean) => Promise<CollectionListItem[]>;

package/dist/content-listing.js

@@ -14,6 +14,7 @@ import { isNotFoundError, getErrorMessage } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 import { ContentStore, ContentStoreError, createReferenceResolveCache, } from './content-store.js';
 import { isBuildMode } from './build-mode.js';
+import { withItemKeys } from './item-keys.js';
 const log = createDebugLogger({ prefix: 'ContentListing' });
 /** Validate and normalize `target` under `root`; throws ContentStoreError on a traversal. */
 const normalizePath = (root, target) => {
@@ -89,6 +90,15 @@ export const createReferenceResolver = (branchRoot, flatSchema, contentRootName,
     // row would have hidden.
     access: visibility?.shouldInclude,
 });
+/**
+ * A collection's listed entries minus those of an `unavailable` entry type, for the listings
+ * adopter pages render: data whose shape the running code does not know renders wrong rather
+ * than failing. The editor's own listing keeps them, so it can say why they cannot be opened.
+ */
+export const withoutUnavailableEntries = (items, collection) => {
+    const unavailable = new Set(collection.entries?.filter((e) => e.unavailable).map((e) => e.name) ?? []);
+    return unavailable.size > 0 ? items.filter((item) => !unavailable.has(item.entryType)) : items;
+};
 /**
  * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
  *
@@ -103,7 +113,7 @@ export const resolveCollectionItemReferences = async (items, collection, resolve
         return item;
     return {
         ...item,
-        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache, resolver.access),
+        data: await resolver.store.resolveReferences(item.data, fields, resolver.cache, resolver.access, item.logicalPath),
     };
 }));
 /**
@@ -142,7 +152,7 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
         ? createReferenceResolver(branchRoot, flatSchema, contentRootName, visibility)
         : null;
     const collectionResults = await Promise.all(collections.map(async (collection) => {
-        const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
+        const entries = withoutUnavailableEntries(await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file)), collection);
         const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
         // Resolve AFTER the visibility filter (a denied entry is never resolved, so its
         // references cost nothing and leak nothing) and BEFORE the mapping below, so
@@ -183,7 +193,7 @@ export async function listEntries(branchRoot, flatSchema, contentRootName, optio
             // One deliberate copy of the rule remains: `content-tree.ts`'s `defaultBuildPath`,
             // exported for adopters to extend and also handling the collection case
             // `computeEntryUrl` does not model. Folding it in is tracked in
-            // `.claude/future-tasks/default-build-path-url-rule-copy.md`.
+            // safeinsights/canopycms#646.
             const urlPath = computeEntryUrl(entry.collectionPath, entry.slug, contentRootName);
             const raw = entry.data;
             const meta = {
@@ -281,8 +291,11 @@ const looksLikeMalformedEntry = (filename, entryTypes) => {
  * -- a `README.md`, a colocated sibling artifact -- is always dropped with a debug-gated
  * `log.warn` and never passed to `onSkip`. Optional and purely diagnostic: `listEntries` uses
  * it to turn the skip into a hard build-time failure instead of a silent one.
+ *
+ * `readsId`, when given, leaves out every entry whose ContentId it rejects before its file is
+ * read, so a caller wanting a few entries does not pay for the rest.
  */
-export const listCollectionEntries = async (root, collection, onSkip) => {
+export const listCollectionEntries = async (root, collection, onSkip, readsId) => {
     if (collection.type !== 'collection' || !collection.entries) {
         return [];
     }
@@ -326,13 +339,17 @@ export const listCollectionEntries = async (root, collection, onSkip) => {
             return null;
         }
         const { type: entryTypeName, slug, id: contentId } = parsed;
+        if (readsId && !readsId(contentId))
+            return null;
         const entryType = entryTypes.find((e) => e.name === entryTypeName);
         const format = entryType?.format || 'json';
         const bodyField = entryType?.schema ? findBodyFieldName(entryType.schema) : 'body';
-        const [stats, data] = await Promise.all([
+        const [stats, rawData] = await Promise.all([
             fs.stat(absolutePath),
             readEntryData(absolutePath, format, bodyField),
         ]);
+        // Keyed as `ContentStore.read` keys it, so every reader names an item alike.
+        const data = withItemKeys(entryType?.schema ?? [], rawData, 'content');
         const item = {
             logicalPath: entryLogicalPath(collection.logicalPath, slug),
             contentId,

package/dist/content-reader.d.ts

@@ -84,10 +84,19 @@ export interface ContentReadMeta {
      * `{type}.{slug}.{id}.{ext}`) -- see the `entryType` caveat above for what that implies.
      */
     entryId?: ContentId;
+    /** The entry's slug within its collection, by the rule `listEntries` uses. */
+    slug: Slug;
+    /** The entry's URL path with no query, by the rule `listEntries` uses. */
+    urlPath: string;
 }
 export interface ContentReader {
     read: <T = unknown>(input: ReadContentInput, message?: string) => Promise<{
         data: T;
+        /**
+         * The requested `entryPath` and slug as a percent-encoded URL path, plus `?branch=<name>`.
+         * Through an entry-type `entryPath` it is not the entry's URL. Compare entries by
+         * `meta.urlPath`.
+         */
         path: string;
         meta: ContentReadMeta;
     }>;

package/dist/content-reader.js

@@ -1,11 +1,14 @@
 import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace.js';
+import { SchemaUnavailableError } from './schema/schema-unavailable-error.js';
 import { ContentStore, ContentStoreError } from './content-store.js';
 import { namesNoWorkspace, resolveBranchPaths, } from './paths/index.js';
 import { trimSlashes } from './paths/normalize.js';
-import { isIndexSlug } from './utils/entry-url.js';
+import { computeEntryUrl, isIndexSlug } from './utils/entry-url.js';
 import { isDeployedStatic, isBuildMode, readsFromCheckout } from './build-mode.js';
 import { isNotFoundError } from './utils/error.js';
 import { resolveEntryLinksInData } from './entry-link-resolver.js';
+import { baseBranchOf } from './utils/base-branch.js';
+import { CONTENT_READER_USER_ID } from './system-users.js';
 /**
  * Server-side helper to read content directly from a branch workspace. A branch with no workspace
  * reads as NOT_FOUND unless `allowCreateBranch` or a `getBranchContext` resolver says otherwise.
@@ -14,12 +17,9 @@ export const createContentReader = (options) => {
     const services = options.services;
     const operatingMode = services.config.mode;
     const basePathOverride = options.basePathOverride;
-    const defaultBranch = options.defaultBranch ??
-        services.config.defaultActiveBranch ??
-        services.config.defaultBaseBranch ??
-        'main';
+    const defaultBranch = options.defaultBranch ?? services.config.defaultActiveBranch ?? baseBranchOf(services.config);
     const allowCreateBranch = options.allowCreateBranch ?? false;
-    const createdBy = options.createdBy ?? 'canopycms-content-reader';
+    const createdBy = options.createdBy ?? CONTENT_READER_USER_ID;
     const resolveBranchContext = async (branchName) => {
         // Static deployments and builds read from the checkout: loadOrCreateBranchContext
         // returns a synthetic cwd context without git ops, regardless of allowCreateBranch
@@ -115,7 +115,7 @@ export const createContentReader = (options) => {
         // deliberately does not resolve the former, so a caller linking `path` linked to a 404.
         // Same index decision as computeEntryUrl/listEntries/buildPreviewSrc, through the same
         // predicate. NOTE this builder still keeps its own content-root strip and its own encoding
-        // rather than delegating wholesale -- see .claude/future-tasks/default-build-path-url-rule-copy.md.
+        // rather than delegating wholesale -- see safeinsights/canopycms#646.
         const encodedSlug = isIndexSlug(opts.slug) ? '' : encodeSlug(opts.slug);
         const url = encodedSlug ? `${trimmed}/${encodedSlug}` : trimmed || '/';
         return appendBranch(url);
@@ -141,6 +141,8 @@ export const createContentReader = (options) => {
         // key by them without a separate listEntries lookup or filename parse.
         let entryType;
         let entryId;
+        let urlPath;
+        let resolvedSlug;
         try {
             const resolved = await store.resolveDocumentPath(entryPath, slug ?? '');
             logicalPath = resolved.logicalPath;
@@ -150,6 +152,8 @@ export const createContentReader = (options) => {
             // absent, for legacy entry files without an embedded ID (see ContentReadMeta).
             entryType = resolved.entryTypeName;
             entryId = resolved.id;
+            resolvedSlug = resolved.slug;
+            urlPath = computeEntryUrl(resolved.collectionPath, resolved.slug, contentRoot);
         }
         catch (err) {
             const message = err instanceof ContentStoreError ? err.message : 'Invalid content request';
@@ -196,10 +200,11 @@ export const createContentReader = (options) => {
                 resolveReferences: input.resolveReferences ?? true,
                 referenceAccess,
             });
-            return { doc, store, physicalPath, entryType, entryId };
+            return { doc, store, physicalPath, entryType, entryId, slug: resolvedSlug, urlPath };
         }
         catch (err) {
-            if (isNotFoundError(err))
+            // An entry of an unavailable type reads as absent, as adopter listings leave it out.
+            if (isNotFoundError(err) || err instanceof SchemaUnavailableError)
                 return null;
             throw err;
         }
@@ -211,7 +216,7 @@ export const createContentReader = (options) => {
             const defaultMessage = `Content not found for ${entryPath}${slug ? `/${slug}` : ''} on branch ${branchName}`;
             throw new ContentStoreError(message ?? defaultMessage, 'NOT_FOUND');
         }
-        const { doc, store, physicalPath, entryType, entryId } = result;
+        const { doc, store, physicalPath, entryType, entryId, slug: entrySlug, urlPath } = result;
         // For md/mdx format, merge the body into the data so callers get a complete object.
         // The field name comes from the schema's isBody flag (defaults to 'body').
         const docRecord = doc;
@@ -228,7 +233,7 @@ export const createContentReader = (options) => {
             slug,
             branch: branchName,
         });
-        return { data, path, meta: { physicalPath, entryType, entryId } };
+        return { data, path, meta: { physicalPath, entryType, entryId, slug: entrySlug, urlPath } };
     };
     return { read };
 };

package/dist/content-store.d.ts

@@ -1,4 +1,4 @@
-import type { EntrySchema, FlatSchemaItem, EntryTypeConfig } from './config/index.js';
+import type { ContentFormat, EntrySchema, FlatSchemaItem, EntryTypeConfig } from './config/index.js';
 import { ContentIdIndex } from './content-id-index.js';
 import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export type MarkdownDocument = {
@@ -50,6 +50,19 @@ export declare class ContentStoreError extends Error {
 export declare class ContentConflictError extends Error {
     constructor(message?: string);
 }
+/**
+ * Thrown when a write carrying a numeric `expectedVersion` finds no file: the entry was deleted
+ * or moved since that version was read. A missing file is a change since the read, so the write
+ * is refused rather than re-creating the entry; re-creating it is a create (`expectedVersion:
+ * null`) the caller makes deliberately.
+ *
+ * A `ContentConflictError` subclass so every 409 mapping keeps working; the distinct type lets
+ * the API tell the editor the entry is gone, where "reload to see the latest version" has
+ * nothing to reload.
+ */
+export declare class EntryGoneError extends ContentConflictError {
+    constructor();
+}
 /**
  * [SYNC-C1] Thrown when a mutation could not take the branch's cross-host
  * content-write lock within its bounded wait (utils/content-write-lock.ts) --
@@ -61,7 +74,11 @@ export declare class ContentConflictError extends Error {
  * instead of the misleading generic "modified by another editor".
  */
 export declare class BranchSyncingError extends ContentConflictError {
-    constructor(message: string);
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the write ran and may have landed. */
+    readonly outcome: 'not-run' | 'unknown';
+    constructor(message: string, 
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the write ran and may have landed. */
+    outcome?: 'not-run' | 'unknown');
 }
 /**
  * [F1] Thrown when a save's content ID is carried by MORE THAN ONE file in the branch's
@@ -152,10 +169,11 @@ export interface ContentStoreOptions {
  * cache must never be shared by two readers.
  *
  * Misses are memoized alongside hits so one batch stays internally coherent: a shared block
- * resolving to data on page 1 and `null` on page 40 of one sitemap is worse than either
- * consistent answer. Each DISTINCT id still gets its full self-healing retry, inside the memo.
+ * resolving to data on page 1 and a `MissingReference` on page 40 of one sitemap is worse than
+ * either consistent answer. Each DISTINCT id still gets its full self-healing retry, inside the
+ * memo.
  */
-export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
+export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown>>>;
 /** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
 export declare const createReferenceResolveCache: () => ReferenceResolveCache;
 /**
@@ -172,6 +190,13 @@ export interface ReadOptions {
     resolveReferences?: boolean;
     /** See {@link ReferenceTargetAccess}. */
     referenceAccess?: ReferenceTargetAccess;
+    /**
+     * Read an entry of an `unavailable` entry type as raw data instead of throwing
+     * {@link SchemaUnavailableError}: for reads of it as another entry's reference target
+     * (resolution embeds that raw data; the picker takes a label from it), never for one an
+     * author edits.
+     */
+    allowUnavailableEntryType?: boolean;
 }
 export declare class ContentStore {
     private readonly root;
@@ -365,6 +390,10 @@ export declare class ContentStore {
         relativePath: PhysicalPath;
         /** The entry's logical path, the form path-permission rules match (`entryLogicalPath`). */
         logicalPath: LogicalPath;
+        /** The collection the entry file lives in: the parent, when an entry-type item delegated. */
+        collectionPath: LogicalPath;
+        /** The entry's slug within that collection, lowercased as listings report it. */
+        slug: Slug;
         id?: string;
         /**
          * Always populated for a valid schema item: the collection branch below resolves a name
@@ -387,6 +416,21 @@ export declare class ContentStore {
      */
     read(collectionPath: LogicalPath, slug?: Slug | '', options?: ReadOptions): Promise<ContentDocument>;
     write(collectionPath: LogicalPath, slug: (Slug | "") | undefined, input: WriteInput, entryTypeName?: string, existingId?: ContentId): Promise<ContentDocument>;
+    /**
+     * Set top-level `field` of the entry file at `physicalPath` to the string `value` when the
+     * file holds it empty (absent, null or ''), keeping every other byte. Resolves to the file's
+     * version (the mtime `read()` reports) before and after the write, or undefined when it left
+     * the file alone.
+     *
+     * PRECONDITION: the caller already holds this branch's content-write lock, which makes the
+     * read and the write one critical section; a call outside it throws. This takes no lock
+     * itself, since a nested acquisition fails busy and is why nothing holding that lock may call
+     * `write()` (docs/concurrency.md, "Lock acquisition order").
+     */
+    fillEmptyFieldWhileHoldingWriteLock(physicalPath: PhysicalPath, format: ContentFormat, field: string, value: string): Promise<{
+        previousVersion: number;
+        version: number;
+    } | undefined>;
     /**
      * Read an entry by its ID (UUID).
      * Returns null if the ID doesn't exist or points to a collection.
@@ -478,14 +522,21 @@ export declare class ContentStore {
      * unmemoized behavior.
      *
      * `access` applies to every target exactly as in `read()`; see {@link ReferenceTargetAccess}.
+     * `origin`, the referring entry's logical path, names it in the dangling-reference warning.
+     */
+    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache, access?: ReferenceTargetAccess, origin?: string): Promise<Record<string, unknown>>;
+    /**
+     * Resolve one reference id the way a reference field resolves it, for callers with ids but no
+     * field to walk: the editor's live-preview endpoint (api/resolve-references.ts) and the AI
+     * export (ai/references.ts). An id
+     * naming no readable entry resolves to a `MissingReference`, as in `read()`. No body is
+     * embedded, since there is no field to ask for one.
      */
-    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache, access?: ReferenceTargetAccess): Promise<Record<string, unknown>>;
+    resolveReferenceTarget(id: string, access?: ReferenceTargetAccess): Promise<Record<string, unknown>>;
     /**
-     * Resolve one reference id the way a reference field resolves it, for the editor's
-     * live-preview endpoint (api/resolve-references.ts), which has ids but no field to walk. Null
-     * when the id names no entry. No body is embedded, since there is no field to ask for one.
+     * `trail` names where `data` sits, for the dangling-reference warning: the referring entry and
+     * the field path so far, in `traverseFields`' format (`blocks[2].author`, `reviewers[1]`).
      */
-    resolveReferenceTarget(id: string, access?: ReferenceTargetAccess): Promise<Record<string, unknown> | null>;
     private resolveReferencesInData;
     /**
      * Resolve a single reference ID to full entry data, memoized when a batch cache is supplied.
@@ -501,7 +552,7 @@ export declare class ContentStore {
      * `data` from a process-global content-keyed cache, so `resolveSingleReferenceOnce`'s
      * top-level spread severs exactly one level and NESTED frontmatter objects alias across
      * occurrences, calls and requests. Pre-existing `read()` behavior, deliberately out of scope
-     * here; see `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+     * here; see safeinsights/canopycms#708.
      *
      * Measured (2000 occurrences of one target, local disk, the friendliest case for NOT
      * caching): cloning a snippet-sized target is ~63x cheaper than re-reading and parsing it, a
@@ -513,7 +564,8 @@ export declare class ContentStore {
      */
     private resolveSingleReference;
     /**
-     * Returns null if the reference is invalid or missing. Includes id, slug and collection.
+     * The target's data with its reference metadata, a `RestrictedReference` for a denied target,
+     * or a `MissingReference` when the id names no readable entry.
      *
      * A suspicious result (ID missing from the index, or an index hit whose file is gone)
      * triggers one forced index refresh and a retry — self-healing for mutations by other
@@ -526,6 +578,17 @@ export declare class ContentStore {
      * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
      */
     private resolveSingleReferenceUncached;
+    /**
+     * Throw {@link SchemaUnavailableError} when an entry exists at `slug` and is of an
+     * `unavailable` entry type, for a handler to refuse before any other check answers first.
+     */
+    assertEntryAvailable(collectionPath: LogicalPath, slug?: Slug | ''): Promise<void>;
+    /**
+     * Throw {@link SchemaUnavailableError} when the entry type an entry is read or written as --
+     * `entryTypeName`, else the collection's default -- is `unavailable`. A name the collection
+     * does not declare is never charged to the default type, which it was not written as.
+     */
+    private assertEntryTypeAvailable;
     /**
      * The entry type an entry file was written as, by its filename's type token, falling back to
      * the collection's default the way `read()` does for a legacy untyped file.