@opengeni/core 0.21.2 → 0.24.1

package/dist/domain/scheduled-tasks.d.ts

@@ -1,8 +1,8 @@
 import type { Settings } from "@opengeni/config";
-import type { AccessGrant, McpPersonalConnectionDelegation, ScheduledTask, CreateScheduledTaskRequest as CreateScheduledTaskPayload, UpdateScheduledTaskRequest as UpdateScheduledTaskPayload } from "@opengeni/contracts";
+import type { AccessGrant, McpPersonalConnectionDelegation, ScheduledTask, ScheduledTaskAgentConfig, Session, SessionAuthorizationPort, SessionAuthorizationSurface, CreateScheduledTaskRequest as CreateScheduledTaskPayload, UpdateScheduledTaskRequest as UpdateScheduledTaskPayload } from "@opengeni/contracts";
 import { type Database, type UpdateScheduledTaskInput } from "@opengeni/db";
-import type { SessionWorkflowClient } from "../dependencies";
-import type { ObjectStorageDependency } from "../dependencies";
+import type { SessionWorkflowClient } from "../dependencies.js";
+import type { ObjectStorageDependency } from "../dependencies.js";
 /**
  * Whether a raw scheduled-task payload explicitly set agentConfig.tools.
  * Zod's `.default([])` erases the distinction between "absent" and
@@ -20,7 +20,25 @@ export declare function createValidatedScheduledTask(input: {
     payload: CreateScheduledTaskPayload;
     toolsProvided?: boolean;
     variableSetPreauthorized?: boolean;
+    sessionAuthorization?: SessionAuthorizationPort | null | undefined;
+    authorizationSurface?: SessionAuthorizationSurface | undefined;
 }): Promise<ScheduledTask>;
+export declare function validateScheduledTaskTarget(input: {
+    db: Database;
+    sessionAuthorization?: SessionAuthorizationPort | null | undefined;
+    authorizationSurface?: SessionAuthorizationSurface | undefined;
+    grant: AccessGrant;
+    targetSessionId: string | null | undefined;
+    runMode: ScheduledTask["runMode"];
+    variableSetId: string | null | undefined;
+    rigId: string | null | undefined;
+    agentConfig: ScheduledTaskAgentConfig;
+    missingTargetStatus?: 404 | 422;
+}): Promise<Session | null>;
+export declare function scheduledTaskForGrant(task: ScheduledTask, grant: AccessGrant): ScheduledTask;
+export declare function scheduledTaskRunForGrant<T extends {
+    sessionId: string | null;
+}>(run: T, grant: AccessGrant): T;
 export declare function validatedScheduledTaskUpdate(input: {
     settings: Settings;
     db: Database;
@@ -30,6 +48,8 @@ export declare function validatedScheduledTaskUpdate(input: {
     payload: UpdateScheduledTaskPayload;
     /** See createValidatedScheduledTask; only consulted when agentConfig is updated. */
     toolsProvided?: boolean;
+    sessionAuthorization?: SessionAuthorizationPort | null | undefined;
+    authorizationSurface?: SessionAuthorizationSurface | undefined;
 }): Promise<UpdateScheduledTaskInput>;
 export declare function requireScheduledTaskForApi(db: Database, workspaceId: string, taskId: string): Promise<ScheduledTask>;
 export type ScheduledTaskRestoreState = {
@@ -38,6 +58,10 @@ export type ScheduledTaskRestoreState = {
 };
 export declare function captureScheduledTaskRestoreState(db: Database, task: ScheduledTask): Promise<ScheduledTaskRestoreState>;
 export declare function restoreScheduledTask(db: Database, previous: ScheduledTaskRestoreState): Promise<ScheduledTask>;
+export declare class ScheduledTaskSyncError extends Error {
+    readonly persistenceRestored: boolean;
+    constructor(cause: unknown, persistenceRestored: boolean);
+}
 export declare function syncCreatedScheduledTask(input: {
     db: Database;
     workflowClient: SessionWorkflowClient;

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 } 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;
@@ -49,7 +49,20 @@ export type FrozenCreationInitiator = {
 };
 export declare function creationInitiatorForGrant(grant: AccessGrant): FrozenCreationInitiator;
 export declare function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings;
-export declare function createAndStartSession(input: {
+export type CreateSessionOutcome = {
+    session: CreateSessionResponse;
+    /** The committed create/start effect represented by this request. */
+    outcome: "created" | "repaired" | "replayed";
+    /** Backward-compatible replay flag for existing entity-oriented callers. */
+    replay: boolean;
+    /** True when the request created/repaired start state or committed a new wake revision. */
+    changed: boolean;
+};
+export type CreateSessionRequestOutcome = CreateSessionOutcome & {
+    /** Billing telemetry is recorded after the committed session start. */
+    usageRecording: "recorded" | "failed";
+};
+export declare function createAndStartSessionWithOutcome(input: {
     requestedSessionId?: string;
     db: Database;
     bus: EventBus;
@@ -107,7 +120,9 @@ export declare function createAndStartSession(input: {
     maxNestedAgentDepthOverride?: number | null;
     allowNestedAgentDepthIncrease?: boolean;
     subjectId?: string | null;
-}): Promise<CreateSessionResponse>;
+}): Promise<CreateSessionOutcome>;
+/** Backward-compatible entity-returning create path used by existing callers. */
+export declare function createAndStartSession(input: Parameters<typeof createAndStartSessionWithOutcome>[0]): Promise<CreateSessionResponse>;
 export declare function workflowIdForSession(sessionId: string): string;
 /**
  * Reject an explicit model that the host does not expose. The set of usable
@@ -116,10 +131,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
@@ -170,6 +185,7 @@ export declare function postUserMessageTurn(input: {
     workspaceId: string;
     sessionId: string;
     text: string;
+    annotations?: TimelineAnnotation[];
     turnInstructions?: string | null;
     resources: ResourceRef[];
     model?: string | null;
@@ -187,9 +203,13 @@ 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;
 }>;
 /**
  * Full create-session flow shared by `POST /sessions` and the first-party MCP
@@ -200,7 +220,11 @@ export declare function postUserMessageTurn(input: {
  * trusted immediate parent, while explicit arrays (including []) win. A
  * top-level create with omitted tools applies workspace-default capability MCPs.
  */
-export declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<Session>;
+export declare function createSessionForRequestWithOutcome(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<CreateSessionRequestOutcome>;
+/** @internal Fixed public projection; the committed session outcome remains authoritative. */
+export declare function reportSessionUsageRecordingFailure(_error: unknown): void;
+/** Backward-compatible entity-returning request path for REST and core callers. */
+export declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<CreateSessionResponse>;
 /**
  * Full accept-user-message flow shared by the `user.message` branch of
  * `POST /sessions/:id/events` and the first-party MCP `session_send_message`
@@ -208,8 +232,9 @@ export declare function createSessionForRequest(deps: ApiRouteDeps, grant: Acces
  * enqueue, and usage recording. `toolsProvided: false` durably preserves an
  * Tool selection is durable session state and never rides a follow-up prompt.
  */
-export declare function acceptSessionUserMessage(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
+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;
@@ -224,6 +249,15 @@ export declare function acceptSessionUserMessage(deps: AcceptSessionUserMessageD
 }): 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,9 @@
+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 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;
+}>;