emdash 0.37.0 → 0.38.0

package/src/plugins/storage-update.ts

@@ -0,0 +1,96 @@
+import { validateJsonFieldName } from "../database/validate.js";
+import type { RangeFilter, WhereClause, WhereValue } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+	if (!isRecord(value)) {
+		throw new TypeError(`${label} must be an object`);
+	}
+	const prototype: unknown = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new TypeError(`${label} must be a plain object`);
+	}
+	return value;
+}
+
+function operand(value: unknown): string | number {
+	if (typeof value === "string" || (typeof value === "number" && Number.isFinite(value))) {
+		return value;
+	}
+	throw new TypeError("Storage guard operands must be strings or finite numbers");
+}
+
+function normalizeFilter(value: unknown): WhereValue {
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "string" || typeof value === "number") return operand(value);
+	const filter = requireRecord(value, "Storage guard filter");
+	const values = filter.in;
+	if (Array.isArray(values)) {
+		return { in: Array.from(values, operand) };
+	}
+	const prefix = filter.startsWith;
+	if (typeof prefix === "string") {
+		return { startsWith: prefix };
+	}
+	const range: RangeFilter = {};
+	for (const key of ["gt", "gte", "lt", "lte"] as const) {
+		if (key in filter) {
+			const bound = filter[key];
+			range[key] = bound === undefined ? undefined : operand(bound);
+		}
+	}
+	return range;
+}
+
+export function parseStorageUpdate(value: unknown): {
+	where: WhereClause;
+	setEntries: Array<[string, unknown]>;
+	deltaEntries: Array<[string, number]>;
+} {
+	const args = requireRecord(value, "Storage update arguments");
+	if (Object.keys(args).some((key) => key !== "where" && key !== "set" && key !== "delta")) {
+		throw new TypeError("Unknown storage update argument");
+	}
+	const where: WhereClause = {};
+	for (const [field, filter] of Object.entries(requireRecord(args.where, "Storage where guard"))) {
+		validateJsonFieldName(field);
+		where[field] = normalizeFilter(filter);
+	}
+	const set = args.set === undefined ? {} : requireRecord(args.set, "Storage set");
+	const delta = args.delta === undefined ? {} : requireRecord(args.delta, "Storage delta");
+	const setEntries: Array<[string, unknown]> = [];
+	for (const [field, entry] of Object.entries(set)) {
+		if (entry === undefined) continue;
+		validateJsonFieldName(field);
+		const serialized = JSON.stringify(entry);
+		if (serialized === undefined)
+			throw new TypeError("Storage set values must be JSON serializable");
+		const normalized: unknown = JSON.parse(serialized);
+		setEntries.push([field, normalized]);
+	}
+	const setFields = new Set(setEntries.map(([field]) => field));
+	const deltaEntries: Array<[string, number]> = [];
+	for (const [field, entry] of Object.entries(delta)) {
+		if (entry === undefined) continue;
+		validateJsonFieldName(field);
+		if (setFields.has(field)) throw new TypeError("Storage field appears in both set and delta");
+		const spec = requireRecord(entry, "Storage numeric delta");
+		const keys = Object.keys(spec);
+		const key = keys[0];
+		if (keys.length !== 1 || (key !== "inc" && key !== "dec")) {
+			throw new TypeError("Storage delta must contain exactly one of inc or dec");
+		}
+		const amount = spec[key];
+		if (typeof amount !== "number" || !Number.isSafeInteger(amount)) {
+			throw new TypeError("Storage delta must be a safe integer");
+		}
+		deltaEntries.push([field, key === "dec" ? -amount : amount]);
+	}
+	if (setEntries.length + deltaEntries.length === 0) {
+		throw new TypeError("Storage update requires at least one of set or delta");
+	}
+	return { where, setEntries, deltaEntries };
+}

package/src/plugins/types.ts

@@ -135,6 +135,71 @@ export interface PaginatedResult<T> {
 	hasMore: boolean;
 }
 
+export interface VersionedValue<T = unknown> {
+	value: T;
+	/** Opaque host revision, valid only for the key from which it was read. */
+	revision: string;
+}
+
+export type ConditionalWriteResult = { applied: true; revision: string } | { applied: false };
+
+export interface ConditionalDeleteResult {
+	applied: boolean;
+}
+
+/**
+ * A single per-field integer delta for {@link StorageCollection.updateIf}.
+ *
+ * `inc`/`dec` values must be safe integers, enforced at runtime with
+ * `Number.isSafeInteger` (which also rejects `NaN`/`Infinity`), because a TS
+ * `number` cannot forbid float literals. Deltas are applied entirely in-SQL
+ * over the stored value with `COALESCE(<value>, 0) ± n`, so a delta on a
+ * missing or JSON-`null` field starts from `0` (never corrupts the document).
+ *
+ * `updateIf` does NOT clamp: a `dec` can drive a field negative when the
+ * `where` guard doesn't cover the delta magnitude (e.g. stock `2` with
+ * `where: { stock: { gte: 1 } }` and `delta: { stock: { dec: 3 } }` → `-1`,
+ * `applied: true`). The guard is the caller's responsibility — pair a `dec: k`
+ * with a `gte: k` guard to prevent underflow.
+ */
+export type NumericDelta = { inc: number } | { dec: number };
+
+/**
+ * Arguments to {@link StorageCollection.updateIf}.
+ *
+ * `where` reuses the {@link QueryOptions} `WhereClause` verbatim — the guard is
+ * evaluated in-SQL with the same numeric-correct, total comparisons as
+ * `query()`. An empty `where: {}` emits no guard, i.e. it matches the row
+ * unconditionally (update-if-row-exists) — a footgun in the no-oversell case,
+ * where a real predicate (e.g. `{ stock: { gte: 1 } }`) is what you want.
+ *
+ * At least one of `set` / `delta` must be present (a runtime error is thrown
+ * otherwise). A field may not appear in both `set` and `delta` in the same
+ * call. `set` and `delta` are separate arguments (not a union) so a wholesale
+ * value that happens to look like `{ inc: 5 }` is never mistaken for a delta.
+ */
+export interface UpdateIfArgs<T> {
+	/**
+	 * Guard evaluated in-SQL; identical semantics to `query({ where })`. An
+	 * empty `{}` means "match the row unconditionally (no guard)".
+	 */
+	where: WhereClause;
+	/** Wholesale field values merged into the stored JSON document. */
+	set?: Partial<T>;
+	/** Per-field integer deltas applied in-SQL (`COALESCE(base, 0) ± n`). */
+	delta?: { [K in keyof T]?: NumericDelta };
+}
+
+/**
+ * Result of {@link StorageCollection.updateIf}.
+ *
+ * `applied: false` intentionally conflates "row absent" and "guard failed": a
+ * single-statement guarded `UPDATE` cannot distinguish them, and the caller
+ * should not need to. `updateIf` is update-only — it never inserts a missing
+ * row.
+ */
+export type UpdateIfResult<T> = { applied: true; data: T } | { applied: false };
+
 /**
  * Storage collection interface - the API exposed to plugins
  * No async iterators - all operations return promises with pagination
@@ -145,6 +210,15 @@ export interface StorageCollection<T = unknown> {
 	put(id: string, data: T): Promise<void>;
 	delete(id: string): Promise<boolean>;
 	exists(id: string): Promise<boolean>;
+	/** A stored JSON null returns an envelope with value: null; only an absent row returns null. */
+	getVersioned(id: string): Promise<VersionedValue<T> | null>;
+	/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+	compareAndSet(
+		id: string,
+		expectedRevision: string | null,
+		data: T,
+	): Promise<ConditionalWriteResult>;
+	compareAndDelete(id: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
 
 	// Batch operations
 	getMany(ids: string[]): Promise<Map<string, T>>;
@@ -154,6 +228,23 @@ export interface StorageCollection<T = unknown> {
 	// Query - always paginated
 	query(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>>;
 	count(where?: WhereClause): Promise<number>;
+
+	// Conditional write (single-statement, atomic per row).
+	/**
+	 * Predicate-guarded atomic update. Applies `set`/`delta` to the row `id`
+	 * only if it exists and the `where` guard matches, in a single guarded
+	 * `UPDATE … RETURNING`. This is the no-oversell primitive: the guard and the
+	 * arithmetic live in one statement, so N concurrent guarded decrements
+	 * serialize correctly. `applied: false` means the row was absent OR the
+	 * guard failed (the two are intentionally indistinguishable). Non-object
+	 * documents, invalid counters and unsafe arithmetic results also fail the
+	 * guard. Never inserts.
+	 *
+	 * Serialization failures and deadlocks throw `StorageSerializationError`.
+	 * Retry the write with a bounded policy; restart an explicit transaction
+	 * before retrying its operations.
+	 */
+	updateIf(id: string, args: UpdateIfArgs<T>): Promise<UpdateIfResult<T>>;
 }
 
 /**
@@ -176,6 +267,14 @@ export type PluginStorage<T extends PluginStorageConfig> = {
  */
 export interface KVAccess {
 	get<T>(key: string): Promise<T | null>;
+	getVersioned<T>(key: string): Promise<VersionedValue<T> | null>;
+	/** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+	compareAndSet(
+		key: string,
+		expectedRevision: string | null,
+		value: unknown,
+	): Promise<ConditionalWriteResult>;
+	compareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
 	set(key: string, value: unknown): Promise<void>;
 	delete(key: string): Promise<boolean>;
 	list(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;
@@ -804,6 +903,15 @@ export interface HookConfig<THandler> {
 	handler: THandler;
 }
 
+/**
+ * Acting user that triggered a content hook. Present for authenticated
+ * saves; absent for unauthenticated or internal writes.
+ */
+export interface ActorInfo {
+	readonly id: string;
+	readonly role: number;
+}
+
 /**
  * Content hook event
  */
@@ -817,6 +925,12 @@ export interface ContentHookEvent {
 	 * `content:afterSave`, where `content.id` carries it.
 	 */
 	id?: string;
+	/**
+	 * The acting user for this save. Carries the same authenticated identity
+	 * used to set the revision author, so plugins (e.g. audit logs) can record
+	 * who made the change.
+	 */
+	actor?: ActorInfo;
 }
 
 /**

package/src/query.ts

@@ -24,7 +24,7 @@
  * import resolves there at typecheck time without our help.
  */
 
-import { encodeCursor } from "./database/repositories/types.js";
+import { encodeCursor, type ContentSeo } from "./database/repositories/types.js";
 import { getFallbackChain, getI18nConfig, isI18nEnabled } from "./i18n/config.js";
 import {
 	creditsFromFoldedBylines,
@@ -40,8 +40,10 @@ import {
 	contentNamespaces,
 	invalidateSchemaObjectCache,
 } from "./object-cache/index.js";
+import { primeSeoPanel } from "./page/seo-panel.js";
 import { requestCached } from "./request-cache.js";
 import { getRequestContext } from "./request-context.js";
+import { resetRegisteredCollectionsCache } from "./schema/collection-slugs-cache.js";
 import { compileUrlPattern } from "./schema/url-pattern.js";
 import type { TaxonomyTerm } from "./taxonomies/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
@@ -398,8 +400,21 @@ export async function getEmDashCollection<T extends string, D = InferCollectionD
 	// Cursor-paginated calls are exempt: their limit is part of the
 	// pagination contract.
 	const bucketed = bucketFilter(filter);
+
+	// Preview and edit-mode requests skip `loadCollectionCached`. That path
+	// reduces every entry to a JSON snapshot (`entrySnapshot`) and rebuilds it
+	// with `reviveEntry`, which cannot carry the `edit` proxy and re-attaches
+	// the no-op — so annotations spread as `{...entry.edit.title}` would render
+	// nothing on list pages. `getEmDashEntry` has the same bypass for the same
+	// reason (see its `serveDrafts` branch). The request-scoped cache still
+	// collapses duplicate queries within the render.
+	const ctx = getRequestContext();
+	const serveDrafts = ctx?.editMode === true || ctx?.preview !== undefined;
+
 	const cached = await requestCached(collectionCacheKey(type, bucketed.fetchFilter), () =>
-		loadCollectionCached<T, D>(type, bucketed.fetchFilter),
+		serveDrafts
+			? getEmDashCollectionUncached<T, D>(type, bucketed.fetchFilter)
+			: loadCollectionCached<T, D>(type, bucketed.fetchFilter),
 	);
 	return bucketed.requestedLimit === undefined
 		? cached
@@ -979,6 +994,15 @@ export async function getEmDashEntry<T extends string, D = InferCollectionData<T
 	}
 	const revived = snapshot.value.entry ? reviveEntry<D>(snapshot.value.entry) : null;
 	if (revived && !canExposeRevisionMetadata(revived, type)) stripRevisionMetadata(revived);
+	if (revived) {
+		// On a warm object-cache hit the loader never runs, so prime the
+		// SEO panel cache from the snapshot's data (a no-op after a miss,
+		// where the loader already primed).
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- snapshot `data` is always a record
+		const { id: rowId, seo } = revived.data as Record<string, unknown>;
+		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- `data.seo` is written by the loader as ContentSeo
+		if (seo && typeof rowId === "string") primeSeoPanel(type, rowId, seo as ContentSeo);
+	}
 	return {
 		entry: revived,
 		isPreview: snapshot.value.isPreview,
@@ -1326,11 +1350,13 @@ const urlPatternCache: UrlPatternCache =
  * Call when collection URL patterns change (schema updates).
  *
  * Also busts the distributed schema cache (collection metadata such as
- * `commentsEnabled`, `supports`, fields read by `getCollectionInfo`), since
+ * `commentsEnabled`, `supports`, fields read by `getCollectionInfo`) and the
+ * per-isolate registered-collection-slugs cache used by term counting, since
  * every schema-mutation path already routes through here.
  */
 export function invalidateUrlPatternCache(): void {
 	urlPatternCache.patterns = null;
+	resetRegisteredCollectionsCache();
 	invalidateSchemaObjectCache();
 }
 

package/src/registry/config.ts

@@ -41,6 +41,39 @@ export interface ManifestRegistryConfig {
 	};
 }
 
+export type RegistryConfigurationErrorCode =
+	| "REGISTRY_AGGREGATOR_URL_REQUIRED"
+	| "REGISTRY_AGGREGATOR_URL_INVALID"
+	| "REGISTRY_AGGREGATOR_URL_FORBIDDEN"
+	| "REGISTRY_MINIMUM_RELEASE_AGE_INVALID"
+	| "REGISTRY_MINIMUM_RELEASE_AGE_EXCLUDE_INVALID";
+
+export type RegistryConfigurationField =
+	| "experimental.registry.aggregatorUrl"
+	| "experimental.registry.policy.minimumReleaseAge"
+	| "experimental.registry.policy.minimumReleaseAgeExclude";
+
+export interface ManifestRegistryConfigurationError {
+	code: RegistryConfigurationErrorCode;
+	field: RegistryConfigurationField;
+}
+
+class RegistryConfigurationError extends Error {
+	constructor(
+		public readonly code: RegistryConfigurationErrorCode,
+		public readonly field: RegistryConfigurationField,
+		message: string,
+		options?: ErrorOptions,
+	) {
+		super(`EmDash registry configuration error in ${field}: ${message}`, options);
+		this.name = "RegistryConfigurationError";
+	}
+}
+
+interface RegistryConfigurationValidationOptions {
+	allowLocalhost?: boolean;
+}
+
 /**
  * Canonicalize a capabilities list for set-style comparison.
  *
@@ -169,15 +202,27 @@ export function parseDurationSeconds(duration: string | number): number {
  * own HTTPS bundle, defeating the checksum trust chain because the
  * attacker controls the unsigned transport that supplied the checksum.
  */
-export function validateAggregatorUrl(aggregatorUrl: string): URL {
+export function validateAggregatorUrl(
+	aggregatorUrl: string,
+	options: RegistryConfigurationValidationOptions = {},
+): URL {
 	let parsed: URL;
 	try {
 		parsed = new URL(aggregatorUrl);
-	} catch {
-		throw new Error(`registry.aggregatorUrl is not a valid URL: ${aggregatorUrl}`);
+	} catch (cause) {
+		throw new RegistryConfigurationError(
+			"REGISTRY_AGGREGATOR_URL_INVALID",
+			"experimental.registry.aggregatorUrl",
+			"must be a valid URL",
+			{ cause },
+		);
 	}
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-		throw new Error(`registry.aggregatorUrl must use http or https: ${aggregatorUrl}`);
+		throw new RegistryConfigurationError(
+			"REGISTRY_AGGREGATOR_URL_FORBIDDEN",
+			"experimental.registry.aggregatorUrl",
+			"must use HTTP or HTTPS",
+		);
 	}
 	// Reject embedded credentials. The normalized aggregator URL ends
 	// up in the admin manifest and is shipped to every admin browser;
@@ -185,7 +230,11 @@ export function validateAggregatorUrl(aggregatorUrl: string): URL {
 	// so leaving them in would both leak the credentials and break the
 	// registry UI at runtime.
 	if (parsed.username || parsed.password) {
-		throw new Error("registry.aggregatorUrl must not contain embedded credentials (user:pass@)");
+		throw new RegistryConfigurationError(
+			"REGISTRY_AGGREGATOR_URL_FORBIDDEN",
+			"experimental.registry.aggregatorUrl",
+			"must not contain embedded credentials",
+		);
 	}
 
 	// WHATWG URL preserves the brackets on IPv6 hostnames -- strip them
@@ -205,18 +254,27 @@ export function validateAggregatorUrl(aggregatorUrl: string): URL {
 		hostname.startsWith("::ffff:127.") ||
 		hostname.startsWith("::ffff:7f00:");
 
-	if (!import.meta.env.DEV) {
+	const allowLocalhost = options.allowLocalhost ?? import.meta.env.DEV;
+	if (!allowLocalhost) {
 		if (parsed.protocol === "http:") {
-			throw new Error(`registry.aggregatorUrl must use https in production: ${aggregatorUrl}`);
+			throw new RegistryConfigurationError(
+				"REGISTRY_AGGREGATOR_URL_FORBIDDEN",
+				"experimental.registry.aggregatorUrl",
+				"must use HTTPS outside development",
+			);
 		}
 		if (isLocalhost) {
-			throw new Error(
-				`registry.aggregatorUrl points at localhost; allowed only in dev: ${aggregatorUrl}`,
+			throw new RegistryConfigurationError(
+				"REGISTRY_AGGREGATOR_URL_FORBIDDEN",
+				"experimental.registry.aggregatorUrl",
+				"must not point at localhost outside development",
 			);
 		}
 	} else if (parsed.protocol === "http:" && !isLocalhost) {
-		throw new Error(
-			`registry.aggregatorUrl must use https (http allowed only for localhost in dev): ${aggregatorUrl}`,
+		throw new RegistryConfigurationError(
+			"REGISTRY_AGGREGATOR_URL_FORBIDDEN",
+			"experimental.registry.aggregatorUrl",
+			"must use HTTPS unless it points at localhost in development",
 		);
 	}
 
@@ -251,28 +309,30 @@ export function coerceRegistryConfig(
  * object. Returns `null` when `input` is undefined so callers can
  * spread the result directly into the manifest object.
  *
- * Throws if the aggregator URL is malformed, points at a forbidden host,
- * or `policy.minimumReleaseAge` is unparseable. These surface at
- * runtime startup as 500s from the manifest endpoint -- intended,
- * because the alternative is silently disabling the registry on
- * misconfigured sites.
- *
- * TODO: switch to a Zod schema for richer per-field error messages and
- * to surface misconfigurations to the admin UI as a banner instead of
- * a manifest 500.
+ * Throws a field-specific configuration error if the aggregator URL is
+ * malformed or forbidden, or a registry policy value cannot be normalized.
+ * The Astro integration uses this to fail during config loading. Runtime
+ * manifest generation uses {@link resolveManifestRegistryConfig} to expose
+ * recognized failures without exposing the configured value.
  */
 export function normalizeRegistryConfig(
 	input: RegistryConfigInput | undefined,
+	options: RegistryConfigurationValidationOptions = {},
 ): ManifestRegistryConfig | null {
 	const config = coerceRegistryConfig(input);
 	if (!config) return null;
 
-	const aggregatorUrl = config.aggregatorUrl?.trim();
+	const aggregatorUrl =
+		typeof config.aggregatorUrl === "string" ? config.aggregatorUrl.trim() : undefined;
 	if (!aggregatorUrl) {
-		throw new Error("registry.aggregatorUrl is required when registry is configured");
+		throw new RegistryConfigurationError(
+			"REGISTRY_AGGREGATOR_URL_REQUIRED",
+			"experimental.registry.aggregatorUrl",
+			"is required when the registry is configured",
+		);
 	}
 
-	validateAggregatorUrl(aggregatorUrl);
+	validateAggregatorUrl(aggregatorUrl, options);
 
 	const out: ManifestRegistryConfig = {
 		// Strip any trailing slash so `${aggregatorUrl}/xrpc/...` works
@@ -288,18 +348,45 @@ export function normalizeRegistryConfig(
 	let hasPolicy = false;
 
 	if (config.policy?.minimumReleaseAge !== undefined) {
-		policy.minimumReleaseAgeSeconds = parseDurationSeconds(config.policy.minimumReleaseAge);
+		try {
+			policy.minimumReleaseAgeSeconds = parseDurationSeconds(config.policy.minimumReleaseAge);
+		} catch (cause) {
+			throw new RegistryConfigurationError(
+				"REGISTRY_MINIMUM_RELEASE_AGE_INVALID",
+				"experimental.registry.policy.minimumReleaseAge",
+				'must be a duration such as "48h", "7d", or a non-negative number of seconds',
+				{ cause },
+			);
+		}
 		hasPolicy = true;
 	}
 
 	if (config.policy?.minimumReleaseAgeExclude !== undefined) {
+		if (!Array.isArray(config.policy.minimumReleaseAgeExclude)) {
+			throw new RegistryConfigurationError(
+				"REGISTRY_MINIMUM_RELEASE_AGE_EXCLUDE_INVALID",
+				"experimental.registry.policy.minimumReleaseAgeExclude",
+				"must be an array of DIDs or <did>/<slug> entries",
+			);
+		}
 		// Normalize at load time so callers (browser and server) can do
 		// plain string compares without each one re-implementing the
 		// case-folding rule.
 		const list = config.policy.minimumReleaseAgeExclude.map((entry) => {
+			if (typeof entry !== "string") {
+				throw new RegistryConfigurationError(
+					"REGISTRY_MINIMUM_RELEASE_AGE_EXCLUDE_INVALID",
+					"experimental.registry.policy.minimumReleaseAgeExclude",
+					"minimumReleaseAgeExclude entry must be a DID or <did>/<slug>",
+				);
+			}
 			const trimmed = entry.trim();
 			if (!trimmed) {
-				throw new Error("registry.policy.minimumReleaseAgeExclude entries cannot be empty");
+				throw new RegistryConfigurationError(
+					"REGISTRY_MINIMUM_RELEASE_AGE_EXCLUDE_INVALID",
+					"experimental.registry.policy.minimumReleaseAgeExclude",
+					"entries cannot be empty",
+				);
 			}
 			const lower = trimmed.toLowerCase();
 			const [did, slug, ...extra] = lower.split("/");
@@ -309,8 +396,10 @@ export function normalizeRegistryConfig(
 				extra.length > 0 ||
 				(slug !== undefined && !REGISTRY_PACKAGE_SLUG_PATTERN.test(slug))
 			) {
-				throw new Error(
-					`registry.policy.minimumReleaseAgeExclude entry must be a DID or <did>/<slug>: ${trimmed}`,
+				throw new RegistryConfigurationError(
+					"REGISTRY_MINIMUM_RELEASE_AGE_EXCLUDE_INVALID",
+					"experimental.registry.policy.minimumReleaseAgeExclude",
+					"minimumReleaseAgeExclude entry must be a DID or <did>/<slug>",
 				);
 			}
 			return lower;
@@ -327,3 +416,17 @@ export function normalizeRegistryConfig(
 
 	return out;
 }
+
+/** Normalize registry config without allowing a known config error to hide the admin. */
+export function resolveManifestRegistryConfig(input: RegistryConfigInput | undefined): {
+	registry?: ManifestRegistryConfig;
+	error?: ManifestRegistryConfigurationError;
+} {
+	try {
+		const registry = normalizeRegistryConfig(input);
+		return registry ? { registry } : {};
+	} catch (error) {
+		if (!(error instanceof RegistryConfigurationError)) throw error;
+		return { error: { code: error.code, field: error.field } };
+	}
+}

package/src/registry/types.ts

@@ -56,12 +56,11 @@ export interface RegistryConfig {
 		 * Accepts a duration string (`"24h"`, `"48h"`, `"72h"`, `"7d"`) or a
 		 * number of seconds.
 		 *
-		 * Currently applies uniformly to all releases. A future addition
-		 * may exempt brand-new packages (those with no prior release
-		 * history) so the holdback doesn't block first-time publishing,
-		 * but that exemption is not implemented yet; use
-		 * {@link minimumReleaseAgeExclude} to allowlist trusted publishers
-		 * whose packages should install immediately.
+		 * A package's first release is exempt only when the aggregator
+		 * reports one release and confirms that its retained history is
+		 * complete. Missing or incomplete history keeps the holdback in
+		 * force. Use {@link minimumReleaseAgeExclude} to allowlist trusted
+		 * publishers whose packages should always install immediately.
 		 *
 		 * Defaults to `undefined` (no holdback). A future trust/moderation
 		 * RFC will specify the recommended default.