@opengeni/db 0.28.9 → 0.36.0

package/dist/knowledge-source-sync.d.ts

@@ -0,0 +1,274 @@
+import { type FileAsset, KnowledgeSourceSyncRunSummary, type ScheduledTask } from "@opengeni/contracts";
+import type { Database } from "./database.js";
+export type KnowledgeSourceSyncState = {
+    sourceId: string;
+    scheduledTaskId: string;
+    sourceSyncGeneration: number;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    executionCheckpoint: Record<string, unknown> | null;
+    executionCheckpointGeneration: number;
+    activeScanGeneration: number;
+    providerCursor: Record<string, unknown> | null;
+    wakeRevision: number;
+    pendingWakeCount: number;
+    bufferedWake: boolean;
+    bufferedScheduledTaskRunId: string | null;
+    reconnectRequired: boolean;
+    lastSuccessAt: string | null;
+    lastCompletedAt: string | null;
+    lastSummary: ReturnType<typeof KnowledgeSourceSyncRunSummary.parse> | null;
+};
+export type KnowledgeSourceSyncObservationFloor = {
+    externalObjectId: string;
+    providerRevision: string | null;
+    metadataHash: string | null;
+};
+export type KnowledgeSourceSyncObservationFence = {
+    initiatingSubjectId: string;
+    scanGeneration: number;
+    executionCheckpointGeneration: number;
+    observations: KnowledgeSourceSyncObservationFloor[];
+};
+export type KnowledgeSourceSyncObjectObservationResult = KnowledgeSourceSyncObservationFloor & {
+    disposition: "accepted" | "replayed" | "stale" | "conflict";
+    currentVersion: {
+        providerRevision: string | null;
+        metadataHash: string | null;
+        sourceLifecycleGeneration: number;
+        objectLifecycleGeneration: number;
+        currentObjectLifecycleGeneration: number;
+        objectLifecycleState: string;
+        aclGeneration: number;
+        indexObligationStatus: string | null;
+    } | null;
+};
+export declare function compareCanonicalDecimalProviderRevisions(candidate: string | null, floor: string | null): -1 | 0 | 1 | null;
+export declare function ensureKnowledgeSourceSyncState(db: Database, task: ScheduledTask): Promise<KnowledgeSourceSyncState>;
+export declare function reconcileKnowledgeSourceSyncLiveGeneration(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    initiatingSubjectId: string;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    liveSourceSyncGeneration: number;
+}): Promise<KnowledgeSourceSyncState>;
+export declare function recordKnowledgeSourceSyncWake(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskId: string;
+    scheduledTaskRunId: string;
+    cause: "scheduled" | "manual" | "initial" | "provider_event" | "retry" | "repair";
+    producerKey: string;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+}): Promise<void>;
+export declare function claimKnowledgeSourceSyncLease(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    overlapPolicy: "skip" | "buffer_one";
+    leaseMs?: number;
+}): Promise<{
+    action: "claimed";
+    state: KnowledgeSourceSyncState;
+} | {
+    action: "skipped" | "buffered";
+    state: KnowledgeSourceSyncState;
+}>;
+export declare function checkpointKnowledgeSourceSync(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    executionCheckpoint: Record<string, unknown>;
+    observationFence?: KnowledgeSourceSyncObservationFence;
+}): Promise<KnowledgeSourceSyncState>;
+export declare function settleKnowledgeSourceSyncLease(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    knowledgeSyncRunId?: string | null;
+    status: "succeeded" | "failed";
+    summary: ReturnType<typeof KnowledgeSourceSyncRunSummary.parse>;
+    error?: string | null;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    sourceSyncGeneration: number;
+    completedSourceSyncGeneration?: number | null;
+    executionCheckpoint?: Record<string, unknown> | null;
+    providerCursor?: Record<string, unknown> | null;
+    observationFence?: KnowledgeSourceSyncObservationFence;
+}): Promise<{
+    bufferedWake: boolean;
+    bufferedScheduledTaskRunId: string | null;
+}>;
+export declare function listObservedKnowledgeSourceSyncExternalObjectIds(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    externalObjectIds: string[];
+}): Promise<Set<string>>;
+/**
+ * Release only the exact active lease after a retryable DB safety obligation
+ * fails. The wake and scheduled-task run deliberately remain open so Temporal
+ * can reclaim the same deterministic run; no provider checkpoint survives a
+ * reconnect/permission-loss failure.
+ */
+export declare function releaseKnowledgeSourceSyncLeaseForRetry(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+}): Promise<void>;
+export declare function completeKnowledgeSourceSyncWakeWithoutLease(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+}): Promise<void>;
+export declare function recordKnowledgeSourceSyncItemOutcomes(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    scheduledTaskRunId: string;
+    knowledgeSyncRunId?: string | null;
+    sourceId: string;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    outcomes: Array<{
+        externalObjectId: string;
+        outcome: "imported" | "unchanged" | "skipped" | "failed" | "tombstoned";
+        reasonCode?: string | null;
+        detail?: string | null;
+        contentSha256?: string | null;
+        sizeBytes?: number | null;
+        providerRevision?: string | null;
+        metadataHash?: string | null;
+        aclEligibility?: "pending" | "eligible" | "denied";
+        aclEvidence?: Record<string, unknown> | null;
+        indexObligationId?: string | null;
+    }>;
+}): Promise<void>;
+export declare function recordKnowledgeSourceSyncObjectObservations(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    initiatingSubjectId: string;
+    scanGeneration: number;
+    executionCheckpointGeneration: number;
+    revisionOrdering?: "first_observation" | "canonical_decimal";
+    observations: Array<{
+        externalObjectId: string;
+        providerRevision?: string | null;
+        metadataHash?: string | null;
+    }>;
+}): Promise<KnowledgeSourceSyncObjectObservationResult[]>;
+export declare function reconcileKnowledgeSourceSyncCompleteScan(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sourceId: string;
+    scheduledTaskRunId: string;
+    initiatingSubjectId: string;
+    sourceSyncGeneration: number;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    scanGeneration: number;
+}): Promise<string[]>;
+export declare function getKnowledgeSourceSyncIndexObligationForVersion(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    knowledgeDocumentVersionId: string;
+    initiatingSubjectId: string;
+}): Promise<{
+    id: string;
+    status: string;
+    aclEligibility: string;
+    sourceSyncGeneration: number;
+    documentId: string;
+} | null>;
+export declare function enqueueKnowledgeSourceSyncIndexObligation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    scheduledTaskRunId: string;
+    sourceId: string;
+    sourceSyncGeneration: number;
+    initiatingSubjectId: string;
+    externalObjectId: string;
+    knowledgeSourceObjectId: string;
+    knowledgeDocumentVersionId: string;
+    documentId: string;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    objectLifecycleGeneration: number;
+    objectVersionGeneration: number;
+    citationLocator: Record<string, unknown>;
+}): Promise<{
+    id: string;
+    status: string;
+    aclEligibility: string;
+    sourceSyncGeneration: number;
+    documentId: string;
+}>;
+/**
+ * Re-open a transiently failed index obligation only while its complete
+ * source/object/version authority is still current. The immutable obligation
+ * identity and original source-sync generation remain intact; the new task run
+ * merely becomes the retry owner.
+ */
+export declare function retryKnowledgeSourceSyncIndexObligation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    obligationId: string;
+    scheduledTaskRunId: string;
+}): Promise<"pending" | "indexed" | "invalidated">;
+export declare function recordKnowledgeSourceSyncAclEvidence(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    obligationId: string;
+    sourceSyncGeneration: number;
+    sourceConfigGeneration: number;
+    sourceLifecycleGeneration: number;
+    objectLifecycleGeneration: number;
+    objectVersionGeneration: number;
+    eligibility: "eligible" | "denied";
+    evidence: Record<string, unknown>;
+}): Promise<void>;
+/** Bounded retention hook. Callers choose policy and cadence; pending index or
+ * ACL obligations are never deleted by age alone. */
+export declare function pruneKnowledgeSourceSyncEvidence(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    before: Date;
+    limit?: number;
+}): Promise<{
+    itemOutcomes: number;
+    wakes: number;
+    indexObligations: number;
+}>;
+export declare function settleKnowledgeSourceSyncIndexObligation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    obligationId: string;
+    status: "indexed" | "failed" | "invalidated";
+    failureCode?: string | null;
+}): Promise<"settled" | "invalidated">;
+export declare function ensureKnowledgeSourceBlobFile(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    fileId: string;
+    filename: string;
+    safeFilename: string;
+    contentType: string;
+    sizeBytes: number;
+    sha256: string;
+    bucket: string;
+    objectKey: string;
+}): Promise<FileAsset>;

package/dist/memory-governance.d.ts

@@ -1,5 +1,5 @@
-import type { Database } from "./database";
-import { type MemoryOperationPlanInput, type MemoryRevertPlanInput } from "./memory-domain";
+import type { Database } from "./database.js";
+import { type MemoryOperationPlanInput, type MemoryRevertPlanInput } from "./memory-domain.js";
 export declare class MemoryGovernanceAuthorityError extends Error {
     readonly name = "MemoryGovernanceAuthorityError";
 }

package/dist/memory-slack-delivery.d.ts

@@ -0,0 +1,101 @@
+import { type MemorySlackPublication, type MemorySlackPublicationConfiguration, type MemorySlackPublicationState } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+import * as schema from "./schema.js";
+export type MemorySlackPublicationActor = {
+    kind: "human" | "agent" | "service";
+    subjectId: string;
+    initiatingHumanSubjectId?: string | null;
+    sessionId?: string | null;
+    turnId?: string | null;
+    attemptId?: string | null;
+};
+export type WorkspaceMemorySlackPublicationSnapshot = {
+    accountId: string;
+    workspaceId: string;
+    id: string;
+    version: number;
+    status: string;
+    kind: string;
+    scopeType: string;
+    namespace: string;
+    labels: string[];
+    validFrom: string;
+    validUntil: string | null;
+    supersedesId: string | null;
+    supersededById: string | null;
+};
+export declare function getWorkspaceMemorySlackPublicationSnapshot(db: Database, workspaceId: string, memoryId: string): Promise<WorkspaceMemorySlackPublicationSnapshot | null>;
+export type MemorySlackPublicationConfigurationInput = {
+    accountId: string;
+    workspaceId: string;
+    expectedRevision: number;
+    enabled: boolean;
+    connectionId: string | null;
+    slackTeamId: string | null;
+    slackChannelId: string | null;
+    slackChannelName: string | null;
+    autoImportances: Array<"major" | "normal" | "minor">;
+    reviewImportances: Array<"major" | "normal" | "minor">;
+    subjectId: string;
+};
+export declare class MemorySlackPublicationRevisionConflictError extends Error {
+    readonly currentRevision: number;
+    constructor(currentRevision: number);
+}
+export declare function listMemorySlackPublicationConfigurations(db: Database, workspaceId: string, limit?: number): Promise<MemorySlackPublicationConfiguration[]>;
+export declare function getCurrentMemorySlackPublicationConfiguration(db: Database, workspaceId: string): Promise<MemorySlackPublicationConfiguration | null>;
+export declare function createMemorySlackPublicationConfiguration(db: Database, input: MemorySlackPublicationConfigurationInput): Promise<MemorySlackPublicationConfiguration>;
+export type EnqueueMemorySlackPublicationInput = {
+    accountId: string;
+    workspaceId: string;
+    sourceType: "workspace_memory" | "durable_learning";
+    sourceId: string;
+    sourceVersion?: string | null;
+    sourceIdempotencyKey: string;
+    projection: Record<string, unknown>;
+    importance: "major" | "normal" | "minor";
+    deliveryMode: "auto" | "review";
+    actor: MemorySlackPublicationActor;
+};
+export type EnqueueMemorySlackPublicationResult = {
+    kind: "not_configured";
+} | {
+    kind: "disabled";
+    configuration: MemorySlackPublicationConfiguration;
+} | {
+    kind: "enqueued" | "replayed";
+    publication: MemorySlackPublication;
+};
+export declare function enqueueMemorySlackPublication(db: Database, input: EnqueueMemorySlackPublicationInput): Promise<EnqueueMemorySlackPublicationResult>;
+export type ClaimedMemorySlackPublication = typeof schema.memorySlackPublications.$inferSelect;
+export declare function claimMemorySlackPublication(db: Database, claimHolderId: string, claimLeaseMs: number): Promise<ClaimedMemorySlackPublication | null>;
+export declare function currentMemorySlackConfigurationMatches(db: Database, publication: ClaimedMemorySlackPublication): Promise<boolean>;
+export declare function completeMemorySlackPublication(db: Database, input: {
+    publication: ClaimedMemorySlackPublication;
+    claimHolderId: string;
+    slackChannelId: string;
+    slackMessageTimestamp: string;
+}): Promise<boolean>;
+export declare function deferMemorySlackPublication(db: Database, input: {
+    publication: ClaimedMemorySlackPublication;
+    claimHolderId: string;
+    retryAt: Date;
+    errorCode: string;
+}): Promise<boolean>;
+export declare function failMemorySlackPublication(db: Database, input: {
+    publication: ClaimedMemorySlackPublication;
+    claimHolderId: string;
+    errorCode: string;
+    cancelled?: boolean;
+}): Promise<boolean>;
+export declare function actOnMemorySlackPublication(db: Database, input: {
+    workspaceId: string;
+    publicationId: string;
+    expectedState: MemorySlackPublicationState;
+    action: "approve" | "reject" | "retry";
+    subjectId: string;
+}): Promise<MemorySlackPublication | null>;
+export declare function listMemorySlackPublications(db: Database, workspaceId: string, options?: {
+    limit?: number;
+    states?: MemorySlackPublicationState[];
+}): Promise<MemorySlackPublication[]>;

package/dist/new-session-drafts.d.ts

@@ -1,6 +1,6 @@
 import type { NewSessionDraftOptions, LatencyMode, ReasoningEffort, ResourceRef, ToolRef } from "@opengeni/contracts";
-import type { Database } from "./database";
-import * as schema from "./schema";
+import type { Database } from "./database.js";
+import * as schema from "./schema.js";
 export type NewSessionDraftRow = typeof schema.newSessionDrafts.$inferSelect;
 export declare class NewSessionDraftConflictError extends Error {
     readonly currentRevision: number;

package/dist/pack-components.d.ts

@@ -0,0 +1,76 @@
+import { type CapabilityPackComponentReference, type PackComponentResolution } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+type PackComponentKind = PackComponentResolution["kind"];
+export type PackInlineSkillRequirement = {
+    key: string;
+    capabilityId: string;
+    name: string;
+    contentSha256: string;
+};
+export type StoredPackInstallationComponent = {
+    id: string;
+    packInstallationId: string;
+    key: string;
+    kind: PackComponentKind;
+    capabilityId: string;
+    resolvedId: string;
+    digest: string;
+    metadata: Record<string, unknown>;
+};
+export declare class PackComponentResolutionError extends Error {
+    readonly componentKey: string;
+    readonly status: "missing" | "mismatch";
+    readonly name = "PackComponentResolutionError";
+    constructor(componentKey: string, status: "missing" | "mismatch");
+}
+export declare function resolvePackComponentReferences(db: Database, workspaceId: string, references: readonly CapabilityPackComponentReference[]): Promise<PackComponentResolution[]>;
+/**
+ * Resolve inline Pack Skills against effective owners by case-insensitive
+ * runtime name. Exact content is shareable; different content under the same
+ * active name is a conflict. The current Pack owner may be excluded so an
+ * update can replace its own previous inline Skill safely.
+ */
+export declare function resolvePackInlineSkillReferences(db: Database, workspaceId: string, requirements: readonly PackInlineSkillRequirement[], excludePackInstallationId?: string): Promise<PackComponentResolution[]>;
+export declare function adoptPackComponentReferences(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    packInstallationId: string;
+    references: readonly CapabilityPackComponentReference[];
+}): Promise<{
+    components: StoredPackInstallationComponent[];
+    retainedFacetInstallationIds: string[];
+    retainedBindingIds: string[];
+}>;
+export declare function listPackInstallationComponents(db: Database, workspaceId: string, packInstallationId: string): Promise<StoredPackInstallationComponent[]>;
+export declare function recordPackInlineSkillComponent(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    packInstallationId: string;
+    componentKey: string;
+    capabilityId: string;
+    facetInstallationId: string;
+    contentSha256: string;
+    name: string;
+}): Promise<StoredPackInstallationComponent>;
+export declare function finalizePackComponentOwnership(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    packInstallationId: string;
+    retainedComponentKeys: string[];
+    retainedFacetInstallationIds: string[];
+    retainedBindingIds: string[];
+}): Promise<void>;
+export declare function previewPackComponentRelease(db: Database, workspaceId: string, packInstallationId: string): Promise<Array<{
+    key: string;
+    kind: PackComponentKind;
+    capabilityId: string;
+    retainedByOtherOwners: boolean;
+}>>;
+export declare function releasePackComponents(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    packInstallationId: string;
+}): Promise<{
+    retainedComponents: string[];
+}>;
+export {};

package/dist/pack-installations.d.ts

@@ -0,0 +1,86 @@
+import { type CapabilityPack, type PackInstallation } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+export declare class PackOperationIdempotencyError extends Error {
+    readonly name = "PackOperationIdempotencyError";
+}
+export declare class PackOperationInProgressError extends Error {
+    readonly name = "PackOperationInProgressError";
+}
+export declare class PackOperationClaimLostError extends Error {
+    readonly name = "PackOperationClaimLostError";
+}
+export declare class PackManifestChangedError extends Error {
+    readonly name = "PackManifestChangedError";
+}
+export declare class PackInstallationVersionConflictError extends Error {
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    readonly name = "PackInstallationVersionConflictError";
+    constructor(expectedVersion: number, actualVersion: number);
+}
+export declare class PackInstallationVersionRequiredError extends Error {
+    readonly name = "PackInstallationVersionRequiredError";
+}
+export type PreparedPackInstallation = {
+    installation: PackInstallation;
+    operationId: string;
+    operationVersion: number;
+    replayResult: Record<string, unknown> | null;
+};
+export declare function preparePackInstallationOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    pack: CapabilityPack;
+    manifestDigest: string;
+    selectedRigId: string | null;
+    metadata: Record<string, unknown>;
+    idempotencyKey: string;
+    requestDigest: string;
+    registeredManifestDigest?: string;
+    expectedInstallationVersion?: number;
+}): Promise<PreparedPackInstallation>;
+export declare function finalizePackInstallationOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    operationVersion: number;
+    packInstallationId: string;
+    packId: string;
+    result: Record<string, unknown>;
+}): Promise<PackInstallation>;
+export declare function deferPackInstallationOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    operationVersion: number;
+    packInstallationId: string;
+    phase: string;
+    errorCode: string;
+}): Promise<void>;
+export declare function touchPackInstallationOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    operationVersion: number;
+}): Promise<void>;
+export declare function preparePackUninstallOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    packId: string;
+    expectedInstallationVersion: number;
+    idempotencyKey: string;
+    requestDigest: string;
+}): Promise<PreparedPackInstallation | {
+    replayResult: Record<string, unknown>;
+}>;
+export declare function finalizePackUninstallOperation(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    operationVersion: number;
+    packInstallationId: string;
+    packId: string;
+    result: Record<string, unknown>;
+}): Promise<void>;

package/dist/persistence-errors.d.ts

@@ -33,13 +33,13 @@ export declare function isDatabasePersistenceFailure(error: unknown): boolean;
 export declare function safeDatabaseErrorFacts(error: unknown): SafeDatabaseErrorFacts;
 /**
  * Typed persistence classification that retains the exact original failure as
- * `cause`. Classification metadata supplements the cause; it never replaces or
- * rewrites source error content.
+ * `cause` for internal diagnostics. The ordinary Error message is deliberately
+ * stable and source-free so a generic presentation path can never disclose SQL,
+ * parameters, or driver detail by rendering `.message`.
  */
 export declare class SessionEventPersistenceError extends Error {
     readonly details: PersistenceFailureDetails;
     readonly name = "SessionEventPersistenceError";
-    readonly cause: unknown;
     constructor(details: PersistenceFailureDetails, cause?: unknown);
     get code(): DatabaseFailureCode;
 }