@opengeni/core 0.21.2 → 0.24.1

package/src/domain/editable-artifacts/snapshot-compaction.ts

@@ -0,0 +1,246 @@
+import { type BoundedImmutableObjectWritePort, BoundedObjectWriteError } from "@opengeni/storage";
+
+import type { EditableArtifactCompactionPort, EditableArtifactKernelState } from "./ports";
+import {
+  MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES,
+  EditableArtifactSnapshotVerificationError,
+} from "./snapshot-verifier";
+import {
+  assertBoundedKernelVersion,
+  causalFrontiersEqual,
+  editableArtifactCausalFrontier,
+  editableArtifactContentHash,
+  editableArtifactId,
+  editableArtifactScope,
+  editableArtifactSnapshotId,
+  editableArtifactStateHash,
+  type EditableArtifactCausalFrontier,
+  type EditableArtifactContentHash,
+  type EditableArtifactId,
+  type EditableArtifactModality,
+  type EditableArtifactScope,
+  type EditableArtifactStateHash,
+  type PublishEditableArtifactSnapshotRequest,
+} from "./types";
+
+const SNAPSHOT_MIME_TYPE = "application/vnd.opengeni.editable-artifact-snapshot" as const;
+
+type AuthoritativeEditableArtifactCompactionKernelResultCommon = Readonly<{
+  scope: EditableArtifactScope;
+  artifactId: EditableArtifactId;
+  modality: EditableArtifactModality;
+  canonicalChunks: AsyncIterable<Uint8Array>;
+  canonicalByteSize: number;
+  canonicalContentHash: EditableArtifactContentHash;
+  stateHash: EditableArtifactStateHash;
+  coveredHeadSequence: number;
+  modelSchemaVersion: number;
+  kernelVersion: string;
+}>;
+
+export type AuthoritativeEditableArtifactCompactionKernelResult =
+  | (AuthoritativeEditableArtifactCompactionKernelResultCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        coveredCausalFrontier: EditableArtifactCausalFrontier;
+        operationProtocolVersion: number;
+        crdtStateVersion: number;
+      }>)
+  | (AuthoritativeEditableArtifactCompactionKernelResultCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        nativeRevision: number;
+      }>);
+
+/** Native authority that replays one detached durable basis without network access. */
+export interface AuthoritativeEditableArtifactCompactionKernelPort {
+  createCanonicalSnapshot(input: {
+    state: EditableArtifactKernelState;
+    signal?: AbortSignal;
+  }): Promise<AuthoritativeEditableArtifactCompactionKernelResult>;
+}
+
+export type EditableArtifactCompactionPipelineDependencies = Readonly<{
+  kernel: AuthoritativeEditableArtifactCompactionKernelPort;
+  objects: BoundedImmutableObjectWritePort;
+  now: () => Date;
+  maxSnapshotBytes?: number;
+}>;
+
+/** Reconstruct, canonicalize, and upload an exact-head state-neutral snapshot. */
+export class EditableArtifactCompactionPipeline implements EditableArtifactCompactionPort {
+  readonly #dependencies: Readonly<{
+    kernel: AuthoritativeEditableArtifactCompactionKernelPort;
+    objects: BoundedImmutableObjectWritePort;
+    now: () => Date;
+    maxSnapshotBytes: number;
+  }>;
+
+  constructor(dependencies: EditableArtifactCompactionPipelineDependencies) {
+    const maxSnapshotBytes = dependencies.maxSnapshotBytes ?? MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES;
+    if (
+      !Number.isSafeInteger(maxSnapshotBytes) ||
+      maxSnapshotBytes <= 0 ||
+      maxSnapshotBytes > MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES
+    ) {
+      throw new TypeError("Compaction snapshot limit is invalid");
+    }
+    this.#dependencies = Object.freeze({ ...dependencies, maxSnapshotBytes });
+  }
+
+  async prepare(
+    input: Parameters<EditableArtifactCompactionPort["prepare"]>[0],
+  ): Promise<PublishEditableArtifactSnapshotRequest> {
+    const scope = editableArtifactScope(input.scope);
+    const artifactId = editableArtifactId(input.artifactId);
+    const snapshotId = editableArtifactSnapshotId(input.snapshotId);
+    validateBasis(input.state, scope, artifactId);
+    throwIfCancelled(input.signal);
+    try {
+      const generated = await this.#dependencies.kernel.createCanonicalSnapshot({
+        state: input.state,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+      validateGenerated(generated, input.state, scope, artifactId);
+      const stored = await this.#dependencies.objects.write({
+        chunks: generated.canonicalChunks,
+        contentType: SNAPSHOT_MIME_TYPE,
+        maxBytes: this.#dependencies.maxSnapshotBytes,
+        expectedByteSize: generated.canonicalByteSize,
+        expectedContentHash: generated.canonicalContentHash,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+      const common = {
+        snapshotId,
+        blobReference: stored.opaqueReference,
+        byteSize: stored.byteSize,
+        contentHash: editableArtifactContentHash(stored.contentHash),
+        mimeType: SNAPSHOT_MIME_TYPE,
+        modality: generated.modality,
+        coveredHeadSequence: generated.coveredHeadSequence,
+        stateHash: generated.stateHash,
+        modelSchemaVersion: generated.modelSchemaVersion,
+        kernelVersion: generated.kernelVersion,
+        verifiedAt: canonicalTimestamp(this.#dependencies.now()),
+      } as const;
+      return generated.modality === "spreadsheet"
+        ? Object.freeze({
+            ...common,
+            modality: generated.modality,
+            coveredCausalFrontier: generated.coveredCausalFrontier,
+            operationProtocolVersion: generated.operationProtocolVersion,
+            crdtStateVersion: generated.crdtStateVersion,
+          })
+        : Object.freeze({
+            ...common,
+            modality: generated.modality,
+            nativeRevision: generated.nativeRevision,
+          });
+    } catch (error) {
+      if (
+        error instanceof EditableArtifactSnapshotVerificationError ||
+        error instanceof BoundedObjectWriteError
+      ) {
+        throw error;
+      }
+      if (input.signal?.aborted) {
+        throw new EditableArtifactSnapshotVerificationError("cancelled");
+      }
+      throw new EditableArtifactSnapshotVerificationError("kernel_rejected");
+    }
+  }
+}
+
+function validateBasis(
+  state: EditableArtifactKernelState,
+  scope: EditableArtifactScope,
+  artifactId: EditableArtifactId,
+): void {
+  if (
+    state.artifact.scope.accountId !== scope.accountId ||
+    state.artifact.scope.workspaceId !== scope.workspaceId ||
+    state.artifact.id !== artifactId ||
+    state.artifact.modality !== state.modality
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("identity_mismatch");
+  }
+  for (const value of [state.tailTransactionCount, state.tailByteSize]) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new EditableArtifactSnapshotVerificationError("coverage_mismatch");
+    }
+  }
+}
+
+function validateGenerated(
+  value: AuthoritativeEditableArtifactCompactionKernelResult,
+  state: EditableArtifactKernelState,
+  scope: EditableArtifactScope,
+  artifactId: EditableArtifactId,
+): void {
+  if (
+    value.scope.accountId !== scope.accountId ||
+    value.scope.workspaceId !== scope.workspaceId ||
+    value.artifactId !== artifactId ||
+    value.modality !== state.modality
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("identity_mismatch");
+  }
+  if (
+    value.coveredHeadSequence !== state.artifact.headSequence ||
+    editableArtifactStateHash(value.stateHash) !== state.artifact.stateHash ||
+    (value.modality === "spreadsheet" &&
+      (state.modality !== "spreadsheet" ||
+        !causalFrontiersEqual(
+          editableArtifactCausalFrontier(value.coveredCausalFrontier),
+          state.artifact.causalFrontier,
+        ))) ||
+    (value.modality !== "spreadsheet" &&
+      (state.modality === "spreadsheet" || value.nativeRevision !== expectedNativeRevision(state)))
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("coverage_mismatch");
+  }
+  if (
+    !Number.isSafeInteger(value.canonicalByteSize) ||
+    value.canonicalByteSize <= 0 ||
+    value.canonicalByteSize > MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("limit_exceeded");
+  }
+  editableArtifactContentHash(value.canonicalContentHash);
+  const versions =
+    value.modality === "spreadsheet"
+      ? [value.modelSchemaVersion, value.operationProtocolVersion, value.crdtStateVersion]
+      : [value.modelSchemaVersion];
+  if (versions.some((version) => !Number.isSafeInteger(version) || version <= 0)) {
+    throw new EditableArtifactSnapshotVerificationError("version_mismatch");
+  }
+  try {
+    assertBoundedKernelVersion(value.kernelVersion);
+  } catch {
+    throw new EditableArtifactSnapshotVerificationError("version_mismatch");
+  }
+  if (!value.canonicalChunks || typeof value.canonicalChunks[Symbol.asyncIterator] !== "function") {
+    throw new EditableArtifactSnapshotVerificationError("kernel_rejected");
+  }
+}
+
+function expectedNativeRevision(
+  state: Extract<EditableArtifactKernelState, { modality: "document" | "presentation" }>,
+): number {
+  return (
+    state.committedTransactionTail.at(-1)?.nativeRevision ??
+    state.snapshot?.nativeRevision ??
+    state.baseNativeRevision
+  );
+}
+
+function canonicalTimestamp(value: Date): string {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError("Compaction verification clock returned an invalid date");
+  }
+  return value.toISOString();
+}
+
+function throwIfCancelled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new EditableArtifactSnapshotVerificationError("cancelled");
+}

package/src/domain/editable-artifacts/snapshot-verifier-genesis.ts

@@ -0,0 +1,235 @@
+import { type BoundedImmutableObjectWritePort, BoundedObjectWriteError } from "@opengeni/storage";
+import type { EditableArtifactGenesisPort } from "./ports";
+import {
+  MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES,
+  EditableArtifactSnapshotVerificationError,
+} from "./snapshot-verifier";
+import {
+  editableArtifactCausalFrontier,
+  assertBoundedKernelVersion,
+  editableArtifactContentHash,
+  editableArtifactId,
+  editableArtifactScope,
+  editableArtifactSnapshotId,
+  editableArtifactStateHash,
+  type EditableArtifactCausalFrontier,
+  type EditableArtifactContentHash,
+  type EditableArtifactId,
+  type EditableArtifactModality,
+  type EditableArtifactScope,
+  type EditableArtifactStateHash,
+  type PublishEditableArtifactSnapshotRequest,
+} from "./types";
+
+const SNAPSHOT_MIME_TYPE = "application/vnd.opengeni.editable-artifact-snapshot" as const;
+
+type AuthoritativeEditableArtifactGenesisKernelResultCommon = Readonly<{
+  scope: EditableArtifactScope;
+  artifactId: EditableArtifactId;
+  modality: EditableArtifactModality;
+  canonicalChunks: AsyncIterable<Uint8Array>;
+  canonicalByteSize: number;
+  canonicalContentHash: EditableArtifactContentHash;
+  stateHash: EditableArtifactStateHash;
+  coveredHeadSequence: 0;
+  modelSchemaVersion: number;
+  kernelVersion: string;
+}>;
+
+export type AuthoritativeEditableArtifactGenesisKernelResult =
+  | (AuthoritativeEditableArtifactGenesisKernelResultCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        coveredCausalFrontier: EditableArtifactCausalFrontier;
+        operationProtocolVersion: number;
+        crdtStateVersion: number;
+      }>)
+  | (AuthoritativeEditableArtifactGenesisKernelResultCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        nativeRevision: 0;
+      }>);
+
+/** Trusted no-network native-kernel subprocess; never an HTTP request adapter. */
+export interface AuthoritativeEditableArtifactGenesisKernelPort {
+  createCanonicalEmptySnapshot(input: {
+    scope: EditableArtifactScope;
+    artifactId: EditableArtifactId;
+    modality: EditableArtifactModality;
+    signal?: AbortSignal;
+  }): Promise<AuthoritativeEditableArtifactGenesisKernelResult>;
+}
+
+export type EditableArtifactGenesisPipelineDependencies = Readonly<{
+  kernel: AuthoritativeEditableArtifactGenesisKernelPort;
+  objects: BoundedImmutableObjectWritePort;
+  now: () => Date;
+  maxSnapshotBytes?: number;
+}>;
+
+/**
+ * Creates the only legal sequence-zero candidate. The domain service passes
+ * the result through its unchanged snapshot verifier, then commits artifact +
+ * checkpoint-0 + snapshot + blob-ref + receipt + outbox atomically.
+ */
+export class EditableArtifactGenesisPipeline implements EditableArtifactGenesisPort {
+  readonly #dependencies: Readonly<{
+    kernel: AuthoritativeEditableArtifactGenesisKernelPort;
+    objects: BoundedImmutableObjectWritePort;
+    now: () => Date;
+    maxSnapshotBytes: number;
+  }>;
+
+  constructor(dependencies: EditableArtifactGenesisPipelineDependencies) {
+    const maxSnapshotBytes = dependencies.maxSnapshotBytes ?? MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES;
+    if (
+      !Number.isSafeInteger(maxSnapshotBytes) ||
+      maxSnapshotBytes <= 0 ||
+      maxSnapshotBytes > MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES
+    ) {
+      throw new TypeError("Genesis snapshot limit is invalid");
+    }
+    this.#dependencies = Object.freeze({
+      kernel: dependencies.kernel,
+      objects: dependencies.objects,
+      now: dependencies.now,
+      maxSnapshotBytes,
+    });
+  }
+
+  async prepare(
+    input: Parameters<EditableArtifactGenesisPort["prepare"]>[0],
+  ): Promise<PublishEditableArtifactSnapshotRequest> {
+    const scope = editableArtifactScope(input.scope);
+    const artifactId = editableArtifactId(input.artifactId);
+    const snapshotId = editableArtifactSnapshotId(input.snapshotId);
+    if (!isModality(input.modality)) {
+      throw new TypeError("Genesis modality is invalid");
+    }
+    throwIfGenesisCancelled(input.signal);
+    try {
+      const generated = await this.#dependencies.kernel.createCanonicalEmptySnapshot({
+        scope,
+        artifactId,
+        modality: input.modality,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+      validateGeneratedGenesis(generated, scope, artifactId, input.modality);
+      const stored = await this.#dependencies.objects.write({
+        chunks: generated.canonicalChunks,
+        contentType: SNAPSHOT_MIME_TYPE,
+        maxBytes: this.#dependencies.maxSnapshotBytes,
+        expectedByteSize: generated.canonicalByteSize,
+        expectedContentHash: generated.canonicalContentHash,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+      const verifiedAt = canonicalTimestamp(this.#dependencies.now());
+      const common = {
+        snapshotId,
+        blobReference: stored.opaqueReference,
+        byteSize: stored.byteSize,
+        contentHash: editableArtifactContentHash(stored.contentHash),
+        mimeType: SNAPSHOT_MIME_TYPE,
+        modality: generated.modality,
+        coveredHeadSequence: 0,
+        stateHash: generated.stateHash,
+        modelSchemaVersion: generated.modelSchemaVersion,
+        kernelVersion: generated.kernelVersion,
+        verifiedAt,
+      } as const;
+      return generated.modality === "spreadsheet"
+        ? Object.freeze({
+            ...common,
+            modality: "spreadsheet" as const,
+            coveredCausalFrontier: editableArtifactCausalFrontier([]),
+            operationProtocolVersion: generated.operationProtocolVersion,
+            crdtStateVersion: generated.crdtStateVersion,
+          })
+        : Object.freeze({
+            ...common,
+            modality: generated.modality,
+            nativeRevision: generated.nativeRevision,
+          });
+    } catch (error) {
+      if (
+        error instanceof EditableArtifactSnapshotVerificationError ||
+        error instanceof BoundedObjectWriteError
+      ) {
+        throw error;
+      }
+      if (input.signal?.aborted) {
+        throw new EditableArtifactSnapshotVerificationError("cancelled");
+      }
+      // Native generation diagnostics may contain internal paths. Preserve no
+      // cause across this service boundary.
+      throw new EditableArtifactSnapshotVerificationError("kernel_rejected");
+    }
+  }
+}
+
+function validateGeneratedGenesis(
+  value: AuthoritativeEditableArtifactGenesisKernelResult,
+  scope: EditableArtifactScope,
+  artifactId: EditableArtifactId,
+  modality: EditableArtifactModality,
+): void {
+  if (
+    value.scope.accountId !== scope.accountId ||
+    value.scope.workspaceId !== scope.workspaceId ||
+    value.artifactId !== artifactId ||
+    value.modality !== modality
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("identity_mismatch");
+  }
+  if (
+    value.coveredHeadSequence !== 0 ||
+    (value.modality === "spreadsheet"
+      ? editableArtifactCausalFrontier(value.coveredCausalFrontier).length !== 0
+      : value.nativeRevision !== 0)
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("coverage_mismatch");
+  }
+  if (
+    !Number.isSafeInteger(value.canonicalByteSize) ||
+    value.canonicalByteSize <= 0 ||
+    value.canonicalByteSize > MAX_EDITABLE_ARTIFACT_SNAPSHOT_BYTES
+  ) {
+    throw new EditableArtifactSnapshotVerificationError("limit_exceeded");
+  }
+  editableArtifactContentHash(value.canonicalContentHash);
+  editableArtifactStateHash(value.stateHash);
+  const versions =
+    value.modality === "spreadsheet"
+      ? [value.modelSchemaVersion, value.operationProtocolVersion, value.crdtStateVersion]
+      : [value.modelSchemaVersion];
+  for (const version of versions) {
+    if (!Number.isSafeInteger(version) || version <= 0) {
+      throw new EditableArtifactSnapshotVerificationError("version_mismatch");
+    }
+  }
+  try {
+    assertBoundedKernelVersion(value.kernelVersion);
+  } catch {
+    throw new EditableArtifactSnapshotVerificationError("version_mismatch");
+  }
+  if (!value.canonicalChunks || typeof value.canonicalChunks[Symbol.asyncIterator] !== "function") {
+    throw new EditableArtifactSnapshotVerificationError("kernel_rejected");
+  }
+}
+
+function canonicalTimestamp(value: Date): string {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError("Genesis verification clock returned an invalid date");
+  }
+  return value.toISOString();
+}
+
+function isModality(value: unknown): value is EditableArtifactModality {
+  return value === "spreadsheet" || value === "presentation" || value === "document";
+}
+
+function throwIfGenesisCancelled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new EditableArtifactSnapshotVerificationError("cancelled");
+  }
+}

package/src/domain/editable-artifacts/snapshot-verifier-materialization.ts

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES } from "@opengeni/contracts/editable-artifacts";
+
+declare const editableArtifactMaterializationKeyBrand: unique symbol;
+
+export type EditableArtifactMaterializationKey = string & {
+  readonly [editableArtifactMaterializationKeyBrand]: true;
+};
+
+export type EditableArtifactMaterializationKeyInput = Readonly<{
+  stateHash: string;
+  format: string;
+  /** SHA-256 of the canonical, normalized export options. */
+  optionsHash: string;
+  codecVersion: string;
+  kernelVersion: string;
+  fontRegistryHash: string;
+  policyHash: string;
+}>;
+
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const FORMAT_PATTERN = /^[a-z0-9][a-z0-9.+_-]{0,63}$/;
+const VERSION_PATTERN = /^[\x21-\x7e]+$/;
+
+/**
+ * Complete materialization identity from docs/artifact-engine.md. Length
+ * framing prevents concatenation ambiguity and the output is safe as a DB
+ * idempotency key; it is deliberately not an object-storage key.
+ */
+export function editableArtifactMaterializationKey(
+  input: EditableArtifactMaterializationKeyInput,
+): EditableArtifactMaterializationKey {
+  for (const [label, value] of [
+    ["state hash", input.stateHash],
+    ["options hash", input.optionsHash],
+    ["font registry hash", input.fontRegistryHash],
+    ["policy hash", input.policyHash],
+  ] as const) {
+    if (!SHA256_PATTERN.test(value)) {
+      throw new TypeError(`${label} must be a canonical SHA-256 digest`);
+    }
+  }
+  if (!FORMAT_PATTERN.test(input.format)) {
+    throw new TypeError("materialization format is invalid");
+  }
+  if (!VERSION_PATTERN.test(input.codecVersion) || input.codecVersion.length > 128) {
+    throw new TypeError("codec version is invalid");
+  }
+  if (
+    !VERSION_PATTERN.test(input.kernelVersion) ||
+    input.kernelVersion.length > EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES
+  ) {
+    throw new TypeError("kernel version is invalid");
+  }
+  const fields = [
+    input.stateHash,
+    input.format,
+    input.optionsHash,
+    input.codecVersion,
+    input.kernelVersion,
+    input.fontRegistryHash,
+    input.policyHash,
+  ];
+  const digest = createHash("sha256");
+  digest.update("OpenGeni editable artifact materialization\0v1\0", "utf8");
+  for (const field of fields) {
+    const bytes = Buffer.from(field, "utf8");
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(bytes.byteLength);
+    digest.update(length);
+    digest.update(bytes);
+  }
+  return `materialization:v1:sha256:${digest.digest("hex")}` as EditableArtifactMaterializationKey;
+}