@opengeni/core 0.21.10 → 0.28.0

package/dist/domain/conversation-integrations.d.ts

@@ -0,0 +1,225 @@
+declare const conversationProviderNamespaceBrand: unique symbol;
+declare const conversationProviderOpaqueValueBrand: unique symbol;
+declare const conversationEventIdentityBrand: unique symbol;
+declare const conversationRouteIdentityBrand: unique symbol;
+declare const conversationActorIdentityBrand: unique symbol;
+declare const conversationOperationIdentityBrand: unique symbol;
+declare const conversationRequestDigestBrand: unique symbol;
+export declare const CONVERSATION_INTEGRATION_SCHEMA_VERSION: 1;
+export declare const CONVERSATION_PROVIDER_NAMESPACE_MAX_UTF8_BYTES = 128;
+export declare const CONVERSATION_PROVIDER_OPAQUE_ID_MAX_UTF8_BYTES = 512;
+export declare const CONVERSATION_TEXT_MAX_UTF8_BYTES: number;
+export declare const CONVERSATION_ATTACHMENT_MAX_COUNT = 16;
+export declare const CONVERSATION_ATTACHMENT_NAME_MAX_UTF8_BYTES = 1024;
+export declare const CONVERSATION_ATTACHMENT_MEDIA_TYPE_MAX_UTF8_BYTES = 128;
+export declare const CONVERSATION_OPERATION_KEY_MAX_UTF8_BYTES = 512;
+export declare const CONVERSATION_OUTCOME_CODE_MAX_UTF8_BYTES = 128;
+export type ConversationProviderNamespace = string & {
+    readonly [conversationProviderNamespaceBrand]: true;
+};
+export type ConversationProviderOpaqueValue = string & {
+    readonly [conversationProviderOpaqueValueBrand]: true;
+};
+export type ConversationProviderOpaqueIdKind = "installation" | "actor" | "conversation" | "thread" | "event" | "message" | "attachment" | "receipt";
+export type ConversationProviderOpaqueId<TKind extends ConversationProviderOpaqueIdKind = ConversationProviderOpaqueIdKind> = Readonly<{
+    provider: ConversationProviderNamespace;
+    kind: TKind;
+    value: ConversationProviderOpaqueValue;
+}>;
+export type ConversationInstallationIdentity = ConversationProviderOpaqueId<"installation">;
+export type ConversationEventIdentity = `ciev1_${string}` & {
+    readonly [conversationEventIdentityBrand]: true;
+};
+export type ConversationRouteIdentity = `cirt1_${string}` & {
+    readonly [conversationRouteIdentityBrand]: true;
+};
+export type ConversationActorIdentity = `ciac1_${string}` & {
+    readonly [conversationActorIdentityBrand]: true;
+};
+export type ConversationOperationIdentity = `ciop1_${string}` & {
+    readonly [conversationOperationIdentityBrand]: true;
+};
+export type ConversationRequestDigest = `sha256:${string}` & {
+    readonly [conversationRequestDigestBrand]: true;
+};
+export type ConversationActorKind = "human" | "bot" | "system";
+export type ConversationActorInput = Readonly<{
+    providerActorId: string;
+    kind: ConversationActorKind;
+}>;
+export type ConversationActor = Readonly<{
+    installation: ConversationInstallationIdentity;
+    providerActorId: ConversationProviderOpaqueId<"actor">;
+    kind: ConversationActorKind;
+    identity: ConversationActorIdentity;
+}>;
+export type ConversationRoute = Readonly<{
+    installation: ConversationInstallationIdentity;
+    providerConversationId: ConversationProviderOpaqueId<"conversation">;
+    providerThreadId: ConversationProviderOpaqueId<"thread"> | null;
+    identity: ConversationRouteIdentity;
+}>;
+export type ConversationRouteInput = Readonly<{
+    providerConversationId: string;
+    providerThreadId?: string | null;
+}>;
+export type ConversationStartSignal = Readonly<{
+    kind: "start";
+}>;
+export type ConversationContinueSignal = Readonly<{
+    kind: "continue";
+}>;
+export type ConversationControlSignal = Readonly<{
+    kind: "control";
+    control: "stop" | "resume";
+}>;
+export type ConversationSignal = ConversationStartSignal | ConversationContinueSignal | ConversationControlSignal;
+export type ConversationAttachmentReference = Readonly<{
+    providerAttachmentId: ConversationProviderOpaqueId<"attachment">;
+    fileName: string | null;
+    mediaType: string | null;
+    byteSize: number | null;
+    contentSha256: string | null;
+}>;
+export type ConversationAttachmentReferenceInput = Readonly<{
+    providerAttachmentId: string;
+    fileName?: string | null;
+    mediaType?: string | null;
+    byteSize?: number | null;
+    contentSha256?: string | null;
+}>;
+export type ConversationInboundEnvelope = Readonly<{
+    schemaVersion: typeof CONVERSATION_INTEGRATION_SCHEMA_VERSION;
+    installation: ConversationInstallationIdentity;
+    actor: ConversationActor;
+    route: ConversationRoute;
+    providerEventId: ConversationProviderOpaqueId<"event">;
+    providerMessageId: ConversationProviderOpaqueId<"message">;
+    eventIdentity: ConversationEventIdentity;
+    occurredAt: string;
+    signal: ConversationSignal;
+    text: string;
+    attachments: readonly ConversationAttachmentReference[];
+}>;
+export type ConversationInboundEnvelopeInput = Readonly<{
+    provider: string;
+    installationId: string;
+    actor: ConversationActorInput;
+    route: ConversationRouteInput;
+    providerEventId: string;
+    providerMessageId: string;
+    occurredAt: string;
+    signal: ConversationSignal;
+    text: string;
+    attachments?: readonly ConversationAttachmentReferenceInput[];
+}>;
+type ConversationDeliveryCommandBase = Readonly<{
+    schemaVersion: typeof CONVERSATION_INTEGRATION_SCHEMA_VERSION;
+    operationId: ConversationOperationIdentity;
+    logicalOperationKey: string;
+    requestDigest: ConversationRequestDigest;
+    installation: ConversationInstallationIdentity;
+    route: ConversationRoute;
+}>;
+export type ConversationPostCommand = ConversationDeliveryCommandBase & Readonly<{
+    kind: "post";
+    targetProviderMessageId: null;
+    text: string;
+}>;
+export type ConversationUpdateCommand = ConversationDeliveryCommandBase & Readonly<{
+    kind: "update";
+    targetProviderMessageId: ConversationProviderOpaqueId<"message">;
+    text: string;
+}>;
+export type ConversationDeleteCommand = ConversationDeliveryCommandBase & Readonly<{
+    kind: "delete";
+    targetProviderMessageId: ConversationProviderOpaqueId<"message">;
+    text: null;
+}>;
+export type ConversationDeliveryCommand = ConversationPostCommand | ConversationUpdateCommand | ConversationDeleteCommand;
+export type ConversationDeliveryCommandInput = Readonly<{
+    kind: "post";
+    logicalOperationKey: string;
+    installation: ConversationInstallationIdentity;
+    route: ConversationRoute;
+    text: string;
+}> | Readonly<{
+    kind: "update";
+    logicalOperationKey: string;
+    installation: ConversationInstallationIdentity;
+    route: ConversationRoute;
+    targetProviderMessageId: string;
+    text: string;
+}> | Readonly<{
+    kind: "delete";
+    logicalOperationKey: string;
+    installation: ConversationInstallationIdentity;
+    route: ConversationRoute;
+    targetProviderMessageId: string;
+}>;
+export type ConversationProviderReceipt = Readonly<{
+    schemaVersion: typeof CONVERSATION_INTEGRATION_SCHEMA_VERSION;
+    operationId: ConversationOperationIdentity;
+    requestDigest: ConversationRequestDigest;
+    installation: ConversationInstallationIdentity;
+    providerMessageId: ConversationProviderOpaqueId<"message">;
+    providerReceiptId: ConversationProviderOpaqueId<"receipt"> | null;
+    observedAt: string;
+}>;
+export type ConversationProviderReceiptInput = Readonly<{
+    command: ConversationDeliveryCommand;
+    providerMessageId: string;
+    providerReceiptId?: string | null;
+    observedAt: string;
+}>;
+export type ConversationDeliveryNotStarted = Readonly<{
+    status: "not_started";
+    code: string;
+}>;
+export type ConversationDeliveryUnknown = Readonly<{
+    status: "unknown";
+    code: string;
+}>;
+export type ConversationDeliveryRetryableFailure = Readonly<{
+    status: "retryable_failure";
+    code: string;
+    retryAfterMs: number | null;
+}>;
+export type ConversationDeliveryPermanentFailure = Readonly<{
+    status: "permanent_failure";
+    code: string;
+}>;
+export type ConversationDeliverySuccess = Readonly<{
+    status: "success";
+    receipt: ConversationProviderReceipt;
+}>;
+export type ConversationDeliveryOutcome = ConversationDeliveryNotStarted | ConversationDeliveryUnknown | ConversationDeliveryRetryableFailure | ConversationDeliveryPermanentFailure | ConversationDeliverySuccess;
+export type ConversationDeliveryOutcomeInput = ConversationDeliveryNotStarted | ConversationDeliveryUnknown | Readonly<{
+    status: "retryable_failure";
+    code: string;
+    retryAfterMs?: number | null;
+}> | ConversationDeliveryPermanentFailure | ConversationDeliverySuccess;
+export type ConversationDeliveryNextAction = "retry_same_operation" | "reconcile" | "stop" | "complete";
+export declare function normalizeConversationInboundEnvelope(input: ConversationInboundEnvelopeInput): ConversationInboundEnvelope;
+export declare function normalizeConversationProviderNamespace(value: string): ConversationProviderNamespace;
+export declare function normalizeConversationInstallationIdentity(input: {
+    provider: string | ConversationProviderNamespace;
+    providerInstallationId: string;
+}): ConversationInstallationIdentity;
+export declare function normalizeConversationActor(installation: ConversationInstallationIdentity, input: ConversationActorInput): ConversationActor;
+export declare function normalizeConversationRoute(installation: ConversationInstallationIdentity, input: ConversationRouteInput): ConversationRoute;
+export declare function normalizeConversationDeliveryCommand(input: ConversationDeliveryCommandInput): ConversationDeliveryCommand;
+export declare function normalizeConversationProviderReceipt(input: ConversationProviderReceiptInput): ConversationProviderReceipt;
+export declare function normalizeConversationDeliveryOutcome(input: ConversationDeliveryOutcomeInput): ConversationDeliveryOutcome;
+export declare function conversationDeliveryNextAction(outcome: ConversationDeliveryOutcome): ConversationDeliveryNextAction;
+export declare function assertConversationDeliveryMayRetry(outcome: ConversationDeliveryOutcome): asserts outcome is ConversationDeliveryNotStarted | ConversationDeliveryRetryableFailure;
+export declare function assertConversationDeliveryCommandMatches(expected: ConversationDeliveryCommand, candidate: ConversationDeliveryCommand): void;
+export declare function assertConversationInboundEnvelope(value: unknown): asserts value is ConversationInboundEnvelope;
+export declare function assertConversationDeliveryCommand(value: unknown): asserts value is ConversationDeliveryCommand;
+export declare function assertConversationProviderReceipt(value: unknown): asserts value is ConversationProviderReceipt;
+export declare function assertConversationDeliveryOutcome(value: unknown): asserts value is ConversationDeliveryOutcome;
+export declare function canonicalConversationInboundEnvelopeJson(envelope: ConversationInboundEnvelope): string;
+export declare function canonicalConversationDeliveryCommandJson(command: ConversationDeliveryCommand): string;
+export declare function canonicalConversationProviderReceiptJson(receipt: ConversationProviderReceipt): string;
+export declare function canonicalConversationDeliveryOutcomeJson(outcome: ConversationDeliveryOutcome): string;
+export {};

package/dist/domain/durable-learning-slack-publication.d.ts

@@ -0,0 +1,72 @@
+import { type Database, type EnqueueMemorySlackPublicationResult } from "@opengeni/db";
+/**
+ * Narrow post-persistence port for the immutable durable-learning v1 attempt/receipt contract.
+ * The router owns validation, authority, routing, and persistence. This adapter
+ * consumes only the fields required to create a bounded notification projection.
+ */
+export type DurableLearningSlackOutcome = {
+    attempt: {
+        id: string;
+        accountId: string;
+        workspaceId: string;
+        inputHash: string;
+        actor: {
+            kind: "human" | "agent" | "service";
+            subjectId: string;
+        };
+        initiatingHumanSubjectId: string | null;
+        sessionId: string | null;
+        request: {
+            operation: "write";
+            subject: {
+                kind: string;
+                summary: string | null;
+            };
+            evidence: Array<{
+                kind: string;
+            }>;
+        } | {
+            operation: "rollback";
+            targetAttemptId: string;
+        };
+    };
+    receipt: {
+        attemptId: string;
+        inputHash: string;
+        outcome: "applied" | "proposed" | "evidence_recorded" | "noop" | "clarification_required" | "rejected" | "rolled_back" | "failed";
+        decision: {
+            code: string;
+            destination: string | null;
+            scope: {
+                kind: string;
+            } | null;
+            authority: string | null;
+        };
+        resource: {
+            surface: string;
+            id: string;
+            version: string | null;
+            status: string;
+        } | null;
+        createdAt: string;
+    };
+};
+export type DurableLearningSlackPublicationResult = {
+    kind: "contract_mismatch" | "not_workspace_scoped" | "connector_evidence_untrusted" | "summary_required" | "policy_quiet";
+    enqueue: null;
+} | {
+    kind: "enqueued";
+    enqueue: EnqueueMemorySlackPublicationResult;
+};
+export type DurableLearningSlackProjection = {
+    summary: string;
+    outcome: DurableLearningSlackOutcome["receipt"]["outcome"];
+    decisionCode: string;
+    destination: string | null;
+    authority: string | null;
+    resource: DurableLearningSlackOutcome["receipt"]["resource"];
+    occurredAt: string;
+};
+export declare function publishDurableLearningOutcomeToSlack(db: Database, outcome: DurableLearningSlackOutcome): Promise<DurableLearningSlackPublicationResult>;
+export declare function durableLearningImportance(outcome: DurableLearningSlackOutcome): "major" | "normal" | "minor";
+export declare function durableLearningSlackProjection(outcome: DurableLearningSlackOutcome): DurableLearningSlackProjection | null;

package/dist/domain/editable-artifacts/agent-application.d.ts

@@ -0,0 +1,192 @@
+import { type DocumentArtifactCommand, type DocumentArtifactQuery, type PresentationArtifactCommand, type PresentationArtifactQuery, type SpreadsheetArtifactCommand, type SpreadsheetArtifactKernelQuery } from "@opengeni/contracts/editable-artifacts";
+import type { EditableArtifactDurableExportService, EditableArtifactMaterializationFormat, EditableArtifactMaterializationJob } from "./durable-export.js";
+import type { EditableArtifactService } from "./service.js";
+import { type EditableArtifact, type EditableArtifactActor, type EditableArtifactClientTransactionId, type EditableArtifactId, type EditableArtifactModality, type EditableArtifactOriginalImport, type EditableArtifactScope, type ImportEditableArtifactRequest } from "./types.js";
+import type { EditableArtifactKernelState } from "./ports.js";
+export type EditableArtifactAgentCommandBatch = Readonly<{
+    modality: "spreadsheet";
+    commands: readonly SpreadsheetArtifactCommand[];
+}> | Readonly<{
+    modality: "document";
+    commands: readonly DocumentArtifactCommand[];
+}> | Readonly<{
+    modality: "presentation";
+    commands: readonly PresentationArtifactCommand[];
+}>;
+export type EditableArtifactAgentQuery = Readonly<{
+    modality: "spreadsheet";
+    query: SpreadsheetArtifactKernelQuery;
+}> | Readonly<{
+    modality: "document";
+    query: DocumentArtifactQuery;
+}> | Readonly<{
+    modality: "presentation";
+    query: PresentationArtifactQuery;
+}>;
+export type EditableArtifactAgentContext = Readonly<{
+    scope: EditableArtifactScope;
+    actor: EditableArtifactActor;
+    sessionId: string;
+}>;
+export type EditableArtifactAgentMetadata = Readonly<{
+    id: string;
+    modality: EditableArtifactModality;
+    title: string;
+    lifecycle: EditableArtifact["lifecycle"];
+    headSequence: number;
+    stateHash: string;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type EditableArtifactAgentMutationReceipt = Readonly<{
+    artifact: EditableArtifactAgentMetadata;
+    transaction: Readonly<{
+        id: string;
+        clientTransactionId: string;
+        sequenceStart: number;
+        sequenceEnd: number;
+        stateHash: string;
+        committedAt: string;
+        replayed: boolean;
+    }>;
+}>;
+export type EditableArtifactAgentExportReceipt = Readonly<{
+    fileId: string;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    sha256: string;
+    artifactId: string;
+    versionId: string;
+    materializationJobId: string;
+    sourceHeadSequence: number;
+    sourceStateHash: string;
+}>;
+export type PreparedEditableArtifactImport = Readonly<{
+    originalImport: EditableArtifactOriginalImport;
+    snapshot: ImportEditableArtifactRequest["snapshot"];
+}>;
+export type EditableArtifactOfficeImportErrorCode = "invalid_source" | "source_changed" | "unsupported_content";
+export declare class EditableArtifactOfficeImportError extends Error {
+    readonly code: EditableArtifactOfficeImportErrorCode;
+    constructor(code: EditableArtifactOfficeImportErrorCode);
+}
+export interface EditableArtifactAgentAssociationPort {
+    listArtifactIds(input: {
+        scope: EditableArtifactScope;
+        sessionId: string;
+        limit: number;
+    }): Promise<readonly EditableArtifactId[]>;
+    touch(input: {
+        scope: EditableArtifactScope;
+        sessionId: string;
+        artifactId: EditableArtifactId;
+    }): Promise<void>;
+}
+export interface EditableArtifactAgentInspectionKernelPort {
+    query(input: {
+        state: EditableArtifactKernelState;
+        queryBytes: Uint8Array;
+    }): Promise<Uint8Array>;
+}
+export interface EditableArtifactOfficeImportPort {
+    prepare(input: {
+        scope: EditableArtifactScope;
+        actor: EditableArtifactActor;
+        fileId: string;
+        modality: EditableArtifactModality;
+        signal?: AbortSignal;
+    }): Promise<PreparedEditableArtifactImport>;
+}
+export interface EditableArtifactAgentWorkspaceFilePort {
+    ensureMaterializationFile(input: {
+        scope: EditableArtifactScope;
+        actor: EditableArtifactActor;
+        artifact: EditableArtifact;
+        versionId: string;
+        jobId: string;
+        filename: string;
+        sourceHeadSequence: number;
+        sourceStateHash: string;
+        signal?: AbortSignal;
+    }): Promise<EditableArtifactAgentExportReceipt>;
+}
+export type EditableArtifactAgentApplicationDependencies = Readonly<{
+    domain: EditableArtifactService;
+    exports: EditableArtifactDurableExportService;
+    associations: EditableArtifactAgentAssociationPort;
+    inspector: EditableArtifactAgentInspectionKernelPort;
+    officeImports: EditableArtifactOfficeImportPort;
+    workspaceFiles: EditableArtifactAgentWorkspaceFilePort;
+}>;
+/**
+ * Attempt-neutral use cases shared by direct model tools and Codemode. This is
+ * not another artifact engine: every mutation terminates at EditableArtifactService.
+ */
+export declare class EditableArtifactAgentApplication {
+    private readonly dependencies;
+    constructor(dependencies: EditableArtifactAgentApplicationDependencies);
+    list(input: EditableArtifactAgentContext & Readonly<{
+        limit?: number;
+    }>): Promise<readonly EditableArtifactAgentMetadata[]>;
+    create(input: EditableArtifactAgentContext & Readonly<{
+        idempotencyKey: EditableArtifactClientTransactionId;
+        modality: EditableArtifactModality;
+        title: string;
+        signal?: AbortSignal;
+    }>): Promise<EditableArtifactAgentMetadata>;
+    import(input: EditableArtifactAgentContext & Readonly<{
+        idempotencyKey: EditableArtifactClientTransactionId;
+        fileId: string;
+        modality: EditableArtifactModality;
+        title: string;
+        signal?: AbortSignal;
+    }>): Promise<EditableArtifactAgentMetadata>;
+    get(input: EditableArtifactAgentContext & Readonly<{
+        artifactId: EditableArtifactId;
+    }>): Promise<EditableArtifactAgentMetadata>;
+    inspect(input: EditableArtifactAgentContext & Readonly<{
+        artifactId: EditableArtifactId;
+        request: EditableArtifactAgentQuery;
+    }>): Promise<Readonly<{
+        artifact: EditableArtifactAgentMetadata;
+        projection: unknown;
+    }>>;
+    apply(input: EditableArtifactAgentContext & Readonly<{
+        artifactId: EditableArtifactId;
+        clientTransactionId: EditableArtifactClientTransactionId;
+        expectedHeadSequence: number;
+        expectedStateHash: string;
+        batch: EditableArtifactAgentCommandBatch;
+    }>): Promise<EditableArtifactAgentMutationReceipt>;
+    startExport(input: EditableArtifactAgentContext & Readonly<{
+        artifactId: EditableArtifactId;
+        idempotencyKey: string;
+        format: EditableArtifactMaterializationFormat;
+        options?: Readonly<Record<string, unknown>>;
+        signal?: AbortSignal;
+    }>): Promise<Readonly<{
+        artifact: EditableArtifactAgentMetadata;
+        versionId: string;
+        jobId: string;
+        sourceHeadSequence: number;
+        sourceStateHash: string;
+        state: EditableArtifactMaterializationJob["state"];
+    }>>;
+    exportStatus(input: EditableArtifactAgentContext & Readonly<{
+        artifactId: EditableArtifactId;
+        versionId: string;
+        jobId: string;
+        signal?: AbortSignal;
+    }>): Promise<Readonly<{
+        artifact: EditableArtifactAgentMetadata;
+        versionId: string;
+        jobId: string;
+        sourceHeadSequence: number;
+        sourceStateHash: string;
+        state: EditableArtifactMaterializationJob["state"];
+        errorCode: string | null;
+        file: EditableArtifactAgentExportReceipt | null;
+    }>>;
+    private touch;
+}

package/dist/domain/editable-artifacts/durable-export-postgres.d.ts

@@ -0,0 +1,4 @@
+import { type PostgresEditableArtifactDurableExportStore } from "@opengeni/db/editable-artifact-durable-export";
+import { type EditableArtifactDurableExportStorePort } from "./durable-export.js";
+/** One-way adapter keeps @opengeni/db free of the core package cycle. */
+export declare function editableArtifactDurableExportStorePortFromPostgres(store: PostgresEditableArtifactDurableExportStore): EditableArtifactDurableExportStorePort;