@cardinali-studio/adminkit 2.1.0-rc.4 → 2.2.0

package/dist/persistence.d.ts

@@ -0,0 +1,182 @@
+import type { StoredReleaseExport } from "./release.js";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type Revision = Readonly<{
+    revisionId: string;
+    documentId: string;
+    baseRevisionId: string | null;
+    expectedDraftRevisionId?: string | null;
+    payload: JsonValue | null;
+    tombstone: boolean;
+    schemaVersion: number;
+    payloadChecksum: string;
+    requestChecksum: string;
+}>;
+export type ReleaseStatus = "publishing" | "published" | "failed" | "superseded";
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(value: string): Promise<string>;
+export declare function canonicalChecksum(value: unknown): Promise<string>;
+/** The client may carry this checksum for retry correlation, but the API
+ * recomputes it from the complete normalized Save command before D1 sees it. */
+export declare function contentSaveRequestChecksum(input: {
+    revisionId: string;
+    documentId: string;
+    baseRevisionId: string | null;
+    expectedDraftRevisionId?: string | null;
+    kind: string;
+    locale: string;
+    translationGroupId?: string | null;
+    payload: JsonValue | null;
+    tombstone: boolean;
+    schemaVersion: number;
+}): Promise<string>;
+/** Stable UUIDv5-shaped identifier for import identities (site + legacy key + locale). */
+export declare function deterministicId(...parts: string[]): Promise<string>;
+export declare function assertIdempotent<T extends {
+    requestChecksum: string;
+}>(existing: T | undefined, requestChecksum: string): {
+    kind: "create";
+} | {
+    kind: "repeat";
+    value: T;
+};
+export declare class UpgraderChain {
+    #private;
+    register(fromVersion: number, upgrade: (payload: JsonValue) => JsonValue): void;
+    upgrade(payload: JsonValue, fromVersion: number, targetVersion: number): JsonValue;
+}
+export type DocumentDraft = {
+    documentId: string;
+    draftRevisionId: string | null;
+    abandoned: boolean;
+};
+/** Structural subset of the Workers D1 API. Keeping it local avoids leaking a
+ * Workers-only type into browser consumers of the package. */
+export interface D1Result<T = unknown> {
+    results?: T[];
+    meta?: {
+        changes?: number;
+    };
+    success: boolean;
+}
+export interface D1Statement {
+    bind(...values: unknown[]): D1Statement;
+    first<T = unknown>(): Promise<T | null>;
+    all<T = unknown>(): Promise<D1Result<T>>;
+    run<T = unknown>(): Promise<D1Result<T>>;
+}
+export interface D1DatabaseLike {
+    prepare(query: string): D1Statement;
+    batch<T = unknown>(statements: D1Statement[]): Promise<D1Result<T>[]>;
+}
+export type StoredRevision = {
+    revisionId: string;
+    documentId: string;
+    baseRevisionId: string | null;
+    payload: string | null;
+    tombstone: boolean;
+    schemaVersion: number;
+    payloadChecksum: string;
+    createdAt: number;
+};
+export type EffectiveDocument = {
+    documentId: string;
+    kind: string;
+    locale: string;
+    draftRevisionId: string | null;
+    publishedRevisionId: string | null;
+    publishedPayload: string | null;
+    publishedTombstone: boolean | null;
+};
+export type SaveInput = Revision & {
+    /** The current DRAFT pointer used for CAS. It is distinct from the immutable
+     * revision ancestry: a first draft may be based on a published revision while
+     * the live draft pointer is still null. */
+    expectedDraftRevisionId?: string | null;
+    kind: string;
+    locale: string;
+    translationGroupId?: string | null;
+    now: number;
+    authorSubject: string;
+    authorLabel: string;
+};
+export type ReleaseInput = {
+    releaseId: string;
+    requestChecksum: string;
+    manifestChecksum: string;
+    schemaPackageVersion: string;
+    materializerVersion: string;
+    authorSubject: string;
+    now: number;
+    entries: readonly {
+        documentId: string;
+        revisionId: string;
+    }[];
+};
+export type ContentImportRun = {
+    importId: string;
+    requestChecksum: string;
+    sourceMainSha: string;
+    sourceDraftSha: string;
+    importerVersion: string;
+    schemaVersion: string;
+    canonicalChecksum: string;
+    countsJson: string;
+    result: string;
+    diagnosticId?: string | null;
+    now: number;
+};
+/** D1 persistence boundary. Every mutation is expressed as a guarded SQL batch:
+ * zero affected rows means stale state, never a best-effort overwrite. */
+export declare class D1ContentRepository {
+    private readonly db;
+    constructor(db: D1DatabaseLike);
+    initializeSiteState(schemaGeneration: number, now: number): Promise<void>;
+    /** Import audit is resource-local and immutable: a rerun of the same fetched
+     * remote SHA pair is harmless; a reused ID with different evidence is not. */
+    recordImport(input: ContentImportRun): Promise<"created" | "repeated">;
+    getImport(importId: string): Promise<{
+        requestChecksum: string;
+    } | null>;
+    getEffectiveDocument(documentId: string): Promise<EffectiveDocument | null>;
+    getRevision(revisionId: string): Promise<StoredRevision | null>;
+    /** Exact immutable candidate/successful release only. This intentionally has
+     * no "latest" variant: a deployment attempt must name what it exports. */
+    getReleaseExport(releaseId: string): Promise<StoredReleaseExport | null>;
+    save(input: SaveInput): Promise<"created" | "repeated">;
+    discard(documentId: string, expectedDraftRevisionId: string | null, baselineRevisionId: string | null, now: number): Promise<void>;
+    publish(input: ReleaseInput): Promise<"created" | "repeated">;
+    finalize(releaseId: string, now: number): Promise<void>;
+}
+/** Pure strict-CAS kernel. The D1 adapter uses these guards around its SQL operations. */
+export declare class ContentKernel {
+    readonly documents: Map<string, DocumentDraft>;
+    readonly revisions: Map<string, Readonly<{
+        revisionId: string;
+        documentId: string;
+        baseRevisionId: string | null;
+        expectedDraftRevisionId?: string | null;
+        payload: JsonValue | null;
+        tombstone: boolean;
+        schemaVersion: number;
+        payloadChecksum: string;
+        requestChecksum: string;
+    }>>;
+    readonly releases: Map<string, {
+        requestChecksum: string;
+        baseReleaseId: string | null;
+        status: ReleaseStatus;
+        entries: Map<string, string>;
+    }>;
+    currentReleaseId: string | null;
+    save(revision: Revision): Revision;
+    discard(documentId: string, expectedDraftRevisionId: string | null, baselineRevisionId: string | null): void;
+    publish(releaseId: string, requestChecksum: string, entries: Iterable<[string, string]>): void;
+    /** Creates the immutable full manifest from the current published release
+     * plus only the explicitly selected current drafts. Other drafts remain
+     * drafts; a candidate never becomes a partial published view by accident. */
+    publishSelected(releaseId: string, requestChecksum: string, selected: Iterable<[string, string]>): void;
+    private createRelease;
+    finalize(releaseId: string): void;
+}

package/dist/persistence.js

@@ -0,0 +1,320 @@
+export function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("JSON numbers must be finite");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value !== "object")
+        throw new TypeError("Value is not canonical JSON");
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+export async function sha256Hex(value) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export async function canonicalChecksum(value) {
+    return sha256Hex(canonicalJson(value));
+}
+/** The client may carry this checksum for retry correlation, but the API
+ * recomputes it from the complete normalized Save command before D1 sees it. */
+export async function contentSaveRequestChecksum(input) {
+    return canonicalChecksum({
+        action: "content.save",
+        revisionId: input.revisionId,
+        documentId: input.documentId,
+        baseRevisionId: input.baseRevisionId,
+        expectedDraftRevisionId: input.expectedDraftRevisionId === undefined ? input.baseRevisionId : input.expectedDraftRevisionId,
+        kind: input.kind,
+        locale: input.locale,
+        translationGroupId: input.translationGroupId ?? null,
+        payload: input.payload,
+        tombstone: input.tombstone,
+        schemaVersion: input.schemaVersion,
+    });
+}
+/** Stable UUIDv5-shaped identifier for import identities (site + legacy key + locale). */
+export async function deterministicId(...parts) {
+    if (!parts.length || parts.some((part) => !part))
+        throw new Error("invalid_deterministic_id_input");
+    const hex = await sha256Hex(parts.map((part) => `${part.length}:${part}`).join("|"));
+    const bytes = Array.from({ length: 16 }, (_, index) => hex.slice(index * 2, index * 2 + 2));
+    bytes[6] = `${(Number.parseInt(bytes[6], 16) & 0x0f | 0x50).toString(16).padStart(2, "0")}`;
+    bytes[8] = `${(Number.parseInt(bytes[8], 16) & 0x3f | 0x80).toString(16).padStart(2, "0")}`;
+    const compact = bytes.join("");
+    return `${compact.slice(0, 8)}-${compact.slice(8, 12)}-${compact.slice(12, 16)}-${compact.slice(16, 20)}-${compact.slice(20, 32)}`;
+}
+export function assertIdempotent(existing, requestChecksum) {
+    if (!existing)
+        return { kind: "create" };
+    if (existing.requestChecksum !== requestChecksum)
+        throw new Error("duplicate_request");
+    return { kind: "repeat", value: existing };
+}
+export class UpgraderChain {
+    #steps = new Map();
+    register(fromVersion, upgrade) {
+        if (!Number.isInteger(fromVersion) || fromVersion < 1 || this.#steps.has(fromVersion)) {
+            throw new Error("invalid_upgrader");
+        }
+        this.#steps.set(fromVersion, upgrade);
+    }
+    upgrade(payload, fromVersion, targetVersion) {
+        if (!Number.isInteger(fromVersion) || !Number.isInteger(targetVersion) || fromVersion > targetVersion) {
+            throw new Error("invalid_schema_version");
+        }
+        let value = payload;
+        for (let version = fromVersion; version < targetVersion; version += 1) {
+            const step = this.#steps.get(version);
+            if (!step)
+                throw new Error("unsupported_schema_version");
+            value = step(value);
+        }
+        return value;
+    }
+}
+/** D1 persistence boundary. Every mutation is expressed as a guarded SQL batch:
+ * zero affected rows means stale state, never a best-effort overwrite. */
+export class D1ContentRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async initializeSiteState(schemaGeneration, now) {
+        const result = await this.db.prepare("INSERT INTO content_site_state (singleton, current_release_id, schema_generation, updated_at) VALUES (1, NULL, ?, ?) ON CONFLICT(singleton) DO NOTHING")
+            .bind(schemaGeneration, now).run();
+        if (!result.success)
+            throw new Error("content_unavailable");
+    }
+    /** Import audit is resource-local and immutable: a rerun of the same fetched
+     * remote SHA pair is harmless; a reused ID with different evidence is not. */
+    async recordImport(input) {
+        const existing = await this.db.prepare("SELECT request_checksum AS requestChecksum FROM content_import_runs WHERE import_id = ?")
+            .bind(input.importId).first();
+        const idempotency = assertIdempotent(existing ?? undefined, input.requestChecksum);
+        if (idempotency.kind === "repeat")
+            return "repeated";
+        const result = await this.db.prepare(`INSERT INTO content_import_runs
+      (import_id, request_checksum, source_main_sha, source_draft_sha, importer_version, schema_version,
+       canonical_checksum, counts_json, result, diagnostic_id, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .bind(input.importId, input.requestChecksum, input.sourceMainSha, input.sourceDraftSha, input.importerVersion, input.schemaVersion, input.canonicalChecksum, input.countsJson, input.result, input.diagnosticId ?? null, input.now).run();
+        if (result.meta?.changes !== 1)
+            throw new Error("content_unavailable");
+        return "created";
+    }
+    async getImport(importId) {
+        return this.db.prepare("SELECT request_checksum AS requestChecksum FROM content_import_runs WHERE import_id = ?")
+            .bind(importId).first();
+    }
+    async getEffectiveDocument(documentId) {
+        return this.db.prepare(`SELECT d.document_id AS documentId, d.kind, d.locale, d.draft_revision_id AS draftRevisionId,
+      published.revision_id AS publishedRevisionId, published.payload_json AS publishedPayload, published.is_tombstone AS publishedTombstone
+      FROM content_documents d
+      LEFT JOIN content_site_state state ON state.singleton = 1
+      LEFT JOIN content_release_entries entry ON entry.release_id = state.current_release_id AND entry.document_id = d.document_id
+      LEFT JOIN content_revisions published ON published.document_id = entry.document_id AND published.revision_id = entry.revision_id
+      WHERE d.document_id = ?`).bind(documentId).first();
+    }
+    async getRevision(revisionId) {
+        return this.db.prepare(`SELECT revision_id AS revisionId, document_id AS documentId, base_revision_id AS baseRevisionId,
+      payload_json AS payload, is_tombstone AS tombstone, schema_version AS schemaVersion,
+      payload_checksum AS payloadChecksum, created_at AS createdAt
+      FROM content_revisions WHERE revision_id = ?`).bind(revisionId).first();
+    }
+    /** Exact immutable candidate/successful release only. This intentionally has
+     * no "latest" variant: a deployment attempt must name what it exports. */
+    async getReleaseExport(releaseId) {
+        const rows = (await this.db.prepare(`SELECT release.release_id AS releaseId, release.status,
+      release.schema_package_version AS schemaPackageVersion, release.materializer_version AS materializerVersion,
+      release.manifest_checksum AS manifestChecksum, entry.document_id AS documentId, entry.revision_id AS revisionId,
+      document.kind, document.locale, revision.schema_version AS schemaVersion, revision.is_tombstone AS tombstone,
+      revision.payload_json AS payloadJson, revision.payload_checksum AS payloadChecksum
+      FROM content_releases release
+      JOIN content_release_entries entry ON entry.release_id = release.release_id
+      JOIN content_documents document ON document.document_id = entry.document_id
+      JOIN content_revisions revision ON revision.document_id = entry.document_id AND revision.revision_id = entry.revision_id
+      WHERE release.release_id = ? AND release.status IN ('publishing', 'published')
+      ORDER BY entry.document_id`).bind(releaseId).all()).results ?? [];
+        if (!rows.length)
+            return null;
+        const [first] = rows;
+        return {
+            releaseId: first.releaseId, status: first.status, schemaPackageVersion: first.schemaPackageVersion,
+            materializerVersion: first.materializerVersion, manifestChecksum: first.manifestChecksum,
+            entries: rows.map(({ documentId, revisionId, kind, locale, schemaVersion, tombstone, payloadJson, payloadChecksum }) => ({ documentId, revisionId, kind, locale, schemaVersion, tombstone: Boolean(tombstone), payloadJson, payloadChecksum })),
+        };
+    }
+    async save(input) {
+        const existing = await this.db.prepare("SELECT revision_id, request_checksum FROM content_revisions WHERE revision_id = ?").bind(input.revisionId).first();
+        const idempotency = assertIdempotent(existing ? { requestChecksum: existing.request_checksum } : undefined, input.requestChecksum);
+        if (idempotency.kind === "repeat")
+            return "repeated";
+        if ((input.payload === null) === !input.tombstone)
+            throw new Error("invalid_document");
+        const document = await this.db.prepare("SELECT document_id, draft_revision_id, abandoned_at FROM content_documents WHERE document_id = ?").bind(input.documentId).first();
+        if (document && (document.kind !== input.kind || document.locale !== input.locale))
+            throw new Error("invalid_document");
+        const expectedDraftRevisionId = input.expectedDraftRevisionId === undefined ? input.baseRevisionId : input.expectedDraftRevisionId;
+        if (document && document.draft_revision_id !== expectedDraftRevisionId)
+            throw new Error("stale_revision");
+        const payload = input.payload === null ? null : canonicalJson(input.payload);
+        const hasBase = expectedDraftRevisionId !== null;
+        const guard = hasBase ? "draft_revision_id = ?" : "draft_revision_id IS NULL";
+        const createDocument = this.db.prepare(`INSERT INTO content_documents (document_id, kind, locale, translation_group_id, draft_revision_id, created_at, updated_at)
+      SELECT ?, ?, ?, ?, NULL, ?, ? WHERE NOT EXISTS (SELECT 1 FROM content_documents WHERE document_id = ?)`)
+            .bind(input.documentId, input.kind, input.locale, input.translationGroupId ?? null, input.now, input.now, input.documentId);
+        const revision = this.db.prepare(`INSERT INTO content_revisions (revision_id, document_id, base_revision_id, payload_json, is_tombstone, schema_version, payload_checksum, request_checksum, author_subject, author_label, created_at)
+      SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? FROM content_documents WHERE document_id = ? AND ${guard}`)
+            .bind(input.revisionId, input.documentId, input.baseRevisionId, payload, Number(input.tombstone), input.schemaVersion, input.payloadChecksum, input.requestChecksum, input.authorSubject, input.authorLabel, input.now, input.documentId, ...(hasBase ? [expectedDraftRevisionId] : []));
+        const advance = this.db.prepare(`UPDATE content_documents SET draft_revision_id = ?, updated_at = ?, abandoned_at = NULL WHERE document_id = ? AND ${guard}`)
+            .bind(input.revisionId, input.now, input.documentId, ...(hasBase ? [expectedDraftRevisionId] : []));
+        const results = await this.db.batch([createDocument, revision, advance]);
+        if (results[1]?.meta?.changes !== 1 || results[2]?.meta?.changes !== 1)
+            throw new Error("stale_revision");
+        return "created";
+    }
+    async discard(documentId, expectedDraftRevisionId, baselineRevisionId, now) {
+        const expected = expectedDraftRevisionId === null ? "draft_revision_id IS NULL" : "draft_revision_id = ?";
+        const set = baselineRevisionId === null ? null : baselineRevisionId;
+        const update = this.db.prepare(`UPDATE content_documents SET draft_revision_id = ?, abandoned_at = CASE WHEN ? IS NULL THEN ? ELSE NULL END, updated_at = ? WHERE document_id = ? AND ${expected}`)
+            .bind(set, set, now, now, documentId, ...(expectedDraftRevisionId === null ? [] : [expectedDraftRevisionId]));
+        const [result] = await this.db.batch([update]);
+        if (result?.meta?.changes === 1)
+            return;
+        const current = await this.db.prepare("SELECT document_id, draft_revision_id, abandoned_at FROM content_documents WHERE document_id = ?").bind(documentId).first();
+        if (current?.draft_revision_id === baselineRevisionId)
+            return;
+        throw new Error("stale_revision");
+    }
+    async publish(input) {
+        const existing = await this.db.prepare("SELECT release_id, request_checksum, status, base_release_id FROM content_releases WHERE release_id = ?").bind(input.releaseId).first();
+        const idempotency = assertIdempotent(existing ? { requestChecksum: existing.request_checksum } : undefined, input.requestChecksum);
+        if (idempotency.kind === "repeat")
+            return "repeated";
+        const active = await this.db.prepare("SELECT release_id FROM content_releases WHERE active_slot = 1").first();
+        if (active)
+            throw new Error("release_in_progress");
+        const state = await this.db.prepare("SELECT current_release_id FROM content_site_state WHERE singleton = 1").first();
+        if (!state)
+            throw new Error("content_unavailable");
+        const inherited = state.current_release_id
+            ? (await this.db.prepare("SELECT document_id, revision_id FROM content_release_entries WHERE release_id = ?").bind(state.current_release_id).all()).results ?? []
+            : [];
+        const manifest = new Map(inherited.map((entry) => [entry.document_id, entry.revision_id]));
+        const selected = [...input.entries];
+        if (!selected.length)
+            throw new Error("invalid_document");
+        for (const entry of selected)
+            manifest.set(entry.documentId, entry.revisionId);
+        const selectionGuard = selected.map(() => "EXISTS (SELECT 1 FROM content_documents WHERE document_id = ? AND draft_revision_id = ?)").join(" AND ");
+        /* The candidate insert itself is the CAS. If an editor advanced any selected
+         * draft, or another release advanced the base release, it inserts zero rows
+         * and no candidate/entry can be left behind. */
+        const candidate = this.db.prepare(`INSERT INTO content_releases (release_id, base_release_id, request_checksum, status, active_slot, manifest_checksum, schema_package_version, materializer_version, created_by_subject, created_at)
+      SELECT ?, current_release_id, ?, 'publishing', 1, ?, ?, ?, ?, ? FROM content_site_state
+      WHERE singleton = 1 AND current_release_id IS ? AND ${selectionGuard}`)
+            .bind(input.releaseId, input.requestChecksum, input.manifestChecksum, input.schemaPackageVersion, input.materializerVersion, input.authorSubject, input.now, state.current_release_id, ...selected.flatMap((entry) => [entry.documentId, entry.revisionId]));
+        const statements = [candidate];
+        for (const [documentId, revisionId] of manifest)
+            statements.push(this.db.prepare("INSERT INTO content_release_entries (release_id, document_id, revision_id) SELECT ?, ?, ? WHERE EXISTS (SELECT 1 FROM content_revisions WHERE document_id = ? AND revision_id = ?)")
+                .bind(input.releaseId, documentId, revisionId, documentId, revisionId));
+        const results = await this.db.batch(statements);
+        if (results[0]?.meta?.changes !== 1)
+            throw new Error("stale_revision");
+        if (results.slice(1).some((result) => result.meta?.changes !== 1))
+            throw new Error("invalid_document");
+        return "created";
+    }
+    async finalize(releaseId, now) {
+        const release = await this.db.prepare("SELECT release_id, request_checksum, status, base_release_id FROM content_releases WHERE release_id = ?").bind(releaseId).first();
+        if (!release || release.status !== "publishing")
+            throw new Error("release_superseded");
+        const promote = this.db.prepare("UPDATE content_releases SET status = 'published', active_slot = NULL, finished_at = ? WHERE release_id = ? AND status = 'publishing' AND base_release_id IS (SELECT current_release_id FROM content_site_state WHERE singleton = 1)").bind(now, releaseId);
+        const pointer = this.db.prepare("UPDATE content_site_state SET current_release_id = ?, updated_at = ? WHERE singleton = 1 AND EXISTS (SELECT 1 FROM content_releases WHERE release_id = ? AND status = 'published')").bind(releaseId, now, releaseId);
+        const clearMatchingDrafts = this.db.prepare("UPDATE content_documents SET draft_revision_id = NULL, updated_at = ? WHERE draft_revision_id IN (SELECT revision_id FROM content_release_entries WHERE release_id = ?) AND document_id IN (SELECT document_id FROM content_release_entries WHERE release_id = ?)").bind(now, releaseId, releaseId);
+        const results = await this.db.batch([promote, pointer, clearMatchingDrafts]);
+        if (results[0]?.meta?.changes !== 1 || results[1]?.meta?.changes !== 1)
+            throw new Error("release_superseded");
+    }
+}
+/** Pure strict-CAS kernel. The D1 adapter uses these guards around its SQL operations. */
+export class ContentKernel {
+    documents = new Map();
+    revisions = new Map();
+    releases = new Map();
+    currentReleaseId = null;
+    save(revision) {
+        const prior = this.revisions.get(revision.revisionId);
+        const idempotency = assertIdempotent(prior, revision.requestChecksum);
+        if (idempotency.kind === "repeat")
+            return idempotency.value;
+        if ((revision.payload === null) === !revision.tombstone)
+            throw new Error("invalid_document");
+        const document = this.documents.get(revision.documentId) ?? { documentId: revision.documentId, draftRevisionId: null, abandoned: false };
+        if (document.draftRevisionId !== (revision.expectedDraftRevisionId === undefined ? revision.baseRevisionId : revision.expectedDraftRevisionId))
+            throw new Error("stale_revision");
+        this.revisions.set(revision.revisionId, revision);
+        this.documents.set(revision.documentId, { ...document, draftRevisionId: revision.revisionId, abandoned: false });
+        return revision;
+    }
+    discard(documentId, expectedDraftRevisionId, baselineRevisionId) {
+        const document = this.documents.get(documentId);
+        if (!document || document.draftRevisionId === baselineRevisionId)
+            return;
+        if (document.draftRevisionId !== expectedDraftRevisionId)
+            throw new Error("stale_revision");
+        this.documents.set(documentId, { ...document, draftRevisionId: baselineRevisionId, abandoned: baselineRevisionId === null });
+    }
+    publish(releaseId, requestChecksum, entries) {
+        this.createRelease(releaseId, requestChecksum, new Map(entries));
+    }
+    /** Creates the immutable full manifest from the current published release
+     * plus only the explicitly selected current drafts. Other drafts remain
+     * drafts; a candidate never becomes a partial published view by accident. */
+    publishSelected(releaseId, requestChecksum, selected) {
+        const current = this.currentReleaseId ? this.releases.get(this.currentReleaseId) : undefined;
+        const manifest = new Map(current?.entries ?? []);
+        for (const [documentId, revisionId] of selected) {
+            const document = this.documents.get(documentId);
+            if (!document || document.draftRevisionId !== revisionId)
+                throw new Error("stale_revision");
+            manifest.set(documentId, revisionId);
+        }
+        this.createRelease(releaseId, requestChecksum, manifest);
+    }
+    createRelease(releaseId, requestChecksum, manifest) {
+        const existing = this.releases.get(releaseId);
+        const idempotency = assertIdempotent(existing, requestChecksum);
+        if (idempotency.kind === "repeat")
+            return;
+        if ([...this.releases.values()].some((release) => release.status === "publishing"))
+            throw new Error("release_in_progress");
+        for (const [documentId, revisionId] of manifest) {
+            const revision = this.revisions.get(revisionId);
+            if (!revision || revision.documentId !== documentId)
+                throw new Error("invalid_document");
+        }
+        this.releases.set(releaseId, { requestChecksum, baseReleaseId: this.currentReleaseId, status: "publishing", entries: manifest });
+    }
+    finalize(releaseId) {
+        const release = this.releases.get(releaseId);
+        if (!release || release.status !== "publishing")
+            throw new Error("release_superseded");
+        if (release.baseReleaseId !== this.currentReleaseId) {
+            release.status = "superseded";
+            throw new Error("release_superseded");
+        }
+        release.status = "published";
+        this.currentReleaseId = releaseId;
+        for (const [documentId, revisionId] of release.entries) {
+            const document = this.documents.get(documentId);
+            if (document?.draftRevisionId === revisionId)
+                this.documents.set(documentId, { ...document, draftRevisionId: null });
+        }
+    }
+}

package/dist/release.d.ts

@@ -0,0 +1,48 @@
+import { type JsonValue } from "./persistence.js";
+export type ReleaseExportEntry = {
+    documentId: string;
+    revisionId: string;
+    kind: string;
+    locale: string;
+    schemaVersion: number;
+    tombstone: boolean;
+    payload: JsonValue | null;
+    payloadChecksum: string;
+};
+export type ImmutableReleaseExport = {
+    releaseId: string;
+    schemaPackageVersion: string;
+    materializerVersion: string;
+    manifestChecksum: string;
+    entries: readonly ReleaseExportEntry[];
+};
+/** Raw D1 snapshot. The repository returns this exact release only; converting
+ * it to an export revalidates every payload/checksum before a CI consumer sees
+ * it. */
+export type StoredReleaseExport = {
+    releaseId: string;
+    status: "publishing" | "published";
+    schemaPackageVersion: string;
+    materializerVersion: string;
+    manifestChecksum: string;
+    entries: readonly (Omit<ReleaseExportEntry, "payload"> & {
+        payloadJson: string | null;
+    })[];
+};
+/** A release export is an immutable, sorted full snapshot. It is never a
+ * convenience view of current drafts, so a CI attempt can reproduce exactly
+ * what the release candidate promised. */
+export declare function createReleaseExport(input: Omit<ImmutableReleaseExport, "manifestChecksum">): Promise<ImmutableReleaseExport>;
+export declare function releaseExportFromStored(snapshot: StoredReleaseExport): Promise<ImmutableReleaseExport>;
+/** Safe to put in `/.well-known/adminkit-deployment.json`: no payload, D1 id,
+ * release id, or credential appears in the digest or output. */
+export declare function deploymentFingerprint(input: {
+    codeSha: string;
+    manifestChecksum: string;
+    schemaPackageVersion: string;
+    materializerVersion: string;
+}): Promise<{
+    version: 1;
+    fingerprint: string;
+}>;
+export declare function deploymentFingerprintJson(fingerprint: Awaited<ReturnType<typeof deploymentFingerprint>>): string;

package/dist/release.js

@@ -0,0 +1,57 @@
+import { canonicalChecksum, canonicalJson } from "./persistence.js";
+/** A release export is an immutable, sorted full snapshot. It is never a
+ * convenience view of current drafts, so a CI attempt can reproduce exactly
+ * what the release candidate promised. */
+export async function createReleaseExport(input) {
+    if (!input.releaseId || !input.schemaPackageVersion || !input.materializerVersion)
+        throw new Error("invalid_release_export");
+    const entries = [...input.entries].sort((left, right) => left.documentId.localeCompare(right.documentId));
+    if (!entries.length || new Set(entries.map((entry) => entry.documentId)).size !== entries.length)
+        throw new Error("invalid_release_export");
+    for (const entry of entries) {
+        if (!entry.documentId || !entry.revisionId || !entry.kind || !entry.locale || !Number.isInteger(entry.schemaVersion) || entry.schemaVersion < 1) {
+            throw new Error("invalid_release_export");
+        }
+        if ((entry.payload === null) !== entry.tombstone)
+            throw new Error("invalid_release_export");
+        if (entry.payloadChecksum !== await canonicalChecksum(entry.payload))
+            throw new Error("invalid_release_export");
+    }
+    const manifestChecksum = await canonicalChecksum({
+        schemaPackageVersion: input.schemaPackageVersion,
+        materializerVersion: input.materializerVersion,
+        entries: entries.map(({ documentId, revisionId, kind, locale, schemaVersion, tombstone, payloadChecksum }) => ({ documentId, revisionId, kind, locale, schemaVersion, tombstone, payloadChecksum })),
+    });
+    return { ...input, entries, manifestChecksum };
+}
+export async function releaseExportFromStored(snapshot) {
+    const release = await createReleaseExport({
+        releaseId: snapshot.releaseId,
+        schemaPackageVersion: snapshot.schemaPackageVersion,
+        materializerVersion: snapshot.materializerVersion,
+        entries: snapshot.entries.map((entry) => ({
+            documentId: entry.documentId, revisionId: entry.revisionId, kind: entry.kind, locale: entry.locale,
+            schemaVersion: entry.schemaVersion, tombstone: entry.tombstone,
+            payload: entry.payloadJson === null ? null : JSON.parse(entry.payloadJson), payloadChecksum: entry.payloadChecksum,
+        })),
+    });
+    if (release.manifestChecksum !== snapshot.manifestChecksum)
+        throw new Error("invalid_release_export");
+    return release;
+}
+/** Safe to put in `/.well-known/adminkit-deployment.json`: no payload, D1 id,
+ * release id, or credential appears in the digest or output. */
+export async function deploymentFingerprint(input) {
+    if (Object.values(input).some((value) => !value))
+        throw new Error("invalid_fingerprint");
+    const fingerprint = await canonicalChecksum({
+        codeSha: input.codeSha,
+        manifestChecksum: input.manifestChecksum,
+        schemaPackageVersion: input.schemaPackageVersion,
+        materializerVersion: input.materializerVersion,
+    });
+    return { version: 1, fingerprint };
+}
+export function deploymentFingerprintJson(fingerprint) {
+    return canonicalJson(fingerprint);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardinali-studio/adminkit",
-  "version": "2.1.0-rc.4",
+  "version": "2.2.0",
   "type": "module",
   "description": "Motore riusabile di un pannello di amministrazione per siti Hugo su Cloudflare Pages: codec del front matter guidato dallo schema, form React, libreria media su R2. NIENTE di specifico di un sito qui dentro.",
   "license": "UNLICENSED",
@@ -31,13 +31,17 @@
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
     },
+    "./materializer": {
+      "types": "./dist/materializer.d.ts",
+      "default": "./dist/materializer.js"
+    },
     "./functions/*": "./dist/functions/*"
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && cp src/theme.css dist/theme.css && cp src/app/app.css dist/app/app.css && cp -R src/functions dist/functions",
+    "build": "rm -rf dist && tsc -p tsconfig.json && cp src/theme.css dist/theme.css && cp src/app/app.css dist/app/app.css && cp -R src/functions dist/functions && cp -R src/migrations dist/migrations",
     "test": "node --test \"test/*.test.js\"",
     "check": "npm run build && npm test"
   },
@@ -45,6 +49,7 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@cloudflare/pages-plugin-cloudflare-access": "^1",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
@@ -52,8 +57,7 @@
     "react": "^19",
     "react-dom": "^19",
     "react-hook-form": "^7",
-    "zod": "^4",
-    "@cloudflare/pages-plugin-cloudflare-access": "^1"
+    "zod": "^4"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -82,6 +86,7 @@
     }
   },
   "devDependencies": {
+    "@cloudflare/pages-plugin-cloudflare-access": "1.0.5",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
@@ -92,6 +97,7 @@
     "react-dom": "^19.2.8",
     "react-hook-form": "^7.85.0",
     "typescript": "^5.9.3",
+    "wrangler": "4.114.0",
     "zod": "^4.4.3"
   }
 }