@opengeni/db 0.28.1 → 0.31.1

package/dist/editable-artifacts.d.ts

@@ -0,0 +1,610 @@
+import { type Database } from "./database.js";
+/**
+ * Persistence DTOs intentionally live below @opengeni/core. Core already
+ * depends on @opengeni/db, so importing its nominal types here would create a
+ * publish-time package cycle. These shapes mirror the editable-artifact domain
+ * port exactly; core owns the one-way typed adapter.
+ */
+export type PersistedEditableArtifactScope = Readonly<{
+    accountId: string;
+    workspaceId: string;
+}>;
+export type PersistedEditableArtifactActor = Readonly<{
+    kind: "human";
+    subjectId: string;
+    replicaId: string;
+}> | Readonly<{
+    kind: "agent";
+    subjectId: string;
+    replicaId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    generation: number;
+}> | Readonly<{
+    kind: "service";
+    subjectId: string;
+    replicaId: string;
+    service: string;
+}>;
+export type PersistedEditableArtifactLiveTicketActor = PersistedEditableArtifactActor;
+export type PersistedEditableArtifactLiveTicketRecord = Readonly<{
+    tokenDigest: string;
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    modality: "spreadsheet" | "presentation" | "document";
+    actor: PersistedEditableArtifactLiveTicketActor;
+    allowEdit: boolean;
+    protocolVersion: number;
+    issuedAt: string;
+    expiresAt: string;
+}>;
+export type PersistedEditableArtifactCausalEntry = Readonly<{
+    replicaId: string;
+    counter: number;
+}>;
+export type PersistedEditableArtifactCausalFrontier = readonly PersistedEditableArtifactCausalEntry[];
+type PersistedEditableArtifactCommon = Readonly<{
+    scope: PersistedEditableArtifactScope;
+    id: string;
+    title: string;
+    lifecycle: "active" | "archived";
+    authorizationRevision: number;
+    headSequence: number;
+    stateHash: string;
+    currentSnapshotId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type PersistedEditableArtifact = (PersistedEditableArtifactCommon & Readonly<{
+    modality: "spreadsheet";
+    causalFrontier: PersistedEditableArtifactCausalFrontier;
+}>) | (PersistedEditableArtifactCommon & Readonly<{
+    modality: "document" | "presentation";
+}>);
+export type PersistedEditableArtifactCreationReceipt = Readonly<{
+    receiptId: string;
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    operationKind: "create" | "import";
+    authorityKey: string;
+    idempotencyKey: string;
+    requestHash: string;
+    genesisSnapshotId: string;
+    createdAt: string;
+}>;
+export type CreatePersistedEditableArtifactResult = Readonly<{
+    artifact: PersistedEditableArtifact;
+    genesisSnapshot: PersistedEditableArtifactSnapshotMetadata;
+    creationReceipt: PersistedEditableArtifactCreationReceipt;
+    replayed: boolean;
+}>;
+export type CreatePersistedEditableArtifactStoreResult = Readonly<{
+    kind: "result";
+    value: CreatePersistedEditableArtifactResult;
+}> | Readonly<{
+    kind: "authorization_stale";
+}>;
+export type ReadPersistedEditableArtifactAtAuthorizationRevisionResult = Readonly<{
+    kind: "result";
+    artifact: PersistedEditableArtifact | null;
+}> | Readonly<{
+    kind: "authorization_stale";
+}>;
+export type PersistedEditableArtifactOperationRecord = Readonly<{
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    serverTransactionId: string;
+    sequence: number;
+    actorKey: string;
+    createdAt: string;
+    operationId: string;
+    dot: PersistedEditableArtifactCausalEntry;
+}>;
+type PersistedEditableArtifactCommittedTransactionCommon = Readonly<{
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    modality: PersistedEditableArtifact["modality"];
+    serverTransactionId: string;
+    requestHash: string;
+    sequenceStart: number;
+    sequenceEnd: number;
+    priorStateHash: string;
+    stateHash: string;
+    modelSchemaVersion: number;
+    kernelVersion: string;
+    committedTransactionBytes: Uint8Array;
+    committedAt: string;
+}>;
+export type PersistedEditableArtifactCommittedTransactionRecord = (PersistedEditableArtifactCommittedTransactionCommon & Readonly<{
+    modality: "spreadsheet";
+    dot: PersistedEditableArtifactCausalEntry;
+    resolvedCausalBase: PersistedEditableArtifactCausalFrontier;
+    resultingCausalFrontier: PersistedEditableArtifactCausalFrontier;
+    operationIds: readonly string[];
+    operationProtocolVersion: number;
+}>) | (PersistedEditableArtifactCommittedTransactionCommon & Readonly<{
+    modality: "document" | "presentation";
+    commitProtocolVersion: number;
+    priorNativeRevision: number;
+    nativeRevision: number;
+    commandCount: number;
+    nativeReceiptBytes: Uint8Array;
+}>);
+type PersistedEditableArtifactReceiptCommon = Readonly<{
+    receiptId: string;
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    modality: PersistedEditableArtifact["modality"];
+    serverTransactionId: string;
+    clientTransactionId: string;
+    replicaId: string;
+    replicaCounter: number;
+    previousLocalTransactionId: string | null;
+    intentBytes: Uint8Array;
+    requestHash: string;
+    actorKey: string;
+    sequenceStart: number;
+    sequenceEnd: number;
+    priorStateHash: string;
+    stateHash: string;
+    intentEnvelopeVersion: number;
+    intentProtocolVersion: number;
+    commandProtocolVersion: number;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    committedAt: string;
+}>;
+export type PersistedEditableArtifactReceipt = (PersistedEditableArtifactReceiptCommon & Readonly<{
+    modality: "spreadsheet";
+    causalBase: PersistedEditableArtifactCausalFrontier;
+    resolvedCausalBase: PersistedEditableArtifactCausalFrontier;
+    resultingCausalFrontier: PersistedEditableArtifactCausalFrontier;
+    operationCount: number;
+    selectiveUndoOperationIds: readonly string[];
+    operationProtocolVersion: number;
+}>) | (PersistedEditableArtifactReceiptCommon & Readonly<{
+    modality: "document" | "presentation";
+    commitProtocolVersion: number;
+    priorNativeRevision: number;
+    nativeRevision: number;
+    commandCount: number;
+}>);
+type PersistedEditableArtifactSnapshotMetadataCommon = Readonly<{
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    modality: PersistedEditableArtifact["modality"];
+    snapshotId: string;
+    blobReference: string;
+    byteSize: number;
+    contentHash: string;
+    mimeType: "application/vnd.opengeni.editable-artifact-snapshot";
+    coveredHeadSequence: number;
+    stateHash: string;
+    modelSchemaVersion: number;
+    kernelVersion: string;
+    verifiedAt: string;
+    publishedAt: string;
+}>;
+export type PersistedEditableArtifactSnapshotMetadata = (PersistedEditableArtifactSnapshotMetadataCommon & Readonly<{
+    modality: "spreadsheet";
+    coveredCausalFrontier: PersistedEditableArtifactCausalFrontier;
+    operationProtocolVersion: number;
+    crdtStateVersion: number;
+}>) | (PersistedEditableArtifactSnapshotMetadataCommon & Readonly<{
+    modality: "document" | "presentation";
+    nativeRevision: number;
+}>);
+export type PersistedEditableArtifactSequenceCheckpoint = Readonly<{
+    modality: "spreadsheet";
+    headSequence: number;
+    causalFrontier: PersistedEditableArtifactCausalFrontier;
+    stateHash: string;
+}> | Readonly<{
+    modality: "document" | "presentation";
+    headSequence: number;
+    nativeRevision: number;
+    stateHash: string;
+}>;
+type PersistedEditableArtifactTransactionEventCommon = Readonly<{
+    kind: "transaction_committed";
+    schemaVersion: 1;
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    serverTransactionId: string;
+    sequenceStart: number;
+    sequenceEnd: number;
+    stateHash: string;
+    committedAt: string;
+}>;
+type PersistedEditableArtifactSnapshotEventCommon = Readonly<{
+    kind: "snapshot_published";
+    schemaVersion: 1;
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    snapshotId: string;
+    coveredHeadSequence: number;
+    stateHash: string;
+    publishedAt: string;
+}>;
+export type PersistedEditableArtifactLiveEvent = (PersistedEditableArtifactTransactionEventCommon & Readonly<{
+    modality: "spreadsheet";
+    operationProtocolVersion: number;
+}>) | (PersistedEditableArtifactTransactionEventCommon & Readonly<{
+    modality: "document" | "presentation";
+    commitProtocolVersion: number;
+}>) | (PersistedEditableArtifactSnapshotEventCommon & Readonly<{
+    modality: "spreadsheet";
+    operationProtocolVersion: number;
+}>) | (PersistedEditableArtifactSnapshotEventCommon & Readonly<{
+    modality: "document" | "presentation";
+}>);
+export type PersistedEditableArtifactLiveOutboxRecord = Readonly<{
+    outboxId: string;
+    event: PersistedEditableArtifactLiveEvent;
+    state: "pending" | "publishing" | "published" | "dead_lettered";
+    attemptCount: number;
+    leaseOwner: string | null;
+    leaseExpiresAt: string | null;
+    nextAttemptAt: string;
+    lastErrorCode: string | null;
+    publishedAt: string | null;
+    deadLetteredAt: string | null;
+    createdAt: string;
+}>;
+type PersistedEditableArtifactLiveBoundaryCommon = Readonly<{
+    modality: PersistedEditableArtifact["modality"];
+    headSequence: number;
+    stateHash: string;
+    minimumReplaySequence: number;
+}>;
+export type PersistedEditableArtifactLiveHead = (PersistedEditableArtifactLiveBoundaryCommon & Readonly<{
+    modality: "spreadsheet";
+    causalFrontier: PersistedEditableArtifactCausalFrontier;
+}>) | (PersistedEditableArtifactLiveBoundaryCommon & Readonly<{
+    modality: "document" | "presentation";
+    nativeRevision: number;
+}>);
+export type PersistedEditableArtifactLiveResume = Readonly<{
+    modality?: "spreadsheet";
+    localCursor: number | null;
+    localStateHash: string | null;
+    localCausalFrontier: PersistedEditableArtifactCausalFrontier;
+    requireSnapshot: boolean;
+}> | Readonly<{
+    modality: "document" | "presentation";
+    localCursor: number | null;
+    localStateHash: string | null;
+    localNativeRevision: number | null;
+    requireSnapshot: boolean;
+}>;
+export type PersistedEditableArtifactLiveSnapshot = Readonly<{
+    modality: "spreadsheet";
+    artifactId: string;
+    sequence: number;
+    stateHash: string;
+    causalFrontier: PersistedEditableArtifactCausalFrontier;
+    digest: string;
+    operationProtocolVersion: number;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    bytes: Uint8Array;
+}> | Readonly<{
+    modality: "document" | "presentation";
+    artifactId: string;
+    sequence: number;
+    stateHash: string;
+    nativeRevision: number;
+    digest: string;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    bytes: Uint8Array;
+}>;
+export type PersistedEditableArtifactLiveCommittedTransaction = Readonly<{
+    modality: "spreadsheet";
+    artifactId: string;
+    transactionId: string;
+    requestHash: string;
+    startSequence: number;
+    endSequence: number;
+    priorStateHash: string;
+    stateHash: string;
+    causalFrontier: PersistedEditableArtifactCausalFrontier;
+    operationProtocolVersion: number;
+    committedTransactionBytes: Uint8Array;
+}> | Readonly<{
+    modality: "document" | "presentation";
+    artifactId: string;
+    transactionId: string;
+    requestHash: string;
+    startSequence: number;
+    endSequence: number;
+    priorStateHash: string;
+    stateHash: string;
+    priorNativeRevision: number;
+    nativeRevision: number;
+    commitProtocolVersion: number;
+    committedTransactionBytes: Uint8Array;
+}>;
+export type PersistedEditableArtifactLiveBootstrap = PersistedEditableArtifactLiveHead & Readonly<{
+    resumeAccepted: boolean;
+    resumeSequence: number;
+    resumeStateHash: string;
+    snapshot: PersistedEditableArtifactLiveSnapshot | null;
+}>;
+export interface PersistedEditableArtifactSnapshotBytesPort {
+    readSnapshotBytes(snapshot: PersistedEditableArtifactSnapshotMetadata): Promise<Uint8Array>;
+}
+export type PersistedEditableArtifactKernelState = Readonly<{
+    modality: "spreadsheet";
+    artifact: Extract<PersistedEditableArtifact, {
+        modality: "spreadsheet";
+    }>;
+    snapshot: Extract<PersistedEditableArtifactSnapshotMetadata, {
+        modality: "spreadsheet";
+    }> | null;
+    tailTransactionCount: number;
+    tailByteSize: number;
+    committedTransactionTail: readonly Extract<PersistedEditableArtifactCommittedTransactionRecord, {
+        modality: "spreadsheet";
+    }>[];
+}> | Readonly<{
+    modality: "document" | "presentation";
+    artifact: Extract<PersistedEditableArtifact, {
+        modality: "document" | "presentation";
+    }>;
+    snapshot: Extract<PersistedEditableArtifactSnapshotMetadata, {
+        modality: "document" | "presentation";
+    }> | null;
+    tailTransactionCount: number;
+    tailByteSize: number;
+    baseNativeRevision: number;
+    committedTransactionTail: readonly Extract<PersistedEditableArtifactCommittedTransactionRecord, {
+        modality: "document" | "presentation";
+    }>[];
+}>;
+export type CommitPersistedEditableArtifactTransaction = Readonly<{
+    expectedHeadSequence: number;
+    serverTransactionId: string;
+    receipt: PersistedEditableArtifactReceipt;
+    committedTransaction: PersistedEditableArtifactCommittedTransactionRecord;
+    operations: readonly PersistedEditableArtifactOperationRecord[];
+    outbox: PersistedEditableArtifactLiveOutboxRecord;
+}>;
+export type ReadPersistedEditableArtifactTransactionBasisRequest = Readonly<{
+    actorKey: string;
+    clientTransactionId: string;
+    previousLocalTransactionId: string | null;
+    selectiveUndoOperationIds: readonly string[];
+}>;
+export type PersistedEditableArtifactTransactionUndoBasis = Readonly<{
+    operationId: string;
+    operation: PersistedEditableArtifactOperationRecord | null;
+    claimedBy: string | null;
+}>;
+export type PersistedEditableArtifactTransactionBasis = Readonly<{
+    kind: "existing";
+    receipt: PersistedEditableArtifactReceipt;
+}> | Readonly<{
+    kind: "basis";
+    artifact: PersistedEditableArtifact;
+    predecessor: PersistedEditableArtifactReceipt | null;
+    undoTargets: readonly PersistedEditableArtifactTransactionUndoBasis[];
+    kernelState: PersistedEditableArtifactKernelState;
+}>;
+export type ExpectedPersistedEditableArtifactPredecessor = Readonly<{
+    receiptId: string;
+    serverTransactionId: string;
+    actorKey: string;
+    clientTransactionId: string;
+    replicaId: string;
+    replicaCounter: number;
+}>;
+export type TryCommitPersistedEditableArtifactTransactionRequest = CommitPersistedEditableArtifactTransaction & Readonly<{
+    scope: PersistedEditableArtifactScope;
+    artifactId: string;
+    expectedLifecycle: "active";
+    expectedAuthorizationRevision: number;
+    authorizationActor: PersistedEditableArtifactActor;
+    actorKey: string;
+    clientTransactionId: string;
+    requestHash: string;
+    expectedPredecessor: ExpectedPersistedEditableArtifactPredecessor | null;
+    expectedUnclaimedUndoTargets: readonly string[];
+}>;
+export type TryCommitPersistedEditableArtifactTransactionResult = Readonly<{
+    kind: "committed";
+    receipt: PersistedEditableArtifactReceipt;
+}> | Readonly<{
+    kind: "replayed";
+    receipt: PersistedEditableArtifactReceipt;
+}> | Readonly<{
+    kind: "stale";
+}>;
+export type CommitPersistedEditableArtifactSnapshot = Readonly<{
+    expectedCurrentSnapshotId: string | null;
+    expectedAuthorizationRevision: number;
+    authorizationActor: PersistedEditableArtifactActor;
+    authorizationPermission?: "manage" | "read" | "edit";
+    snapshot: PersistedEditableArtifactSnapshotMetadata;
+    outbox: PersistedEditableArtifactLiveOutboxRecord;
+}>;
+export type CommitPersistedEditableArtifactSnapshotResult = Readonly<{
+    kind: "committed";
+}> | Readonly<{
+    kind: "authorization_stale";
+}>;
+export interface PersistedEditableArtifactSnapshotPublicationUnitOfWork {
+    artifact(): PersistedEditableArtifact;
+    checkpoint(headSequence: number): Promise<PersistedEditableArtifactSequenceCheckpoint | null>;
+    findSnapshot(snapshotId: string): Promise<PersistedEditableArtifactSnapshotMetadata | null>;
+    commitSnapshot(input: CommitPersistedEditableArtifactSnapshot): Promise<CommitPersistedEditableArtifactSnapshotResult>;
+}
+export type ClaimPersistedEditableArtifactLiveOutboxRequest = Readonly<{
+    owner: string;
+    leaseDurationMs: number;
+    limit: number;
+}>;
+export type PersistedEditableArtifactOutboxRetryErrorCode = "broker_unavailable" | "broker_backpressure" | "publish_timeout";
+export type PersistedEditableArtifactOutboxDeadLetterErrorCode = "invalid_hint" | "oversized_hint";
+export type AdvancePersistedEditableArtifactAuthorizationRevisionResult = Readonly<{
+    applied: boolean;
+    authorizationRevision: number;
+}>;
+export type PersistedEditableArtifactScopeAuthorizationHead = Readonly<{
+    scope: PersistedEditableArtifactScope;
+    createRevision: number;
+}>;
+export declare class EditableArtifactPersistenceError extends Error {
+    readonly code: "not_found" | "conflict" | "corrupt_history" | "history_limit" | "outbox_lease_conflict" | "transient";
+    constructor(code: "not_found" | "conflict" | "corrupt_history" | "history_limit" | "outbox_lease_conflict" | "transient", message: string, options?: ErrorOptions);
+}
+/** Record that one session used an artifact; repeated calls only advance recency. */
+export declare function touchEditableArtifactSessionLink(db: Database, scopeInput: PersistedEditableArtifactScope, sessionIdInput: string, artifactIdInput: string): Promise<void>;
+/** List the exact artifacts most recently used by one session. */
+export declare function listEditableArtifactIdsForSession(db: Database, scopeInput: PersistedEditableArtifactScope, sessionIdInput: string, limitInput?: number): Promise<readonly string[]>;
+export declare const EDITABLE_ARTIFACT_INTENT_MAX_BYTES: number;
+export declare const EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_TRANSACTIONS = 100000;
+export declare const EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_BYTES: number;
+/**
+ * Shared PostgreSQL implementation of the live ticket atomic-take port.
+ * Direct table access is intentionally unnecessary: all three operations use
+ * hardened owner-defined routines installed by migration 0185.
+ */
+export declare class PostgresEditableArtifactLiveTicketStore {
+    private readonly db;
+    constructor(db: Database);
+    put(recordInput: PersistedEditableArtifactLiveTicketRecord): Promise<void>;
+    consume(tokenDigestInput: string): Promise<PersistedEditableArtifactLiveTicketRecord | null>;
+    cleanupExpired(limitInput?: number): Promise<number>;
+}
+/**
+ * PostgreSQL authority adapter. Kernel inputs are copied from a detached,
+ * repeatable-read basis; only the final write CAS and narrow snapshot metadata
+ * publication hold the artifact row lock. Tenant RLS is set and verified in
+ * every scoped transaction.
+ */
+export declare class PostgresEditableArtifactStore {
+    private readonly db;
+    constructor(db: Database);
+    findArtifactCreation(scopeInput: PersistedEditableArtifactScope, operationKindInput: "create" | "import", authorityKeyInput: string, idempotencyKeyInput: string): Promise<CreatePersistedEditableArtifactResult | null>;
+    createArtifact(input: {
+        scope: PersistedEditableArtifactScope;
+        artifactId: string;
+        authorizationActor: PersistedEditableArtifactActor;
+        receiptId: string;
+        authorityKey: string;
+        idempotencyKey: string;
+        requestHash: string;
+        operationKind: "create" | "import";
+        modality: PersistedEditableArtifact["modality"];
+        title: string;
+        expectedScopeAuthorizationRevision: number;
+        initialArtifactAuthorizationRevision: number;
+        createdBySubjectId: string;
+        genesisSnapshot: PersistedEditableArtifactSnapshotMetadata;
+        originalImport?: Readonly<{
+            fileId: string;
+            blobRefId: string;
+            blobReference: string;
+            byteSize: number;
+            contentHash: string;
+            mimeType: string;
+        }>;
+        outbox: PersistedEditableArtifactLiveOutboxRecord;
+    }): Promise<CreatePersistedEditableArtifactStoreResult>;
+    ensureScopeCreateAuthorizationHead(scopeInput: PersistedEditableArtifactScope): Promise<PersistedEditableArtifactScopeAuthorizationHead>;
+    advanceScopeCreateAuthorizationRevision(scopeInput: PersistedEditableArtifactScope, expectedRevisionInput: number, nextRevisionInput: number): Promise<AdvancePersistedEditableArtifactAuthorizationRevisionResult>;
+    getArtifact(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string): Promise<PersistedEditableArtifact | null>;
+    readArtifactAtAuthorizationRevision(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string, expectedAuthorizationRevisionInput: number): Promise<ReadPersistedEditableArtifactAtAuthorizationRevisionResult>;
+    advanceAuthorizationRevision(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string, expectedRevisionInput: number, nextRevisionInput: number): Promise<AdvancePersistedEditableArtifactAuthorizationRevisionResult>;
+    readTransactionBasis(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string, request: ReadPersistedEditableArtifactTransactionBasisRequest): Promise<PersistedEditableArtifactTransactionBasis>;
+    readCurrentKernelState(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string, expectedAuthorizationRevisionInput: number): Promise<Readonly<{
+        kind: "basis";
+        state: PersistedEditableArtifactKernelState;
+    }> | Readonly<{
+        kind: "authorization_stale";
+    }>>;
+    tryCommitAppliedTransaction(request: TryCommitPersistedEditableArtifactTransactionRequest): Promise<TryCommitPersistedEditableArtifactTransactionResult>;
+    withSnapshotPublicationLock<T>(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string, callback: (unitOfWork: PersistedEditableArtifactSnapshotPublicationUnitOfWork) => Promise<T>): Promise<T>;
+    claimLiveOutbox(request: ClaimPersistedEditableArtifactLiveOutboxRequest): Promise<readonly PersistedEditableArtifactLiveOutboxRecord[]>;
+    markLiveOutboxPublished(input: {
+        outboxId: string;
+        owner: string;
+        attemptCount: number;
+    }): Promise<void>;
+    renewLiveOutbox(input: {
+        outboxId: string;
+        owner: string;
+        attemptCount: number;
+        leaseDurationMs: number;
+    }): Promise<void>;
+    retryLiveOutbox(input: {
+        outboxId: string;
+        owner: string;
+        attemptCount: number;
+        retryDelayMs: number;
+        errorCode: PersistedEditableArtifactOutboxRetryErrorCode;
+    }): Promise<void>;
+    deadLetterLiveOutbox(input: {
+        outboxId: string;
+        owner: string;
+        attemptCount: number;
+        errorCode: PersistedEditableArtifactOutboxDeadLetterErrorCode;
+    }): Promise<void>;
+    releaseLiveOutbox(input: {
+        outboxId: string;
+        owner: string;
+        attemptCount: number;
+    }): Promise<void>;
+}
+export type PostgresEditableArtifactLiveReadStoreOptions = Readonly<{
+    snapshotBytes: PersistedEditableArtifactSnapshotBytesPort;
+    replicaLeaseTtlMs?: number;
+}>;
+/**
+ * Durable OGALV read/ACK adapter. PostgreSQL selects the immutable modality
+ * before any canonical transaction bytes are decoded; object storage supplies
+ * only bytes for already-authoritative snapshot metadata.
+ */
+export declare class PostgresEditableArtifactLiveReadStore {
+    private readonly db;
+    private readonly options;
+    private readonly replicaLeaseTtlMs;
+    constructor(db: Database, options: PostgresEditableArtifactLiveReadStoreOptions);
+    readBootstrap(input: {
+        scope: PersistedEditableArtifactScope;
+        artifactId: string;
+        resume: PersistedEditableArtifactLiveResume;
+        protocolVersion: number;
+    }): Promise<PersistedEditableArtifactLiveBootstrap>;
+    readHead(scopeInput: PersistedEditableArtifactScope, artifactIdInput: string): Promise<PersistedEditableArtifactLiveHead>;
+    readTransactions(input: {
+        scope: PersistedEditableArtifactScope;
+        artifactId: string;
+        after: number;
+        through: number;
+        maxCount: number;
+        maxBytes: number;
+    }): Promise<Readonly<{
+        transactions: readonly PersistedEditableArtifactLiveCommittedTransaction[];
+        headSequence: number;
+        minimumReplaySequence: number;
+    }>>;
+    readCommittedTransaction(input: {
+        scope: PersistedEditableArtifactScope;
+        artifactId: string;
+        transactionId: string;
+    }): Promise<PersistedEditableArtifactLiveCommittedTransaction | null>;
+    acknowledgeReplica(input: {
+        scope: PersistedEditableArtifactScope;
+        artifactId: string;
+        replicaId: string;
+        actorKey: string;
+        streamEpoch: string;
+        sequence: number;
+        stateHash: string;
+    }): Promise<void>;
+    private readVerifiedSnapshotBytes;
+}
+export {};

package/dist/editable-artifacts.js

@@ -0,0 +1,26 @@
+import {
+  EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
+  EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_BYTES,
+  EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_TRANSACTIONS,
+  EditableArtifactPersistenceError,
+  PostgresEditableArtifactLiveReadStore,
+  PostgresEditableArtifactLiveTicketStore,
+  PostgresEditableArtifactStore,
+  listEditableArtifactIdsForSession,
+  touchEditableArtifactSessionLink
+} from "./chunk-F5FT7BEZ.js";
+import "./chunk-ISI2TIUG.js";
+import "./chunk-MWDVXQOL.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  EDITABLE_ARTIFACT_INTENT_MAX_BYTES,
+  EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_BYTES,
+  EDITABLE_ARTIFACT_KERNEL_TAIL_MAX_TRANSACTIONS,
+  EditableArtifactPersistenceError,
+  PostgresEditableArtifactLiveReadStore,
+  PostgresEditableArtifactLiveTicketStore,
+  PostgresEditableArtifactStore,
+  listEditableArtifactIdsForSession,
+  touchEditableArtifactSessionLink
+};
+//# sourceMappingURL=editable-artifacts.js.map

package/dist/editable-artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/environment-crypto.d.ts

@@ -1,11 +1,15 @@
 /**
  * Encrypts one workspace environment variable value with AES-256-GCM under an
- * operator key held outside Postgres. Output format: `v1:<b64 iv>:<b64 ciphertext||tag>`.
+ * operator key held outside Postgres. v2 encodes the JavaScript string as
+ * UTF-16LE before encryption so every code unit (including NUL and lone
+ * surrogates) round-trips exactly. Output format:
+ * `v2:<b64 iv>:<b64 ciphertext||tag>`.
  */
 export declare function encryptEnvironmentValue(key: Uint8Array, plaintext: string): string;
 /**
- * Decrypts a stored `v1:` value. Error messages never echo plaintext or
- * ciphertext: unknown versions throw "unsupported environment value format",
- * auth-tag mismatches throw "environment value decryption failed".
+ * Decrypts current lossless v2 values and historical UTF-8 v1 values. Error
+ * messages never echo plaintext or ciphertext: unknown versions throw
+ * "unsupported environment value format", auth-tag mismatches throw
+ * "environment value decryption failed".
  */
 export declare function decryptEnvironmentValue(key: Uint8Array, stored: string): string;