@opengeni/core 0.21.10 → 0.28.0

package/dist/domain/session-tool-policy.d.ts

@@ -24,8 +24,8 @@ export declare function defaultSessionMcpServerIds(servers: Iterable<{
  */
 export declare function resolveSessionToolPolicy(input: SessionToolPolicyInput): ResolvedSessionToolPolicy;
 /** Current full runtime registry IDs, including configured static servers. */
-export declare function workspaceSessionToolPolicyServerIds(db: Database, workspaceId: string, settings: Settings): Promise<string[]>;
+export declare function workspaceSessionToolPolicyServerIds(db: Database, workspaceId: string, settings: Settings, subjectId?: string): Promise<string[]>;
 /** Current omitted-tools defaults: every configured runtime MCP is on. */
-export declare function workspaceSessionToolPolicyDefaultServerIds(db: Database, workspaceId: string, settings: Settings): Promise<string[]>;
+export declare function workspaceSessionToolPolicyDefaultServerIds(db: Database, workspaceId: string, settings: Settings, subjectId?: string): Promise<string[]>;
 /** Add a bounded, secret-safe effective projection to a session response. */
 export declare function sessionWithEffectiveToolPolicy(session: Session, workspaceServerIds: Iterable<string>, workspaceDefaultServerIds?: Iterable<string>): Session;

package/dist/domain/sessions.d.ts

@@ -1,8 +1,8 @@
 import { type Settings } from "@opengeni/config";
-import { SessionSpawnDenial, type AccessGrant, type CreateSessionResponse, type GoalSpec, type FirstPartyMcpToolName, type McpPersonalConnectionDelegation, type Permission, type ReasoningEffort, type ResourceRef, type Session, type SessionSkill, type SessionEvent, SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerMetadata, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionToolPolicyRequest, type SessionAuthorizationPort, type SessionToolPolicy, type SessionTurn, type ToolRef, type TurnInitiator, type TurnInitiatorContext, type TurnExecutionPolicyV1 } from "@opengeni/contracts";
+import { SessionSpawnDenial, type AccessGrant, type CreateSessionResponse, type GoalSpec, type FirstPartyMcpToolName, type McpPersonalConnectionDelegation, type Permission, type ReasoningEffort, type ResourceRef, type Session, type SessionSkill, type SessionEvent, SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerMetadata, type SubmittedTimelineAnnotation, type TimelineAnnotation, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionToolPolicyRequest, type SessionAuthorizationPort, type SessionToolPolicy, type SessionTurn, type ToolRef, type TurnInitiator, type TurnInitiatorContext, type TurnExecutionPolicyV1, type XaiProviderAccountAuthoritySnapshotV1 } from "@opengeni/contracts";
 import { type CreateSessionMcpServerInput, type Database, type UpdateSessionMcpServerCredentialsInput, type SessionCommandActor } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
-import type { AcceptSessionUserMessageDependencies, ApiRouteDeps, SessionWorkflowClient } from "../dependencies";
+import type { AcceptSessionUserMessageDependencies, ApiRouteDeps, SessionWorkflowClient } from "../dependencies.js";
 /** Transport-neutral typed denial raised only after its audit row committed. */
 export declare class SessionSpawnDeniedError extends Error {
     readonly denial: SessionSpawnDenial;
@@ -14,7 +14,10 @@ export declare class SessionSpawnDeniedError extends Error {
  * child omission snapshots the parent's exact effective selection. Explicit
  * [] is authoritative and must never widen.
  */
-export declare function resolveFirstPartyMcpToolsForCreate(requested: FirstPartyMcpToolName[] | undefined, parentStored: FirstPartyMcpToolName[] | null | undefined): FirstPartyMcpToolName[];
+export declare function resolveFirstPartyMcpToolsForCreate(requested: FirstPartyMcpToolName[] | undefined, parentStored: FirstPartyMcpToolName[] | null | undefined, policy?: {
+    default: readonly FirstPartyMcpToolName[];
+    allowed: readonly FirstPartyMcpToolName[];
+}): FirstPartyMcpToolName[];
 export declare function sessionSpawnDenialEnvelope(error: SessionSpawnDeniedError): {
     readonly error: {
         readonly code: "nested_agent_depth_exceeded" | "nested_agent_depth_override_forbidden";
@@ -66,7 +69,10 @@ export declare function createAndStartSessionWithOutcome(input: {
     requestedSessionId?: string;
     db: Database;
     bus: EventBus;
-    workflowClient: SessionWorkflowClient;
+    workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow">;
+    /** Internal database-only composition seam. The exact session shell and this
+     * linkage commit together before its first event/turn can be initialized. */
+    beforeCreateCommit?: (tx: Database, sessionId: string) => Promise<void>;
     accountId: string;
     workspaceId: string;
     initialMessage: string;
@@ -96,6 +102,7 @@ export declare function createAndStartSessionWithOutcome(input: {
     } | null;
     rigId?: string | null;
     rigVersionId?: string | null;
+    channelId?: string | null;
     goal?: GoalSpec | null;
     instructions?: string | null;
     policyRole?: string | null;
@@ -104,6 +111,7 @@ export declare function createAndStartSessionWithOutcome(input: {
     mcpServers?: CreateSessionMcpServerInput[];
     sessionMcpServers?: SessionMcpServerMetadata[];
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
+    xaiProviderAccountAuthoritySnapshot?: XaiProviderAccountAuthoritySnapshotV1;
     parentSessionId?: string | null;
     createIdempotencyKey?: string | null;
     sandboxGroupId?: string | null;
@@ -131,10 +139,10 @@ export declare function workflowIdForSession(sessionId: string): string;
  * it cannot be resolved to a provider at run time, so we fail the request at
  * the API edge with 422 rather than enqueuing a turn the worker can't honor.
  *
- * `model` is the explicit, caller-supplied value (null/undefined when omitted).
- * An omitted model defaults to `settings.openaiModel` downstream — which is
- * always first in `configuredAllowedModels` — so only an explicit value is
- * checked. Centralized here so every model-carrying choke point
+ * `model` is the effective value selected by the caller's boundary. Top-level
+ * omission defaults to `settings.openaiModel`; child-session omission inherits
+ * the worker-signed calling turn before reaching this helper. Centralized here
+ * so every model-carrying choke point
  * (create-session, user-message/turn-accept, queued-turn update, and
  * scheduled-task agentConfig — a scheduled task is a session the worker runs
  * later) and the MCP surfaces that share them validate identically and cannot
@@ -185,6 +193,7 @@ export declare function postUserMessageTurn(input: {
     workspaceId: string;
     sessionId: string;
     text: string;
+    annotations?: TimelineAnnotation[];
     turnInstructions?: string | null;
     resources: ResourceRef[];
     model?: string | null;
@@ -202,9 +211,12 @@ export declare function postUserMessageTurn(input: {
     expectedDraftRevision?: number | null;
     reasoningEffortFallback?: Settings["openaiReasoningEffort"];
     turnExecutionPolicy: TurnExecutionPolicyV1;
+    recordAgentRunUsage?: boolean;
+    schedulePostCommit?: (task: () => Promise<void>) => void;
 }): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
+    interruptionCount: number;
     replay: boolean;
 }>;
 /**
@@ -230,6 +242,7 @@ export declare function createSessionForRequest(deps: ApiRouteDeps, grant: Acces
  */
 export declare function acceptSessionUserMessageWithOutcome(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
     text: string;
+    annotations?: SubmittedTimelineAnnotation[];
     turnInstructions?: string | null;
     resources?: ResourceRef[];
     model?: string | null;
@@ -244,12 +257,15 @@ export declare function acceptSessionUserMessageWithOutcome(deps: AcceptSessionU
 }): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
+    interruptionCount: number;
     replay: boolean;
 }>;
 /** Backward-compatible entity-returning path used by existing REST callers. */
 export declare function acceptSessionUserMessage(deps: Parameters<typeof acceptSessionUserMessageWithOutcome>[0], grant: Parameters<typeof acceptSessionUserMessageWithOutcome>[1], workspaceId: Parameters<typeof acceptSessionUserMessageWithOutcome>[2], sessionId: Parameters<typeof acceptSessionUserMessageWithOutcome>[3], input: Parameters<typeof acceptSessionUserMessageWithOutcome>[4]): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
+    interruptionCount: number;
+    replay: boolean;
 }>;
 /**
  * Shared title-write path for the manual rename route AND both MCP tools

package/dist/domain/skill-imports.d.ts

@@ -0,0 +1,32 @@
+import type { SkillImportPreview, SkillImportSource } from "@opengeni/contracts";
+import { type SkillLibraryFile } from "@opengeni/runtime/skill-library";
+export type GitHubSkillTreeEntry = Readonly<{
+    path: string;
+    type: "blob" | "tree" | "commit";
+    mode: string;
+    sha: string;
+    size: number | null;
+}>;
+export type GitHubSkillSourceClient = Readonly<{
+    resolveCommit(owner: string, repository: string, ref: string): Promise<string>;
+    listTree(owner: string, repository: string, commit: string): Promise<readonly GitHubSkillTreeEntry[]>;
+    readBlob(owner: string, repository: string, sha: string): Promise<Uint8Array>;
+}>;
+export type ResolvedSkillImport = Readonly<{
+    preview: SkillImportPreview;
+    files: readonly SkillLibraryFile[];
+}>;
+type ParsedSkillSource = Readonly<{
+    source: SkillImportSource;
+    owner: string;
+    repository: string;
+    ref: string;
+    requestedPath: string | null;
+    skillSlug: string | null;
+    inputUrl: string;
+}>;
+export declare function resolveSkillImport(rawUrl: string, client: GitHubSkillSourceClient): Promise<ResolvedSkillImport>;
+export declare function portableSkillPluginKey(source: Pick<SkillImportPreview, "owner" | "repository" | "sourcePath">): string;
+export declare function portableSkillCapabilityId(source: Pick<SkillImportPreview, "name" | "owner" | "repository" | "sourcePath">): string;
+export declare function parseSkillSource(rawUrl: string): ParsedSkillSource;
+export {};

package/dist/domain/slack-publication-secret-safety.d.ts

@@ -0,0 +1,8 @@
+export declare const SLACK_PUBLICATION_CREDENTIAL_OMISSION = "[credential omitted]";
+/**
+ * Deterministic, sink-local protection for text that is about to be persisted
+ * as a Slack publication projection or rendered to Slack. It intentionally
+ * does not scan or mutate canonical Memory, durable-learning receipts, model
+ * context, history, events, or any other internal OpenGeni content path.
+ */
+export declare function sanitizeSlackPublicationText(value: string): string;

package/dist/domain/timeline-annotations.d.ts

@@ -0,0 +1,5 @@
+import { type DraftTimelineAnnotation, type SessionEvent, type SubmittedTimelineAnnotation, type TimelineAnnotation } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+export declare function timelineAnnotationSourceText(event: SessionEvent): string | null;
+export declare function validateDraftTimelineAnnotations(db: Database, workspaceId: string, sessionId: string, annotations: readonly DraftTimelineAnnotation[]): Promise<DraftTimelineAnnotation[]>;
+export declare function validateSubmittedTimelineAnnotations(db: Database, workspaceId: string, sessionId: string, annotations: readonly SubmittedTimelineAnnotation[]): Promise<TimelineAnnotation[]>;

package/dist/domain/video-generation-capabilities.d.ts

@@ -0,0 +1,10 @@
+import { VideoGenerationCapabilities, type VideoGenerationModelCapability, type VideoGenerationPolicy as VideoGenerationPolicyType } from "@opengeni/contracts";
+/** Reviewed executable catalog. Dynamic workspace policy never mutates tool schemas. */
+export declare const VIDEO_GENERATION_MODEL_CATALOG: readonly VideoGenerationModelCapability[];
+export declare function videoGenerationModelSupportsFundingSource(modelId: string, fundingSource: VideoGenerationPolicyType["fundingSource"]): boolean;
+export declare function defaultVideoGenerationPolicy(): VideoGenerationPolicyType;
+export declare function videoGenerationCapabilitiesForPolicy(input: {
+    policy: VideoGenerationPolicyType;
+    credentialVersion: number;
+}): VideoGenerationCapabilities;
+export declare function assertKnownVideoGenerationModelIds(modelIds: readonly string[]): void;

package/dist/domain/video-generation.d.ts

@@ -0,0 +1,47 @@
+import { VideoGenerationAspectRatio, VideoGenerationResolution, VideoGenerationSourceMode, type GenerateVideoToolInput as GenerateVideoToolInputType, type VideoGenerationFundingSource, type VideoGenerationModelCapability } from "@opengeni/contracts";
+export declare const VIDEO_GENERATION_ADAPTER_VERSION: "gateway-video-v4/1";
+export type SealedVideoReferenceRole = "first_frame" | "last_frame" | "image_reference" | "video_reference";
+export type SealedVideoReference = Readonly<{
+    role: SealedVideoReferenceRole;
+    contentSha256: string;
+    contentType: string;
+    byteSize: number;
+}>;
+export type CanonicalVideoGenerationRequest = Readonly<{
+    schemaVersion: 1;
+    modelId: string;
+    prompt: string;
+    sourceMode: VideoGenerationSourceMode;
+    references: readonly SealedVideoReference[];
+    durationSeconds: number;
+    aspectRatio: VideoGenerationAspectRatio;
+    resolution: VideoGenerationResolution;
+    generateAudio: boolean;
+}>;
+export type VideoGenerationOperationState = "preparing" | "prepared" | "accepted" | "submission_uncertain" | "provider_started" | "retaining" | "completed" | "provider_failed" | "cancelled_before_submit" | "outcome_unknown" | "retention_failed";
+export declare function normalizeVideoGenerationRequest(input: {
+    toolInput: GenerateVideoToolInputType;
+    model: VideoGenerationModelCapability;
+    sealedReferences: readonly SealedVideoReference[];
+}): CanonicalVideoGenerationRequest;
+export declare function canonicalVideoGenerationRequestJson(request: CanonicalVideoGenerationRequest): string;
+export declare function videoGenerationRequestDigest(request: CanonicalVideoGenerationRequest): string;
+/** Stable only for one logical tool call; intentional identical calls remain distinct. */
+export declare function videoGenerationAdmissionKey(input: {
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    toolCallId: string;
+}): string;
+export declare function videoGenerationProviderIdempotencyKey(input: {
+    operationId: string;
+    requestDigest: string;
+}): string;
+export declare function videoGenerationCapabilityRevision(input: {
+    policyRevision: number;
+    fundingSource: VideoGenerationFundingSource;
+    credentialVersion: number;
+    modelIds: readonly string[];
+}): string;
+export declare function assertVideoGenerationTransition(from: VideoGenerationOperationState, to: VideoGenerationOperationState): void;
+export declare function isTerminalVideoGenerationState(state: VideoGenerationOperationState): boolean;

package/dist/editable-artifact-live/application.d.ts

@@ -0,0 +1,69 @@
+import type { EditableArtifactService } from "../domain/editable-artifacts/service.js";
+import { type EditableArtifact, type EditableArtifactActor, type EditableArtifactClientTransactionId, type EditableArtifactId, type EditableArtifactModality, type EditableArtifactOriginalImport, type EditableArtifactScope, type ImportEditableArtifactRequest } from "../domain/editable-artifacts/types.js";
+import type { EditableArtifactLiveSession, EditableArtifactLiveServer, OpenEditableArtifactLiveInput } from "./server.js";
+import type { EditableArtifactLiveTicket } from "./types.js";
+export type EditableArtifactLiveCompatibilityRequest = Readonly<{
+    artifact: EditableArtifact;
+    protocolVersion: number;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+}>;
+/** A client/runtime protocol tuple cannot be served by the loaded kernel. */
+export declare class EditableArtifactCompatibilityError extends Error {
+    readonly code: "unsupported_protocol";
+    constructor(message?: string);
+}
+/** Local runtime compatibility; unsupported native/WASM assets fail closed. */
+export interface EditableArtifactLiveCompatibilityPort {
+    assertCompatible(input: EditableArtifactLiveCompatibilityRequest): Promise<void> | void;
+}
+export type CreateEditableArtifactApplicationInput = Readonly<{
+    scope: EditableArtifactScope;
+    actor: EditableArtifactActor;
+    idempotencyKey: EditableArtifactClientTransactionId;
+    modality: EditableArtifactModality;
+    title: string;
+    signal?: AbortSignal;
+}>;
+export type ImportEditableArtifactApplicationInput = Readonly<{
+    scope: EditableArtifactScope;
+    actor: EditableArtifactActor;
+    idempotencyKey: EditableArtifactClientTransactionId;
+    modality: EditableArtifactModality;
+    title: string;
+    originalImport: EditableArtifactOriginalImport;
+    snapshot: ImportEditableArtifactRequest["snapshot"];
+    signal?: AbortSignal;
+}>;
+export type ReadEditableArtifactApplicationInput = Readonly<{
+    scope: EditableArtifactScope;
+    actor: EditableArtifactActor;
+    artifactId: EditableArtifactId;
+}>;
+export type MintEditableArtifactApplicationTicketInput = ReadEditableArtifactApplicationInput & Readonly<{
+    protocolVersion: number;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    allowEdit: boolean;
+}>;
+/** Exact application seam used by standalone API and embedding hosts. */
+export interface EditableArtifactApplicationPort {
+    createArtifact(input: CreateEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    importArtifact(input: ImportEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    readArtifact(input: ReadEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    mintLiveTicket(input: MintEditableArtifactApplicationTicketInput): Promise<EditableArtifactLiveTicket>;
+    openLive(input: OpenEditableArtifactLiveInput): Promise<EditableArtifactLiveSession>;
+}
+export declare class EditableArtifactApplication implements EditableArtifactApplicationPort {
+    private readonly dependencies;
+    constructor(dependencies: Readonly<{
+        domain: EditableArtifactService;
+        live: EditableArtifactLiveServer;
+        compatibility: EditableArtifactLiveCompatibilityPort;
+    }>);
+    createArtifact(input: CreateEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    importArtifact(input: ImportEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    readArtifact(input: ReadEditableArtifactApplicationInput): Promise<EditableArtifact>;
+    mintLiveTicket(input: MintEditableArtifactApplicationTicketInput): Promise<EditableArtifactLiveTicket>;
+    openLive(input: OpenEditableArtifactLiveInput): Promise<EditableArtifactLiveSession>;
+}

package/dist/editable-artifact-live/errors.d.ts

@@ -0,0 +1 @@
+export { EditableArtifactLiveError, type EditableArtifactLiveErrorCode, } from "@opengeni/contracts/editable-artifact-live";

package/dist/editable-artifact-live/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./application.js";
+export * from "./errors.js";
+export * from "./outbox-dispatcher.js";
+export * from "./ports.js";
+export * from "./server.js";
+export * from "./ticket.js";
+export * from "./types.js";
+export * from "./wire.js";

package/dist/editable-artifact-live/outbox-dispatcher.d.ts

@@ -0,0 +1,162 @@
+import { type EditableArtifactLiveOutboxRecord, type EditableArtifactModality, type EditableArtifactOutboxId, type EditableArtifactScope } from "../domain/editable-artifacts/types.js";
+import type { EditableArtifactLiveClockPort, EditableArtifactLiveSchedulerPort } from "./ports.js";
+export declare const EDITABLE_ARTIFACT_HINT_MAX_BYTES: number;
+export declare const EDITABLE_ARTIFACT_HINT_SUBJECT_PREFIX = "editable_artifacts.v1";
+type EditableArtifactBrokerHeadHintCommon = Readonly<{
+    kind: "head_advanced";
+    schemaVersion: 1;
+    scope: EditableArtifactScope;
+    artifactId: string;
+    modality: EditableArtifactModality;
+    headSequence: number;
+    stateHash: string;
+}>;
+type EditableArtifactBrokerSnapshotHintCommon = Readonly<{
+    kind: "snapshot_available";
+    schemaVersion: 1;
+    scope: EditableArtifactScope;
+    artifactId: string;
+    modality: EditableArtifactModality;
+    headSequence: number;
+    stateHash: string;
+    snapshotId: string;
+}>;
+export type EditableArtifactBrokerHint = (EditableArtifactBrokerHeadHintCommon & Readonly<{
+    modality: "spreadsheet";
+    operationProtocolVersion: number;
+}>) | (EditableArtifactBrokerHeadHintCommon & Readonly<{
+    modality: "document" | "presentation";
+    commitProtocolVersion: number;
+}>) | (EditableArtifactBrokerSnapshotHintCommon & Readonly<{
+    modality: "spreadsheet";
+    operationProtocolVersion: number;
+}>) | (EditableArtifactBrokerSnapshotHintCommon & Readonly<{
+    modality: "document" | "presentation";
+}>);
+export type EditableArtifactEncodedBrokerHint = Readonly<{
+    subject: string;
+    payload: Uint8Array;
+    hint: EditableArtifactBrokerHint;
+}>;
+export interface EditableArtifactOutboxDispatcherStorePort {
+    claimLiveOutbox(input: {
+        owner: string;
+        leaseDurationMs: number;
+        limit: number;
+    }): Promise<readonly EditableArtifactLiveOutboxRecord[]>;
+    renewLiveOutbox(input: {
+        outboxId: EditableArtifactOutboxId;
+        owner: string;
+        attemptCount: number;
+        leaseDurationMs: number;
+    }): Promise<void>;
+    markLiveOutboxPublished(input: {
+        outboxId: EditableArtifactOutboxId;
+        owner: string;
+        attemptCount: number;
+    }): Promise<void>;
+    retryLiveOutbox(input: {
+        outboxId: EditableArtifactOutboxId;
+        owner: string;
+        attemptCount: number;
+        retryDelayMs: number;
+        errorCode: EditableArtifactOutboxRetryErrorCode;
+    }): Promise<void>;
+    deadLetterLiveOutbox(input: {
+        outboxId: EditableArtifactOutboxId;
+        owner: string;
+        attemptCount: number;
+        errorCode: EditableArtifactOutboxDeadLetterErrorCode;
+    }): Promise<void>;
+}
+/** Resolves only after the broker has acknowledged every preceding publish. */
+export interface EditableArtifactHintBrokerPort {
+    publish(input: Readonly<{
+        subject: string;
+        payload: Uint8Array;
+        signal: AbortSignal;
+    }>): Promise<void>;
+}
+export interface EditableArtifactOutboxRandomPort {
+    unit(): number;
+}
+export type EditableArtifactOutboxMetricOutcome = "claimed" | "published" | "retried" | "dead_lettered" | "lease_lost" | "claim_failed" | "mark_failed" | "retry_store_failed" | "dead_letter_store_failed";
+/** Labels are closed unions; artifact/workspace identities must never become metric labels. */
+export interface EditableArtifactOutboxMetricsPort {
+    increment(outcome: EditableArtifactOutboxMetricOutcome, count?: number): void;
+    observePublishSeconds(outcome: "acked" | "failed" | "timed_out", seconds: number): void;
+}
+export interface EditableArtifactOutboxLoggerPort {
+    warn(message: string, attributes: Readonly<Record<string, unknown>>): void;
+}
+export type EditableArtifactOutboxRetryErrorCode = "broker_unavailable" | "broker_backpressure" | "publish_timeout";
+export type EditableArtifactOutboxDeadLetterErrorCode = "invalid_hint" | "oversized_hint";
+export type EditableArtifactOutboxDispatcherOptions = Readonly<{
+    owner: string;
+    batchSize?: number;
+    concurrency?: number;
+    leaseDurationMs?: number;
+    leaseRenewIntervalMs?: number;
+    pollIntervalMs?: number;
+    publishTimeoutMs?: number;
+    retryBaseMs?: number;
+    retryMaxMs?: number;
+    retryJitterRatio?: number;
+    claimBackoffBaseMs?: number;
+    claimBackoffMaxMs?: number;
+    maxHintBytes?: number;
+}>;
+export type EditableArtifactOutboxDispatcherDependencies = Readonly<{
+    store: EditableArtifactOutboxDispatcherStorePort;
+    broker: EditableArtifactHintBrokerPort;
+    clock: EditableArtifactLiveClockPort;
+    scheduler: EditableArtifactLiveSchedulerPort;
+    random: EditableArtifactOutboxRandomPort;
+    metrics?: EditableArtifactOutboxMetricsPort;
+    logger?: EditableArtifactOutboxLoggerPort;
+}>;
+export type EditableArtifactOutboxDispatchSummary = Readonly<{
+    claimed: number;
+    published: number;
+    retried: number;
+    deadLettered: number;
+    leaseLost: number;
+    markFailed: number;
+    claimFailed: boolean;
+}>;
+export declare class EditableArtifactLiveOutboxDispatcher {
+    private readonly dependencies;
+    private readonly options;
+    private activeDispatch;
+    constructor(dependencies: EditableArtifactOutboxDispatcherDependencies, options: EditableArtifactOutboxDispatcherOptions);
+    /**
+     * Long-running resilient loop. Abort stops new claims; an already-claimed
+     * bounded batch drains before this promise resolves.
+     */
+    run(signal: AbortSignal): Promise<void>;
+    /** Concurrent callers share one bounded claim/dispatch pass. */
+    dispatchOnce(): Promise<EditableArtifactOutboxDispatchSummary>;
+    drain(): Promise<void>;
+    private dispatchBatch;
+    private dispatchRecord;
+    private renewWhilePublishing;
+    private retry;
+    private deadLetter;
+    private metric;
+    private observePublish;
+    private warn;
+}
+export declare class EditableArtifactHintEncodingError extends Error {
+    readonly code: EditableArtifactOutboxDeadLetterErrorCode;
+    constructor(code: EditableArtifactOutboxDeadLetterErrorCode, message: string);
+}
+export declare function encodeEditableArtifactBrokerHint(record: EditableArtifactLiveOutboxRecord, maxBytes?: number): EditableArtifactEncodedBrokerHint;
+export declare function editableArtifactLiveHintSubject(scope: EditableArtifactScope, artifactIdInput: string): string;
+export declare function decodeEditableArtifactBrokerHint(payload: Uint8Array, expected: Readonly<{
+    scope: EditableArtifactScope;
+    artifactId: string;
+}>, maxBytes?: number): EditableArtifactBrokerHint;
+export declare class MathEditableArtifactOutboxRandom implements EditableArtifactOutboxRandomPort {
+    unit(): number;
+}
+export {};

package/dist/editable-artifact-live/ports.d.ts

@@ -0,0 +1,100 @@
+import type { EditableArtifactAuthorizationPort } from "../domain/editable-artifacts/ports.js";
+import type { EditableArtifactService } from "../domain/editable-artifacts/service.js";
+import type { EditableArtifactActor, EditableArtifactId, EditableArtifactScope, EditableArtifactStateHash, EditableArtifactTransactionId } from "../domain/editable-artifacts/types.js";
+import type { EditableArtifactLiveBootstrap, EditableArtifactLiveClose, EditableArtifactLiveCommittedTransaction, EditableArtifactLiveHead, EditableArtifactLiveResume, EditableArtifactLiveServerFrame, EditableArtifactLiveTicketRecord } from "./types.js";
+export interface EditableArtifactLiveTicketStorePort {
+    put(record: EditableArtifactLiveTicketRecord): Promise<void>;
+    /** Atomic take. A token can establish at most one live connection. */
+    consume(tokenDigest: string): Promise<EditableArtifactLiveTicketRecord | null>;
+}
+export interface EditableArtifactLiveTokenPort {
+    randomOpaqueToken(): string;
+    digestOpaqueToken(token: string): Promise<string>;
+}
+export interface EditableArtifactLiveClockPort {
+    now(): Date;
+}
+export interface EditableArtifactLiveSchedulerPort {
+    sleep(milliseconds: number, signal: AbortSignal): Promise<void>;
+}
+export type EditableArtifactLiveBootstrapRead = Readonly<{
+    scope: EditableArtifactScope;
+    artifactId: EditableArtifactId;
+    resume: EditableArtifactLiveResume;
+    protocolVersion: number;
+}>;
+export type EditableArtifactLiveTransactionPage = Readonly<{
+    transactions: readonly EditableArtifactLiveCommittedTransaction[];
+    headSequence: number;
+    minimumReplaySequence: number;
+}>;
+/** Canonical PostgreSQL/object-store read side. Fanout data is never accepted here. */
+export interface EditableArtifactLiveReadPort {
+    /**
+     * Verifies any proposed resume sequence/hash/frontier against durable truth.
+     * Snapshot bytes must already have passed digest/size/object-identity checks.
+     */
+    readBootstrap(input: EditableArtifactLiveBootstrapRead): Promise<EditableArtifactLiveBootstrap>;
+    readHead(scope: EditableArtifactScope, artifactId: EditableArtifactId): Promise<EditableArtifactLiveHead>;
+    readTransactions(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        after: number;
+        through: number;
+        maxCount: number;
+        maxBytes: number;
+    }>): Promise<EditableArtifactLiveTransactionPage>;
+    readCommittedTransaction(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        transactionId: EditableArtifactTransactionId;
+    }>): Promise<EditableArtifactLiveCommittedTransaction | null>;
+    /** Advances retention authority only after a verified client apply ACK. */
+    acknowledgeReplica(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        replicaId: string;
+        actorKey: string;
+        streamEpoch: string;
+        sequence: number;
+        stateHash: EditableArtifactStateHash;
+    }>): Promise<void>;
+}
+export type EditableArtifactLiveHint = Readonly<{
+    artifactId: EditableArtifactId;
+    headSequence: number;
+}>;
+export interface EditableArtifactLiveHintPort {
+    /** Resolves only after the underlying subscription/flush barrier is active. */
+    subscribe(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        onHint: (hint: EditableArtifactLiveHint) => void;
+        onReconnect: () => void;
+    }>): Promise<() => void>;
+}
+export interface EditableArtifactLiveAuthorizationInvalidationPort {
+    subscribe(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        actor: EditableArtifactActor;
+        onInvalidated: () => void;
+    }>): Promise<() => void>;
+}
+/** Adapter-owned socket writer. `send` resolves when the adapter accepts the frame. */
+export interface EditableArtifactLiveSinkPort {
+    send(frame: EditableArtifactLiveServerFrame): Promise<void>;
+    bufferedBytes(): number;
+    close(close: EditableArtifactLiveClose): void;
+}
+export type EditableArtifactLiveServerDependencies = Readonly<{
+    authorization: EditableArtifactAuthorizationPort;
+    domain: EditableArtifactService;
+    tickets: EditableArtifactLiveTicketStorePort;
+    tokens: EditableArtifactLiveTokenPort;
+    clock: EditableArtifactLiveClockPort;
+    scheduler: EditableArtifactLiveSchedulerPort;
+    read: EditableArtifactLiveReadPort;
+    hints: EditableArtifactLiveHintPort;
+    invalidations: EditableArtifactLiveAuthorizationInvalidationPort;
+}>;

package/dist/editable-artifact-live/server.d.ts

@@ -0,0 +1,71 @@
+import type { EditableArtifactAuthorizationPort } from "../domain/editable-artifacts/ports.js";
+import type { EditableArtifactService } from "../domain/editable-artifacts/service.js";
+import { type EditableArtifactActor, type EditableArtifactId, type EditableArtifactModality, type EditableArtifactRequestHash, type EditableArtifactScope } from "../domain/editable-artifacts/types.js";
+import type { EditableArtifactLiveAuthorizationInvalidationPort, EditableArtifactLiveClockPort, EditableArtifactLiveHintPort, EditableArtifactLiveReadPort, EditableArtifactLiveSchedulerPort, EditableArtifactLiveServerDependencies, EditableArtifactLiveSinkPort, EditableArtifactLiveTicketStorePort, EditableArtifactLiveTokenPort } from "./ports.js";
+import { type EditableArtifactLiveAppliedClientFrame, type EditableArtifactLiveClose, type EditableArtifactLiveCloseReason, type EditableArtifactLiveMutationReceipt, type EditableArtifactLiveResume, type EditableArtifactLiveTicket } from "./types.js";
+export type EditableArtifactLiveServerOptions = Readonly<{
+    protocolVersion?: number;
+    ticketTtlMs?: number;
+    maxClientFrameBytes?: number;
+    maxOutboundFrameBytes?: number;
+    maxSnapshotBytes?: number;
+    snapshotChunkBytes?: number;
+    maxInFlightTransactions?: number;
+    maxInFlightBytes?: number;
+    replayPageTransactions?: number;
+    replayPageBytes?: number;
+    maxSocketBufferedBytes?: number;
+    maxInboundQueueFrames?: number;
+    maxInboundQueueBytes?: number;
+    reconcileIntervalMs?: number;
+    reauthorizeIntervalMs?: number;
+    ackTimeoutMs?: number;
+    sendTimeoutMs?: number;
+}>;
+export type OpenEditableArtifactLiveInput = Readonly<{
+    token: string;
+    artifactId: EditableArtifactId;
+    protocolVersion: number;
+    resume: EditableArtifactLiveResume;
+    sink: EditableArtifactLiveSinkPort;
+    signal?: AbortSignal;
+}>;
+export interface EditableArtifactLiveSession {
+    readonly artifactId: EditableArtifactId;
+    readonly modality: EditableArtifactModality;
+    readonly streamEpoch: string;
+    readonly closed: Promise<EditableArtifactLiveClose>;
+    receive(bytes: Uint8Array): Promise<void>;
+    acknowledge(frame: EditableArtifactLiveAppliedClientFrame): Promise<void>;
+    submitIntent(input: Readonly<{
+        protocolVersion: number;
+        artifactId: EditableArtifactId;
+        streamEpoch: string;
+        requestHash: EditableArtifactRequestHash;
+        intentBytes: Uint8Array;
+    }>): Promise<EditableArtifactLiveMutationReceipt>;
+    reconcileNow(): Promise<void>;
+    reauthorizeNow(): Promise<void>;
+    close(reason?: EditableArtifactLiveCloseReason): Promise<void>;
+}
+export declare class EditableArtifactLiveServer {
+    private readonly dependencies;
+    private readonly options;
+    private readonly ticketAuthority;
+    constructor(dependencies: EditableArtifactLiveServerDependencies, options?: EditableArtifactLiveServerOptions);
+    mintTicket(input: Readonly<{
+        scope: EditableArtifactScope;
+        artifactId: EditableArtifactId;
+        modality: EditableArtifactModality;
+        actor: EditableArtifactActor;
+        allowEdit: boolean;
+    }>): Promise<EditableArtifactLiveTicket>;
+    openLive(input: OpenEditableArtifactLiveInput): Promise<EditableArtifactLiveSession>;
+}
+export declare class SystemEditableArtifactLiveClock implements EditableArtifactLiveClockPort {
+    now(): Date;
+}
+export declare class SystemEditableArtifactLiveScheduler implements EditableArtifactLiveSchedulerPort {
+    sleep(milliseconds: number, signal: AbortSignal): Promise<void>;
+}
+export type { EditableArtifactAuthorizationPort, EditableArtifactService, EditableArtifactLiveAuthorizationInvalidationPort, EditableArtifactLiveHintPort, EditableArtifactLiveReadPort, EditableArtifactLiveSchedulerPort, EditableArtifactLiveSinkPort, EditableArtifactLiveTicketStorePort, EditableArtifactLiveTokenPort, };