@opengeni/core 0.21.10 → 0.24.1

package/src/editable-artifact-live/ticket.ts

@@ -0,0 +1,217 @@
+import type { EditableArtifactAuthorizationPort } from "../domain/editable-artifacts/ports";
+import {
+  assertIsoTimestamp,
+  editableArtifactId,
+  editableArtifactScope,
+  validateEditableArtifactActor,
+  type EditableArtifactActor,
+  type EditableArtifactId,
+  type EditableArtifactModality,
+  type EditableArtifactScope,
+} from "../domain/editable-artifacts/types";
+import { EditableArtifactLiveError } from "./errors";
+import type {
+  EditableArtifactLiveClockPort,
+  EditableArtifactLiveTicketStorePort,
+  EditableArtifactLiveTokenPort,
+} from "./ports";
+import {
+  EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION,
+  type EditableArtifactLiveTicket,
+  type EditableArtifactLiveTicketRecord,
+} from "./types";
+
+const DEFAULT_TTL_MS = 30_000;
+const MAX_TTL_MS = 60_000;
+const MAX_TOKEN_BYTES = 4_096;
+
+export type EditableArtifactLiveTicketAuthorityDependencies = Readonly<{
+  authorization: EditableArtifactAuthorizationPort;
+  tickets: EditableArtifactLiveTicketStorePort;
+  tokens: EditableArtifactLiveTokenPort;
+  clock: EditableArtifactLiveClockPort;
+  ttlMs?: number;
+  protocolVersion?: number;
+}>;
+
+export class EditableArtifactLiveTicketAuthority {
+  private readonly ttlMs: number;
+  private readonly protocolVersion: number;
+
+  constructor(private readonly dependencies: EditableArtifactLiveTicketAuthorityDependencies) {
+    this.ttlMs = dependencies.ttlMs ?? DEFAULT_TTL_MS;
+    if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs < 1_000 || this.ttlMs > MAX_TTL_MS) {
+      throw new TypeError(`ticket ttl must be 1000-${MAX_TTL_MS} milliseconds`);
+    }
+    this.protocolVersion = dependencies.protocolVersion ?? EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION;
+    if (!Number.isSafeInteger(this.protocolVersion) || this.protocolVersion < 1) {
+      throw new TypeError("protocol version must be a positive safe integer");
+    }
+  }
+
+  async mint(
+    input: Readonly<{
+      scope: EditableArtifactScope;
+      artifactId: EditableArtifactId;
+      modality: EditableArtifactModality;
+      actor: EditableArtifactActor;
+      allowEdit: boolean;
+    }>,
+  ): Promise<EditableArtifactLiveTicket> {
+    const scope = editableArtifactScope(input.scope);
+    const artifactId = editableArtifactId(input.artifactId);
+    const modality = assertModality(input.modality);
+    validateEditableArtifactActor(input.actor);
+    if (typeof input.allowEdit !== "boolean") {
+      throw new TypeError("ticket allowEdit must be boolean");
+    }
+    const actor = Object.freeze({ ...input.actor }) as EditableArtifactActor;
+    const decision = await this.dependencies.authorization.authorize({
+      scope,
+      artifactId,
+      actor,
+      permission: "read",
+    });
+    if (!decision.allowed) {
+      throw new EditableArtifactLiveError(
+        "permission_changed",
+        "Editable artifact read permission denied",
+      );
+    }
+    const token = this.dependencies.tokens.randomOpaqueToken();
+    assertToken(token);
+    const tokenDigest = await this.dependencies.tokens.digestOpaqueToken(token);
+    assertDigest(tokenDigest);
+    const issuedAtDate = this.dependencies.clock.now();
+    if (!Number.isFinite(issuedAtDate.getTime()))
+      throw new TypeError("clock returned an invalid date");
+    const issuedAt = issuedAtDate.toISOString();
+    const expiresAt = new Date(issuedAtDate.getTime() + this.ttlMs).toISOString();
+    const record: EditableArtifactLiveTicketRecord = Object.freeze({
+      tokenDigest,
+      scope,
+      artifactId,
+      modality,
+      actor,
+      allowEdit: input.allowEdit,
+      protocolVersion: this.protocolVersion,
+      issuedAt,
+      expiresAt,
+    });
+    await this.dependencies.tickets.put(record);
+    return Object.freeze({
+      artifactId,
+      modality,
+      replicaId: actor.replicaId,
+      token,
+      expiresAt,
+      protocolVersion: this.protocolVersion,
+    });
+  }
+
+  async consume(
+    input: Readonly<{
+      token: string;
+      artifactId: EditableArtifactId;
+      protocolVersion: number;
+    }>,
+  ): Promise<EditableArtifactLiveTicketRecord> {
+    assertToken(input.token);
+    const artifactId = editableArtifactId(input.artifactId);
+    const digest = await this.dependencies.tokens.digestOpaqueToken(input.token);
+    assertDigest(digest);
+    const record = await this.dependencies.tickets.consume(digest);
+    if (!record) {
+      throw new EditableArtifactLiveError(
+        "ticket_replayed",
+        "Live ticket is invalid or was already consumed",
+      );
+    }
+    validateTicketRecord(record);
+    if (Date.parse(record.expiresAt) <= this.dependencies.clock.now().getTime()) {
+      throw new EditableArtifactLiveError("ticket_expired", "Live ticket has expired", {
+        retryable: true,
+      });
+    }
+    if (record.artifactId !== artifactId) {
+      throw new EditableArtifactLiveError("invalid_ticket", "Live ticket scope does not match");
+    }
+    if (
+      record.protocolVersion !== input.protocolVersion ||
+      input.protocolVersion !== this.protocolVersion
+    ) {
+      throw new EditableArtifactLiveError(
+        "protocol_mismatch",
+        "Editable artifact live protocol is unsupported",
+      );
+    }
+    return Object.freeze({
+      ...record,
+      scope: editableArtifactScope(record.scope),
+      actor: Object.freeze({ ...record.actor }) as EditableArtifactActor,
+    });
+  }
+}
+
+/** Single-process test/dev store. Production must inject a shared atomic CAS store. */
+export class InMemoryEditableArtifactLiveTicketStore implements EditableArtifactLiveTicketStorePort {
+  private readonly records = new Map<string, EditableArtifactLiveTicketRecord>();
+
+  async put(record: EditableArtifactLiveTicketRecord): Promise<void> {
+    if (this.records.has(record.tokenDigest)) throw new Error("Live ticket digest collision");
+    this.records.set(record.tokenDigest, record);
+  }
+
+  async consume(tokenDigest: string): Promise<EditableArtifactLiveTicketRecord | null> {
+    const record = this.records.get(tokenDigest) ?? null;
+    if (record) this.records.delete(tokenDigest);
+    return record;
+  }
+}
+
+export class WebCryptoEditableArtifactLiveTokens implements EditableArtifactLiveTokenPort {
+  randomOpaqueToken(): string {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    let binary = "";
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+  }
+
+  async digestOpaqueToken(token: string): Promise<string> {
+    const digest = new Uint8Array(
+      await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token)),
+    );
+    return `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  }
+}
+
+function validateTicketRecord(record: EditableArtifactLiveTicketRecord): void {
+  assertDigest(record.tokenDigest);
+  editableArtifactScope(record.scope);
+  editableArtifactId(record.artifactId);
+  assertModality(record.modality);
+  validateEditableArtifactActor(record.actor);
+  if (typeof record.allowEdit !== "boolean") {
+    throw new TypeError("ticket allowEdit is invalid");
+  }
+  assertIsoTimestamp(record.issuedAt, "ticket issuedAt");
+  assertIsoTimestamp(record.expiresAt, "ticket expiresAt");
+}
+
+function assertModality(value: EditableArtifactModality): EditableArtifactModality {
+  if (value !== "document" && value !== "spreadsheet" && value !== "presentation") {
+    throw new TypeError("ticket modality is invalid");
+  }
+  return value;
+}
+
+function assertToken(token: string): void {
+  const bytes = new TextEncoder().encode(token).byteLength;
+  if (bytes < 32 || bytes > MAX_TOKEN_BYTES || !/^[A-Za-z0-9._~-]+$/u.test(token)) {
+    throw new EditableArtifactLiveError("invalid_ticket", "Live ticket is malformed");
+  }
+}
+
+function assertDigest(value: string): void {
+  if (!/^sha256:[0-9a-f]{64}$/u.test(value)) throw new TypeError("ticket digest is malformed");
+}

package/src/editable-artifact-live/types.ts

@@ -0,0 +1,286 @@
+import type {
+  EditableArtifactActor,
+  EditableArtifactCausalFrontier,
+  EditableArtifactClientTransactionId,
+  EditableArtifactContentHash,
+  EditableArtifactId,
+  EditableArtifactModality,
+  EditableArtifactRequestHash,
+  EditableArtifactScope,
+  EditableArtifactStateHash,
+  EditableArtifactTransactionId,
+} from "../domain/editable-artifacts/types";
+
+export const EDITABLE_ARTIFACT_LIVE_PROTOCOL_VERSION = 1;
+
+export type EditableArtifactLiveTicket = Readonly<{
+  artifactId: EditableArtifactId;
+  modality: EditableArtifactModality;
+  replicaId: string;
+  token: string;
+  expiresAt: string;
+  protocolVersion: number;
+}>;
+
+/** Stored under a digest of the opaque token and atomically consumed once. */
+export type EditableArtifactLiveTicketRecord = Readonly<{
+  tokenDigest: string;
+  scope: EditableArtifactScope;
+  artifactId: EditableArtifactId;
+  modality: EditableArtifactModality;
+  actor: EditableArtifactActor;
+  /** Delegated ceiling captured by the authenticated ticket-minting request. */
+  allowEdit: boolean;
+  protocolVersion: number;
+  issuedAt: string;
+  expiresAt: string;
+}>;
+
+type EditableArtifactLiveSnapshotCommon = Readonly<{
+  artifactId: EditableArtifactId;
+  sequence: number;
+  stateHash: EditableArtifactStateHash;
+  digest: EditableArtifactContentHash;
+  kernelVersion: string;
+  modelSchemaVersion: number;
+  bytes: Uint8Array;
+}>;
+
+export type EditableArtifactLiveSnapshot =
+  | (EditableArtifactLiveSnapshotCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        causalFrontier: EditableArtifactCausalFrontier;
+        operationProtocolVersion: number;
+      }>)
+  | (EditableArtifactLiveSnapshotCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        nativeRevision: number;
+      }>);
+
+type EditableArtifactLiveCommittedTransactionCommon = Readonly<{
+  artifactId: EditableArtifactId;
+  transactionId: EditableArtifactTransactionId;
+  requestHash: EditableArtifactRequestHash;
+  startSequence: number;
+  endSequence: number;
+  priorStateHash: EditableArtifactStateHash;
+  stateHash: EditableArtifactStateHash;
+  committedTransactionBytes: Uint8Array;
+}>;
+
+export type EditableArtifactLiveCommittedTransaction =
+  | (EditableArtifactLiveCommittedTransactionCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        causalFrontier: EditableArtifactCausalFrontier;
+        operationProtocolVersion: number;
+      }>)
+  | (EditableArtifactLiveCommittedTransactionCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        priorNativeRevision: number;
+        nativeRevision: number;
+        commitProtocolVersion: number;
+      }>);
+
+type EditableArtifactLiveHeadCommon = Readonly<{
+  headSequence: number;
+  stateHash: EditableArtifactStateHash;
+  minimumReplaySequence: number;
+}>;
+
+export type EditableArtifactLiveHead =
+  | (EditableArtifactLiveHeadCommon &
+      Readonly<{
+        modality: "spreadsheet";
+        causalFrontier: EditableArtifactCausalFrontier;
+      }>)
+  | (EditableArtifactLiveHeadCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        nativeRevision: number;
+      }>);
+
+export type EditableArtifactLiveBootstrap = EditableArtifactLiveHead &
+  Readonly<{
+    resumeAccepted: boolean;
+    resumeSequence: number;
+    resumeStateHash: EditableArtifactStateHash;
+    snapshot: EditableArtifactLiveSnapshot | null;
+  }>;
+
+type EditableArtifactLiveResumeCommon = Readonly<{
+  localCursor: number | null;
+  localStateHash: EditableArtifactStateHash | null;
+  requireSnapshot: boolean;
+}>;
+
+export type EditableArtifactLiveResume =
+  | (EditableArtifactLiveResumeCommon &
+      Readonly<{
+        modality?: "spreadsheet";
+        localCausalFrontier: EditableArtifactCausalFrontier;
+      }>)
+  | (EditableArtifactLiveResumeCommon &
+      Readonly<{
+        modality: "document" | "presentation";
+        localNativeRevision: number | null;
+      }>);
+
+export type EditableArtifactLiveServerFrame =
+  | Readonly<{
+      type: "open";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      modality: EditableArtifactModality;
+      writable: boolean;
+      headSequence: number;
+      minimumReplaySequence: number;
+      maxClientFrameBytes: number;
+      maxCommandBytes: number;
+      maxIntentBytes: number;
+      maxCommittedTransactionBytes: number;
+      maxSnapshotBytes: number;
+      maxInFlightTransactions: number;
+      maxInFlightBytes: number;
+    }>
+  | (Readonly<{
+      type: "snapshot";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      sequence: number;
+      stateHash: EditableArtifactStateHash;
+      digest: EditableArtifactContentHash;
+      kernelVersion: string;
+      modelSchemaVersion: number;
+      offset: number;
+      totalBytes: number;
+      final: boolean;
+      bytes: Uint8Array;
+    }> &
+      (
+        | Readonly<{
+            modality: "spreadsheet";
+            causalFrontier: EditableArtifactCausalFrontier;
+          }>
+        | Readonly<{
+            modality: "document" | "presentation";
+            nativeRevision: number;
+          }>
+      ))
+  | Readonly<{
+      type: "transaction";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      transaction: EditableArtifactLiveCommittedTransaction;
+    }>
+  | Readonly<{
+      type: "barrier";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      sequence: number;
+      stateHash: EditableArtifactStateHash;
+    }>
+  | Readonly<{
+      type: "watermark";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      headSequence: number;
+    }>
+  | Readonly<{
+      type: "resyncRequired";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      reason: "retention_gap" | "durable_gap" | "invalid_ack" | "slow_client" | "oversized_frame";
+      headSequence: number;
+    }>
+  | Readonly<{
+      type: "applied";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      sequence: number;
+      stateHash: EditableArtifactStateHash;
+    }>
+  | Readonly<{
+      type: "authorizationChanged";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      writable: boolean;
+    }>
+  | Readonly<{
+      type: "mutationAccepted";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      requestHash: EditableArtifactRequestHash;
+      clientTransactionId: EditableArtifactClientTransactionId;
+      transactionId: EditableArtifactTransactionId;
+      startSequence: number;
+      endSequence: number;
+      stateHash: EditableArtifactStateHash;
+    }>
+  | Readonly<{
+      type: "mutationRejected";
+      protocolVersion: number;
+      artifactId: EditableArtifactId;
+      streamEpoch: string;
+      requestHash: EditableArtifactRequestHash;
+      code: "invalid_request" | "forbidden" | "conflict" | "unsupported" | "unavailable";
+      retryable: boolean;
+    }>;
+
+export type EditableArtifactLiveAppliedClientFrame = Readonly<{
+  type: "applied";
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  streamEpoch: string;
+  sequence: number;
+  stateHash: EditableArtifactStateHash;
+}>;
+
+export type EditableArtifactLiveMutationClientFrame = Readonly<{
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  streamEpoch: string;
+  requestHash: EditableArtifactRequestHash;
+  intentBytes: Uint8Array;
+}>;
+
+export type EditableArtifactLiveClientFrame = EditableArtifactLiveAppliedClientFrame;
+
+export type EditableArtifactLiveCloseReason =
+  | "closed"
+  | "ticket_expired"
+  | "ticket_replayed"
+  | "protocol_mismatch"
+  | "permission_changed"
+  | "invalid_frame"
+  | "oversized_frame"
+  | "stale_epoch"
+  | "invalid_ack"
+  | "retention_gap"
+  | "durable_gap"
+  | "slow_client"
+  | "transport_error";
+
+export type EditableArtifactLiveClose = Readonly<{
+  reason: EditableArtifactLiveCloseReason;
+  retryable: boolean;
+  requiresSnapshot: boolean;
+}>;
+
+export type EditableArtifactLiveMutationReceipt = Readonly<{
+  clientTransactionId: EditableArtifactClientTransactionId;
+  requestHash: EditableArtifactRequestHash;
+  transaction: EditableArtifactLiveCommittedTransaction;
+}>;

package/src/editable-artifact-live/wire.ts

@@ -0,0 +1,95 @@
+import {
+  EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
+  decodeEditableArtifactLiveClientWireFrame as decodeContractClientFrame,
+  decodeEditableArtifactLiveServerWireFrame,
+  encodeEditableArtifactLiveAppliedWireFrame as encodeContractAppliedFrame,
+  encodeEditableArtifactLiveMutationWireFrame as encodeContractMutationFrame,
+  encodeEditableArtifactLiveOpenWireFrame as encodeContractOpenFrame,
+  encodeEditableArtifactLiveServerWireFrame as encodeContractServerFrame,
+  inspectEditableArtifactLiveWireEnvelope,
+  type EditableArtifactLiveAppliedWireFrame as ContractAppliedWireFrame,
+  type EditableArtifactLiveMutationWireFrame as ContractMutationWireFrame,
+  type EditableArtifactLiveOpenWireFrame as ContractOpenWireFrame,
+  type EditableArtifactLiveServerFrame as ContractServerFrame,
+} from "@opengeni/contracts/editable-artifact-live";
+import type {
+  EditableArtifactId,
+  EditableArtifactRequestHash,
+  EditableArtifactStateHash,
+} from "../domain/editable-artifacts/types";
+import type { EditableArtifactLiveResume, EditableArtifactLiveServerFrame } from "./types";
+
+export {
+  EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
+  decodeEditableArtifactLiveServerWireFrame,
+  inspectEditableArtifactLiveWireEnvelope,
+};
+
+/** Branded core view over the contracts-owned wire type. Runtime validation is contracts-only. */
+export type EditableArtifactLiveOpenWireFrame = Readonly<{
+  type: "open";
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  token: string;
+  resume: EditableArtifactLiveResume;
+}>;
+export type EditableArtifactLiveAppliedWireFrame = Readonly<{
+  type: "applied";
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  streamEpoch: string;
+  sequence: number;
+  stateHash: EditableArtifactStateHash;
+}>;
+export type EditableArtifactLiveMutationWireFrame = Readonly<{
+  type: "mutation";
+  protocolVersion: number;
+  artifactId: EditableArtifactId;
+  streamEpoch: string;
+  requestHash: EditableArtifactRequestHash;
+  intentBytes: Uint8Array;
+}>;
+export type EditableArtifactLiveClientWireFrame =
+  | EditableArtifactLiveOpenWireFrame
+  | EditableArtifactLiveAppliedWireFrame
+  | EditableArtifactLiveMutationWireFrame;
+
+export function decodeEditableArtifactLiveClientWireFrame(
+  bytes: Uint8Array,
+): EditableArtifactLiveClientWireFrame {
+  return decodeContractClientFrame(bytes) as unknown as EditableArtifactLiveClientWireFrame;
+}
+
+export function encodeEditableArtifactLiveOpenWireFrame(
+  frame: EditableArtifactLiveOpenWireFrame,
+): Uint8Array {
+  return encodeContractOpenFrame(frame as unknown as ContractOpenWireFrame);
+}
+
+export function encodeEditableArtifactLiveAppliedWireFrame(
+  frame: EditableArtifactLiveAppliedWireFrame,
+): Uint8Array {
+  return encodeContractAppliedFrame(frame as unknown as ContractAppliedWireFrame);
+}
+
+export function encodeEditableArtifactLiveMutationWireFrame(
+  frame: EditableArtifactLiveMutationWireFrame,
+): Uint8Array {
+  return encodeContractMutationFrame(frame as unknown as ContractMutationWireFrame);
+}
+
+export function encodeEditableArtifactLiveServerWireFrame(
+  frame: EditableArtifactLiveServerFrame,
+): Uint8Array {
+  if (frame.type === "transaction" && frame.transaction.modality === "spreadsheet") {
+    const { operationProtocolVersion, modality: _modality, ...transaction } = frame.transaction;
+    return encodeContractServerFrame({
+      ...frame,
+      transaction: {
+        ...transaction,
+        protocolVersion: operationProtocolVersion,
+      },
+    } as unknown as ContractServerFrame);
+  }
+  return encodeContractServerFrame(frame as unknown as ContractServerFrame);
+}

package/src/editable-artifact-live.ts

@@ -0,0 +1,2 @@
+/** Durable editable-artifact live broker API. */
+export * from "./editable-artifact-live/index";

package/src/editable-artifacts.ts

@@ -0,0 +1,2 @@
+/** Transport-neutral editable-artifact domain API. */
+export * from "./domain/editable-artifacts";

package/src/index.ts

@@ -55,6 +55,7 @@ export * from "./billing/limits";
 // postUserMessageTurn, createAndStartSession, capability/pack/environment/
 // scheduled-task/workspace-member logic, …).
 export * from "./domain/capabilities";
+export * from "./domain/skill-imports";
 export * from "./domain/environments";
 export * from "./rigs";
 export * from "./domain/packs";
@@ -65,7 +66,19 @@ export * from "./domain/scheduled-tasks";
 export * from "./domain/sessions";
 export * from "./domain/insights";
 export * from "./domain/memory-slack-publication";
+export * from "./domain/memory-slack-delivery";
+export * from "./domain/durable-learning-slack-publication";
+export * from "./domain/slack-publication-secret-safety";
+export * from "./domain/company-profile-durable-learning-adapter";
 export * from "./domain/slack-bot";
 export * from "./domain/workspace-members";
+export * from "./domain/video-generation";
+export * from "./domain/video-generation-capabilities";
 export * from "./application/new-session-drafts";
 export * from "./application/session-commands";
+
+// Durable editable-artifact live broker, ticket, ports, and projection types.
+export * from "./editable-artifact-live";
+
+// Transport-neutral editable-artifact domain service, ports, and contracts.
+export * from "./editable-artifacts";