@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/src/core/component-sync.ts

@@ -0,0 +1,290 @@
+/** Exact component approvals supplement ordinary pending-text promotion. */
+import {
+  type BentoDoc,
+  canonical,
+  clone,
+  type ComponentCreation,
+  componentProblems,
+  type ComponentProjection,
+  type ProjectState,
+  type ProvenanceMap,
+  StateError,
+  targetKey,
+  validateComponentCreations,
+  validateComponentProjections,
+} from "../state/mod.ts";
+import { componentFrame } from "./component-frames.ts";
+import { fields } from "../state/json.ts";
+import {
+  type ComponentInsertion,
+  componentMarkdown,
+} from "../source/component-insertion.ts";
+export interface ComponentApproval {
+  version: 1;
+  intent: ComponentCreation;
+  operation: ComponentInsertion;
+}
+function fail(code: string, message: string): never {
+  throw new StateError(code, message);
+}
+export function validateComponentApprovals(
+  value: unknown,
+  retirements: unknown,
+  docId: string,
+  projectionRetirements?: ComponentProjection[],
+) {
+  if (value !== undefined) {
+    if (!Array.isArray(value) || !value.length) {
+      fail(
+        "INVALID_APPROVAL",
+        "Component approvals must be a nonempty exact collection.",
+      );
+    }
+    validateComponentCreations(
+      value.map((approval) => approval?.intent),
+      docId,
+    );
+    for (const approval of value as ComponentApproval[]) {
+      if (
+        !approval ||
+        Object.keys(approval).sort().join(",") !== "intent,operation,version" ||
+        approval.version !== 1 ||
+        approval.operation?.id !== approval.intent.id ||
+        approval.operation?.kind !== approval.intent.kind ||
+        approval.operation?.slideId !== approval.intent.slideId ||
+        canonical(
+            approval.operation.fields.map((
+              field,
+            ) => [field.role, field.sourceId]),
+          ) !==
+          canonical(
+            approval.intent.members.map((
+              member,
+            ) => [member.role, member.sourceId]),
+          )
+      ) {
+        fail(
+          "INVALID_APPROVAL",
+          "Component approval does not identify its exact authored roles.",
+        );
+      }
+      componentMarkdown(approval.operation);
+    }
+  }
+  if (retirements !== undefined) {
+    validateComponentCreations(retirements, docId);
+    if (
+      !(retirements as ComponentCreation[]).length ||
+      (retirements as ComponentCreation[]).some((retired) =>
+        (value as ComponentApproval[] | undefined)?.some((approval) =>
+          approval.intent.id === retired.id
+        )
+      )
+    ) {
+      fail(
+        "INVALID_APPROVAL",
+        "Component retirement overlaps its source acquisition.",
+      );
+    }
+  }
+  if (projectionRetirements !== undefined) {
+    validateComponentProjections(projectionRetirements, [
+      ...(value as ComponentApproval[] | undefined)?.map((approval) =>
+        approval.intent
+      ) ?? [],
+      ...(retirements as ComponentCreation[] | undefined) ?? [],
+    ]);
+    if (!projectionRetirements.length) {
+      fail(
+        "INVALID_APPROVAL",
+        "Projection retirement must be a nonempty exact collection.",
+      );
+    }
+  }
+}
+/** Compare approved metadata before consuming any text/background. No ID-only promotion. */
+export function prepareComponentApprovals(
+  state: ProjectState,
+  generated: BentoDoc,
+  sourceHash: string,
+  approvals: ComponentApproval[] = [],
+  retirements: ComponentCreation[] = [],
+  freshProvenance?: ProvenanceMap,
+  projectionRetirements: ComponentProjection[] = [],
+): ProjectState {
+  const prepared = clone(state);
+  for (
+    const expected of [
+      ...approvals.map((approval) => approval.intent),
+      ...retirements,
+    ]
+  ) {
+    if (
+      canonical(
+        state.componentCreations?.find((intent) => intent.id === expected.id),
+      ) !== canonical(expected)
+    ) {
+      fail(
+        "STALE_APPROVAL",
+        "A component's saved membership or member snapshots changed after source synchronization; preserve and review it.",
+      );
+    }
+  }
+  for (const record of projectionRetirements) {
+    if (
+      canonical(
+          state.componentProjections?.find((item) => item.id === record.id),
+        ) !== canonical(record) ||
+      generated.slides.some((slide) => slide.id === record.slideId)
+    ) {
+      fail(
+        "STALE_APPROVAL",
+        "Retained projection retires only with its exact approved record and fresh parent deletion proof.",
+      );
+    }
+    prepared.componentProjections = prepared.componentProjections?.filter((
+      item,
+    ) => item.id !== record.id);
+  }
+  for (const intent of retirements) {
+    if (generated.slides.some((slide) => slide.id === intent.slideId)) {
+      fail(
+        "STALE_APPROVAL",
+        "Fresh execution must omit the exact approved parent slide before retiring its pending component.",
+      );
+    }
+    prepared.componentCreations = prepared.componentCreations?.filter((item) =>
+      item.id !== intent.id
+    );
+  }
+  for (const { intent, operation } of approvals) {
+    if (componentProblems(state, intent).length) {
+      fail(
+        "STALE_APPROVAL",
+        "Approved component no longer has its exact saved members and background.",
+      );
+    }
+    const slide = generated.slides.find((slide) => slide.id === intent.slideId);
+    const wrapper = componentMarkdown(operation);
+    // Both source hash and fresh source role proof are mandatory; input provenance is insufficient.
+    const background = slide?.elements.find((element) =>
+      element.id === intent.backgroundId
+    );
+    const proof = freshProvenance
+      ?.[
+        targetKey({ slideId: intent.slideId, elementId: intent.backgroundId })
+      ];
+    if (
+      !background ||
+      canonical(componentFrame(background)) !==
+        canonical(intent.projectionFrame) ||
+      background.type !== "shape" ||
+      background.shape !== "rect" || background.groupId !== intent.id ||
+      proof?.origin !== "authored" || proof.semanticId !== intent.id ||
+      proof.source?.hash !== sourceHash || proof.source?.kind !== "div" ||
+      proof.source?.blockId !== intent.id || proof.source?.stable !== true ||
+      String(proof.source?.content).replace(/\r\n/g, "\n") !==
+        wrapper.slice(wrapper.indexOf("\n") + 1, wrapper.lastIndexOf("::::"))
+    ) {
+      fail(
+        "COMPONENT_PROMOTION_PROOF",
+        "Fresh execution must prove the exact identified component and generated design-only background before consuming its pending design.",
+      );
+    }
+    for (const member of intent.members) {
+      const roleProof = freshProvenance
+        ?.[targetKey({ slideId: intent.slideId, elementId: member.nativeId })];
+      const element = slide?.elements.find((element) =>
+        element.id === member.nativeId
+      );
+      if (
+        !element || element.type !== "text" ||
+        roleProof?.origin !== "authored" ||
+        roleProof.semanticId !== member.nativeId ||
+        roleProof.source?.hash !== sourceHash ||
+        roleProof.source?.blockId !== member.nativeId ||
+        roleProof.source?.kind !==
+          (member.role === "title" ? "heading" : "paragraph") ||
+        (member.role !== "title" &&
+          (roleProof.source?.parentId !== member.sourceId ||
+            roleProof.source?.siblings !== 1))
+      ) {
+        fail(
+          "COMPONENT_PROMOTION_PROOF",
+          "Fresh execution must prove every authored role, source binding and native ID; computed substitutions cannot acquire an authored component.",
+        );
+      }
+    }
+    const saved = state.bentoOnly.find((item) =>
+      item.slideId === intent.slideId && item.element.id === intent.backgroundId
+    );
+    if (
+      !saved ||
+      canonical(saved.element) !== canonical(intent.backgroundSnapshot)
+    ) {
+      fail(
+        "STALE_APPROVAL",
+        "The approved pending background snapshot is no longer the saved decoration.",
+      );
+    }
+    const target = { slideId: intent.slideId, elementId: intent.backgroundId };
+    for (const field of fields(background, saved.element, ["id"])) {
+      let overlay = prepared.overrides.find((item) =>
+        canonical(item.target) === canonical(target)
+      );
+      if (!overlay) {
+        overlay = { target, fields: [] };
+        prepared.overrides.push(overlay);
+      }
+      overlay.fields = overlay.fields.filter((item) =>
+        canonical(item.path) !== canonical(field.path)
+      );
+      overlay.fields.push(clone(field));
+    }
+    // Persist the approved measurement bootstrap, never the saved decorative frame.
+    (prepared.componentProjections ??= []).push({
+      version: 1,
+      id: intent.id,
+      kind: intent.kind,
+      slideId: intent.slideId,
+      frame: clone(intent.projectionFrame),
+    });
+    // The native background placement is a visual override applied only by compose.
+    for (
+      const native of [
+        saved.element,
+        ...intent.members.map((member) => member.snapshot),
+      ]
+    ) {
+      const memberTarget = { slideId: intent.slideId, elementId: native.id };
+      let frameOverlay = prepared.overrides.find((item) =>
+        canonical(item.target) === canonical(memberTarget)
+      );
+      if (!frameOverlay) {
+        frameOverlay = { target: memberTarget, fields: [] };
+        prepared.overrides.push(frameOverlay);
+      }
+      for (const path of ["x", "y", "w", "h"]) {
+        frameOverlay.fields = frameOverlay.fields.filter((field) =>
+          canonical(field.path) !== canonical([path])
+        );
+        frameOverlay.fields.push({
+          path: [path],
+          value: { present: true, value: native[path] },
+        });
+      }
+    }
+    prepared.bentoOnly = prepared.bentoOnly.filter((item) =>
+      !(item.slideId === intent.slideId &&
+        item.element.id === intent.backgroundId)
+    );
+    prepared.componentCreations = prepared.componentCreations?.filter((item) =>
+      item.id !== intent.id
+    );
+  }
+  if (!prepared.componentCreations?.length) delete prepared.componentCreations;
+  if (!prepared.componentProjections?.length) {
+    delete prepared.componentProjections;
+  }
+  return prepared;
+}

package/distribution/runtime/src/core/design-diagnostics.ts

@@ -0,0 +1,78 @@
+/** Observed original-QMD design traces, never a claim of historical restoration. */
+import type { Diagnostic } from "../render/types.ts";
+import type { DesignDefaults } from "../render/design.ts";
+import type { ProjectState } from "../state/mod.ts";
+import { type SourceDocument, SourceError } from "../source/mod.ts";
+import { readDesignAnnotations } from "../source/annotations.ts";
+import { annotationRequests } from "./annotations.ts";
+
+/** Pure reevaluation keeps an empty newly rendered baseline from hiding lost design. */
+export function missingDesignDiagnostics(
+  document: SourceDocument,
+  state: ProjectState | null | undefined,
+  registry: { defaults: DesignDefaults; hash: string | null },
+): Diagnostic[] {
+  let traces;
+  try {
+    traces = readDesignAnnotations(document);
+  } catch (error) {
+    if (!(error instanceof SourceError)) throw error;
+    return [{
+      code: "UNVERIFIABLE_DESIGN_ANNOTATION",
+      reference: ".qbento/",
+      message:
+        `An original QMD design trace cannot be verified: ${error.message} Preserve the QMD and restore .qbento/ from Git or backup, or explicitly reconcile the trace. Rendering a base deck does not recover its historical visual design.`,
+    }];
+  }
+  const creations =
+    state?.pending.filter((p) =>
+      ["create-slide", "create-element"].includes(p.kind)
+    ).map((p) => p.id) ?? [];
+  const requests = annotationRequests(document, state, creations, {
+    hash: registry.hash,
+    ...(registry.defaults.theme
+      ? { activeTheme: "validated-active-theme" }
+      : {}),
+    layouts: Object.keys(registry.defaults.layouts ?? {}),
+  });
+  const diagnostics: Diagnostic[] = [];
+  for (const trace of traces) {
+    const request = requests.find((r) => r.slideId === trace.slideId);
+    const missing = trace.references
+      ? trace.references.flatMap((reference) => {
+        const categories = reference === ".qbento/design.json"
+          ? ["theme", "layout"]
+          : ["overrides", "decorations", "stacking", "created-design"];
+        const declared = trace.features!.filter((feature) =>
+          categories.includes(feature)
+        );
+        const absent = declared.filter((feature) => {
+          if (request?.features.includes(feature)) return false;
+          // Approved creations become ordinary sparse visual effects after promotion.
+          // This checks current availability, never proof of historical identity/approval.
+          return feature !== "created-design" || !request?.features.some((f) =>
+            ["overrides", "decorations", "stacking"].includes(f)
+          );
+        });
+        return !request?.references.includes(reference) || !declared.length ||
+            absent.length
+          ? [{ reference, features: absent }]
+          : [];
+      })
+      : request
+      ? []
+      : [{ reference: ".qbento/", features: [] }];
+    for (const { reference, features } of missing) {
+      diagnostics.push({
+        code: "MISSING_DESIGN",
+        slideId: trace.slideId,
+        reference,
+        message:
+          `Slide ${trace.slideId} retains a QMD design trace for ${reference}, but corresponding recoverable external design is missing${
+            features.length ? ` (${features.join(", ")})` : ""
+          }. Restore ${reference} from Git or backup, then render again; or explicitly review and resolve the obsolete trace through approved sync. The QMD is unchanged. A base deck or newly saved design is not proof that the historical visual design was recovered.`,
+      });
+    }
+  }
+  return diagnostics;
+}

package/distribution/runtime/src/core/design-registry.ts

@@ -0,0 +1,287 @@
+import { resolve } from "node:path";
+import {
+  assertDesignRegistryUnchanged,
+  type DesignRegistry,
+  MAX_DESIGN_REGISTRY_BYTES,
+  readDesignRegistry,
+  validateDesignRegistry,
+} from "../render/registry.ts";
+import { sha256, StateError } from "../state/mod.ts";
+import { withProject } from "./project.ts";
+import { syncDirectory, writeDurable } from "./io.ts";
+
+export interface RegistryEditRequest {
+  expectedDocId: string;
+  expectedRevision: number;
+  expectedHash: string | null;
+  registry: DesignRegistry;
+}
+export async function readProjectRegistry(source: string) {
+  return await withProject(source, async (paths, store) => {
+    const state = await store.load();
+    if (!state) {
+      throw new StateError("NO_BASELINE", "Render the project first.");
+    }
+    return {
+      ...await readDesignRegistry(paths.directory),
+      docId: state.docId,
+      revision: state.revision,
+    };
+  });
+}
+function requestShape(request: RegistryEditRequest) {
+  if (
+    !request || typeof request !== "object" || Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !==
+      "expectedDocId,expectedHash,expectedRevision,registry" ||
+    typeof request.expectedDocId !== "string" || !request.expectedDocId ||
+    !Number.isSafeInteger(request.expectedRevision) ||
+    request.expectedRevision < 0 ||
+    !(request.expectedHash === null ||
+      typeof request.expectedHash === "string" &&
+        /^[a-f0-9]{64}$/.test(request.expectedHash))
+  ) {
+    throw new StateError(
+      "INVALID_REGISTRY_EDIT",
+      "Registry edits require the saved document identity, revision and exact registry hash.",
+    );
+  }
+}
+async function exists(path: string) {
+  try {
+    await Deno.lstat(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) return false;
+    throw error;
+  }
+}
+/** No state, output or QMD write. Existing bytes and candidate stay recoverable. */
+export async function saveProjectRegistry(
+  source: string,
+  request: RegistryEditRequest,
+) {
+  requestShape(request);
+  const registry = validateDesignRegistry(request.registry);
+  const text = JSON.stringify(registry, null, 2) + "\n";
+  if (new TextEncoder().encode(text).length > MAX_DESIGN_REGISTRY_BYTES) {
+    throw new StateError(
+      "DESIGN_REGISTRY_TOO_LARGE",
+      "Registry exceeds 256 KiB.",
+    );
+  }
+  return await withProject(source, async (paths, store) => {
+    const state = await store.load();
+    if (!state) {
+      throw new StateError("NO_BASELINE", "Render the project first.");
+    }
+    if (state.docId !== request.expectedDocId) {
+      throw new StateError(
+        "DOC_ID_CHANGED",
+        "Reload this project before saving its registry.",
+      );
+    }
+    if (state.revision !== request.expectedRevision) {
+      throw new StateError(
+        "STALE_REVISION",
+        "Another save changed the project. Reload before saving its registry.",
+      );
+    }
+    await readDesignRegistry(paths.directory); // Refuse invalid/unknown current schema, never replace it silently.
+    await assertDesignRegistryUnchanged(paths.directory, request.expectedHash);
+    const history = resolve(paths.stateDir, "history");
+    await Deno.mkdir(history, { recursive: true });
+    const info = await Deno.lstat(history);
+    if (info.isSymlink || !info.isDirectory) {
+      throw new StateError(
+        "UNSAFE_DESIGN_REGISTRY",
+        "Registry history must be a real directory.",
+      );
+    }
+    const token = crypto.randomUUID();
+    const transaction = resolve(history, "design-" + token);
+    await Deno.mkdir(transaction);
+    await syncDirectory(history);
+    const before = resolve(transaction, "before.json"),
+      after = resolve(transaction, "after.json");
+    const stage = resolve(paths.stateDir, ".design-stage-" + token + ".json");
+    const target = resolve(paths.stateDir, "design.json");
+    const marker = resolve(paths.stateDir, "design-save.json");
+    const hash = await sha256(text);
+    await writeDurable(after, text);
+    await writeDurable(stage, text);
+    await writeDurable(
+      resolve(transaction, "receipt.json"),
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          docId: state.docId,
+          revision: state.revision,
+          beforeHash: request.expectedHash,
+          afterHash: hash,
+          stage,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    await syncDirectory(transaction);
+    // Probe the filesystem capability while the original target is still intact.
+    const probe = resolve(paths.stateDir, ".design-link-probe-" + token);
+    await Deno.link(stage, probe);
+    await Deno.remove(probe);
+    await syncDirectory(paths.stateDir);
+    let moved = false, published = false, marked = false;
+
+    try {
+      await assertDesignRegistryUnchanged(
+        paths.directory,
+        request.expectedHash,
+      );
+      await writeDurable(
+        marker,
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            token,
+            transaction,
+            stage,
+            beforeHash: request.expectedHash,
+            afterHash: hash,
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+      marked = true;
+      await syncDirectory(paths.stateDir);
+      await assertDesignRegistryUnchanged(
+        paths.directory,
+        request.expectedHash,
+        token,
+      );
+      if (request.expectedHash !== null) {
+        await Deno.rename(target, before);
+        moved = true;
+        await syncDirectory(transaction);
+        await syncDirectory(paths.stateDir);
+        const previous = await Deno.lstat(before);
+        if (
+          !previous.isFile || previous.isSymlink ||
+          previous.nlink !== null && previous.nlink > 1 ||
+          previous.size > MAX_DESIGN_REGISTRY_BYTES
+        ) {
+          throw new StateError(
+            "DESIGN_REGISTRY_CHANGED",
+            "Registry path changed while preparing its save.",
+          );
+        }
+        if (
+          await sha256(await Deno.readFile(before)) !== request.expectedHash
+        ) {
+          throw new StateError(
+            "DESIGN_REGISTRY_CHANGED",
+            "Registry bytes changed while preparing its save.",
+          );
+        }
+      }
+      // Atomic create-if-absent publication, unlike rename-overwrite. A writer
+      // outside the project lock cannot have its replacement silently removed.
+      await Deno.link(stage, target);
+      published = true;
+      await Deno.remove(stage);
+      await syncDirectory(paths.stateDir);
+      await assertDesignRegistryUnchanged(paths.directory, hash, token);
+      await writeDurable(
+        resolve(transaction, "committed.json"),
+        JSON.stringify({ hash }) + "\n",
+      );
+      await syncDirectory(transaction);
+      await Deno.remove(marker);
+      marked = false;
+      await syncDirectory(paths.stateDir);
+    } catch (error) {
+      if (published) {
+        throw new StateError(
+          "REGISTRY_SAVED_RECOVERY_REQUIRED",
+          `Registry publication occurred but final verification/durability failed. Preserve the registry and recovery files at ${transaction}. ${
+            (error as Error).message
+          }`,
+        );
+      }
+      let restored = !moved;
+      if (moved && !await exists(target)) {
+        try {
+          const original = await Deno.lstat(before);
+          if (!original.isFile || original.isSymlink) {
+            throw new Error("Retained path is not a regular file");
+          }
+          // Keep before.json immutable: a concurrent editor may replace the
+          // restored target immediately after publication.
+          const rollbackStage = resolve(
+            paths.stateDir,
+            ".design-stage-" + token + "-rollback.json",
+          );
+          const originalBytes = await Deno.readFile(before);
+          if (await sha256(originalBytes) !== request.expectedHash) {
+            throw new Error("Retained original bytes changed");
+          }
+          const rollbackFile = await Deno.open(rollbackStage, {
+            createNew: true,
+            write: true,
+            mode: 0o600,
+          });
+          try {
+            let offset = 0;
+            while (offset < originalBytes.length) {
+              offset += await rollbackFile.write(
+                originalBytes.subarray(offset),
+              );
+            }
+            await rollbackFile.sync();
+          } finally {
+            rollbackFile.close();
+          }
+          await syncDirectory(paths.stateDir);
+          await Deno.link(rollbackStage, target); // Atomic create, never overwrite.
+          await Deno.remove(rollbackStage);
+          await syncDirectory(paths.stateDir);
+          await assertDesignRegistryUnchanged(
+            paths.directory,
+            request.expectedHash,
+            token,
+          );
+          restored = true;
+        } catch (restoreError) {
+          throw new StateError(
+            "DESIGN_REGISTRY_RECOVERY_REQUIRED",
+            `Registry save refused; existing bytes and candidate remain at ${transaction}. A concurrent replacement is never overwritten. ${
+              (restoreError as Error).message
+            }`,
+          );
+        }
+      }
+      if (!restored) {
+        throw new StateError(
+          "DESIGN_REGISTRY_RECOVERY_REQUIRED",
+          `Registry save refused and a concurrent replacement was preserved. Inspect ${marker} and ${transaction} before continuing.`,
+        );
+      }
+      if (marked) {
+        await Deno.remove(marker);
+        await syncDirectory(paths.stateDir);
+      }
+      if (
+        error instanceof Deno.errors.AlreadyExists ||
+        error instanceof Deno.errors.NotFound
+      ) {
+        throw new StateError(
+          "DESIGN_REGISTRY_CHANGED",
+          "Registry changed during publication; retry from a fresh snapshot. Recovery files were retained.",
+        );
+      }
+      throw error;
+    }
+    return { registry, hash, docId: state.docId, revision: state.revision };
+  });
+}