@dbsp/adapter-pgsql 5.0.0 → 6.0.0

package/dist/internal.d.ts

@@ -1,8 +1,9 @@
-import { q as PgLedgerTarget, T as TransitionJournalQueryable, av as PgOrderedLedgerLocks, aw as PgLedgerShapeAllowance, ax as PgLedgerPhysicalShapeOutcome, a5 as readPgLedgerScopeCurrency } from './outcome-protocol-CACJDzli.js';
-export { ay as PgCommitAcknowledgementAmbiguousError, az as appendPgLedgerClaim, aA as appendPgLedgerClaimGroup, aB as appendPgLedgerProgress, aC as appendPgLedgerRelease, aD as appendPgLedgerResolution, aE as appendPgLedgerResolutionGroup, aF as appendPgOutcomeResolution, aG as classifyPgLedgerPhysicalShape, aH as createPgLedgerShapeAllowance, aI as executePgDestructiveOutcome, aJ as lockPgJournalRun, aK as openPgOutcomeClaim, aL as openPgOutcomeClaimGroup, aM as readPgLedgerReservationsForPair, aN as recoverPgAdmittedReaddressPair, aO as recoverPgOutcomeClaim, aP as resolvePgDestructiveOutcome, aQ as resolvePgOutcomeClaimGroup } from './outcome-protocol-CACJDzli.js';
-import '@dbsp/core';
+import { ad as PgLedgerTarget, T as TransitionJournalQueryable, bX as PgOrderedLedgerLocks, bY as PgLedgerShapeAllowance, bZ as PgLedgerPhysicalShapeOutcome, bx as readPgLedgerScopeCurrency, c as PgPhysicalModel, P as PgLockedRun, a as PgOutcomeCheckpointObserver } from './outcome-protocol-Dw5DYhnA.js';
+export { b_ as ComparePgsqlDatabaseSchemaOptions, b$ as ComparePgsqlDeclaredAdoptionSchemaInput, c0 as CompareSchemataOptions, c1 as ConvergePgBaseOptions, c2 as ConvergePgCheckOptions, b as ConvergePgOptions, c3 as GenerateDDLOptions, c4 as MigrationSQLOptions, a1 as PgApplicationStepTx, c5 as PgCommitAcknowledgementAmbiguousError, a3 as PgConvergeApplicationStep, a4 as PgConvergeAssertStep, e as PgConvergeCheckResult, a5 as PgConvergeInitializationFailure, a6 as PgConvergeOnceStep, a7 as PgConvergePlannedStep, a9 as PgConvergeRefusalChange, aa as PgConvergeRefusalError, d as PgConvergeResult, c6 as PgsqlAdoptionComparisonExecutor, c7 as appendPgLedgerClaim, c8 as appendPgLedgerClaimGroup, c9 as appendPgLedgerProgress, ca as appendPgLedgerRelease, cb as appendPgLedgerResolution, cc as appendPgLedgerResolutionGroup, cd as appendPgOutcomeResolution, ce as classifyPgLedgerPhysicalShape, cf as collectReferencedKeyRemovalConflicts, cg as comparePgsqlDatabaseSchema, ch as comparePgsqlDeclaredAdoptionSchema, ci as compareSchemata, cj as convergePg, ck as createPgLedgerShapeAllowance, cl as createPgsqlDeclaredAdoptionStep, cm as createPgsqlDeclaredSequenceAdoptionStep, cn as executePgDestructiveOutcome, co as generateDDL, cp as generateDownSQL, cq as generateMigrationSQL, cr as lockPgJournalRun, cs as modelForDeclaredAdoption, ct as openPgOutcomeClaim, cu as openPgOutcomeClaimGroup, cv as pgsqlDeclaredAdoptionDeclaration, cw as pgsqlDeclaredSequenceAdoptionDeclaration, cx as readPgLedgerReservationsForPair, cy as recoverPgAdmittedReaddressPair, cz as recoverPgOutcomeClaim, cA as resolvePgDestructiveOutcome, cB as resolvePgOutcomeClaimGroup } from './outcome-protocol-Dw5DYhnA.js';
+import { InProcessProvenPlan, ValidatedManagedStepManifest } from '@dbsp/core';
+import { TransitionRunMetadata, ProvenPlanShape, TransitionRunJournal, TransitionRunAuthorization, TransitionSessionClient, ModelIR, CompareOutcome, PlanAssessment, ObservationContext, ApplyResult, ApplyPolicy, ScopedApprovalSet, NormalizedManagedStep } from '@dbsp/types';
+import { Pool, PoolClient } from 'pg';
 import '@dbsp/core/internal';
-import '@dbsp/types';
 
 declare const postLockAdmissionEvidenceBrand: unique symbol;
 /**
@@ -31,4 +32,142 @@ type PostLockAdmissionEvidenceSeams = {
 declare function createPostLockAdmissionEvidence(executor: TransitionJournalQueryable, locks: PgOrderedLedgerLocks, seams?: PostLockAdmissionEvidenceSeams, allowance?: PgLedgerShapeAllowance): Promise<PostLockAdmissionEvidence>;
 declare function isPostLockAdmissionEvidence(value: unknown): value is PostLockAdmissionEvidence;
 
-export { PgLedgerPhysicalShapeOutcome, PgLedgerShapeAllowance, type PostLockAdmissionEvidence, createPostLockAdmissionEvidence, isPostLockAdmissionEvidence };
+/** Reads the live schema from a short-lived adapter-owned PostgreSQL session. */
+type PgLiveSchemaReader = (client: TransitionSessionClient, schema: string | undefined) => Promise<ModelIR>;
+interface PlanPgTransitionRunOptions {
+    /** False proves and binds a durable plan but leaves no journal record. */
+    readonly persist?: boolean;
+    /** Lets a caller prepare an inspection view before durable persistence. */
+    readonly beforePersist?: (plan: InProcessProvenPlan, proofContext: ObservationContext) => void | Promise<void>;
+}
+type PgTransitionPlanResult = {
+    readonly kind: 'proven';
+    readonly compare: CompareOutcome;
+    readonly assessment: PlanAssessment;
+    readonly plan: InProcessProvenPlan;
+    readonly run: TransitionRunMetadata;
+    readonly proofContext: ObservationContext;
+} | {
+    readonly kind: 'no-drift' | 'blocked' | 'inapplicable';
+    readonly compare: CompareOutcome;
+    readonly assessment: PlanAssessment;
+};
+/** The run id is available even when PostgreSQL cannot confirm persistence. */
+declare class PgTransitionRunPersistenceIndeterminateError extends Error {
+    readonly run: TransitionRunMetadata;
+    readonly compare: CompareOutcome;
+    readonly assessment: PlanAssessment;
+    readonly persistenceError: unknown;
+    constructor(run: TransitionRunMetadata, compare: CompareOutcome, assessment: PlanAssessment, persistenceError: unknown);
+}
+/**
+ * Proves, binds, and optionally persists one PostgreSQL transition run.
+ * The reader sees only an adapter-owned introspection lease; all journal,
+ * evidence, and contract sessions are opened and released here.
+ */
+declare function planPgTransitionRun(physical: PgPhysicalModel, readLiveSchema: PgLiveSchemaReader, pool: Pool, options?: PlanPgTransitionRunOptions): Promise<PgTransitionPlanResult>;
+type PgTransitionRunApplyResult = {
+    readonly kind: 'busy';
+} | {
+    readonly kind: 'settled';
+    readonly result: ApplyResult;
+};
+interface ApplyPgTransitionRunOptions {
+    /**
+     * Chooses a durable authorization record from a freshly read journal. Before
+     * core may execute, the adapter holds the run-row lock while it commits that
+     * exact record to this run's authorization stream, unless the same record was
+     * already present. The fresh read, choice, and commit share one transaction.
+     */
+    readonly authorize: (input: {
+        readonly run: TransitionRunMetadata;
+        readonly plan: ProvenPlanShape;
+        readonly current: TransitionRunJournal;
+    }) => Promise<TransitionRunAuthorization>;
+}
+/** Applies one already-persisted, non-generator PostgreSQL transition run. */
+declare function applyPgTransitionRun(pool: Pool, runId: string, policy: ApplyPolicy, expectedPlanDigest: string, options: ApplyPgTransitionRunOptions): Promise<PgTransitionRunApplyResult>;
+
+type GeneratorExecutionExecutor = Pool | Pick<PoolClient, 'query' | 'release'>;
+type GeneratorExecutionResult = {
+    readonly outcome: 'completed';
+} | {
+    readonly outcome: 'partially-applied';
+    readonly detail: string;
+    readonly completedStepKeys: readonly string[];
+    readonly notStartedStepKeys: readonly string[];
+} | {
+    readonly outcome: 'selection-incomplete';
+    readonly detail: string;
+} | {
+    readonly outcome: 'adoption-refused';
+    readonly detail: string;
+} | {
+    readonly outcome: 'readdress-unsupported';
+    readonly detail: string;
+} | {
+    readonly outcome: 'readdress-refused';
+    readonly detail: string;
+} | {
+    readonly outcome: 'destructive-authority-refused';
+    readonly detail: string;
+    /** The exact live authority that remained withheld at admission. */
+    readonly refusal?: {
+        readonly withheldAuthority: string;
+    };
+} | {
+    readonly outcome: 'prior-step-events-refusal';
+    readonly detail: string;
+} | {
+    readonly outcome: 'recovery-required';
+    readonly claimId: string;
+    readonly detail: string;
+} | {
+    readonly outcome: 'transport-ambiguous';
+    readonly detail: string;
+} | {
+    readonly outcome: 'execution-failed';
+    readonly detail: string;
+};
+/**
+ * Executes the in-memory, just-presented generator material.  It never reads
+ * a generator run back by id: that persisted row remains review-only.
+ */
+declare function executeGeneratorPlan(input: {
+    /**
+     * A pg pool or checked-out PoolClient. A connected standalone pg.Client is
+     * deliberately unsupported: although session-pinned, it has no release(),
+     * and the pool/client distinction must not try to connect it again.
+     */
+    readonly pool: GeneratorExecutionExecutor;
+    /** Bound by apply after validating the persisted durable manifest. */
+    readonly manifest?: ValidatedManagedStepManifest;
+    /** @deprecated Compatibility shim for direct fixtures; it is validated before use. */
+    readonly plan?: {
+        readonly steps: readonly unknown[];
+    };
+    readonly planDigest: string;
+    readonly schema: string;
+    /** Preserve scopes and trust roots until admission; never reduce to classes. */
+    readonly approval?: ScopedApprovalSet;
+    /** Durable witness minted while apply holds this run's journal lock. */
+    readonly run: PgLockedRun;
+    /** Appends the run-to-attempt mapping before any ledger claim may be opened. */
+    readonly recordAttempt: (executionId: string) => Promise<void>;
+    /** Test-only admitted-path observation; absent from every CLI invocation. */
+    readonly observer?: PgOutcomeCheckpointObserver;
+    /** Contiguous fresh-object steps that must commit as one PostgreSQL transaction. */
+    readonly atomicCreationGroup?: readonly string[];
+    /**
+     * Converge supplies its lock-holding canonical comparison here.  The
+     * callback receives both the preflight executor and the executor inside the
+     * admitted outcome transaction, so adoption never escapes that session.
+     */
+    readonly verifyDeclaredAdoptionShape?: (executor: TransitionJournalQueryable, step: NormalizedManagedStep) => Promise<boolean>;
+    /** @deprecated Compatibility shim for old direct fixtures. */
+    readonly accepts?: readonly string[];
+    readonly replaces?: readonly string[];
+    readonly runId: string;
+}): Promise<GeneratorExecutionResult>;
+
+export { type ApplyPgTransitionRunOptions, type GeneratorExecutionResult, PgLedgerPhysicalShapeOutcome, PgLedgerShapeAllowance, type PgLiveSchemaReader, type PgTransitionPlanResult, type PgTransitionRunApplyResult, PgTransitionRunPersistenceIndeterminateError, type PlanPgTransitionRunOptions, type PostLockAdmissionEvidence, applyPgTransitionRun, createPostLockAdmissionEvidence, executeGeneratorPlan, isPostLockAdmissionEvidence, planPgTransitionRun };

package/dist/internal.js

@@ -1,5 +1,7 @@
 import {
   PgCommitAcknowledgementAmbiguousError,
+  PgConvergeRefusalError,
+  PgTransitionRunPersistenceIndeterminateError,
   appendPgLedgerClaim,
   appendPgLedgerClaimGroup,
   appendPgLedgerProgress,
@@ -7,22 +9,40 @@ import {
   appendPgLedgerResolution,
   appendPgLedgerResolutionGroup,
   appendPgOutcomeResolution,
+  applyPgTransitionRun,
   classifyPgLedgerPhysicalShape,
+  collectReferencedKeyRemovalConflicts,
+  comparePgsqlDatabaseSchema2 as comparePgsqlDatabaseSchema,
+  comparePgsqlDeclaredAdoptionSchema,
+  compareSchemata,
+  convergePg,
   createPgLedgerShapeAllowance,
+  createPgsqlDeclaredAdoptionStep,
+  createPgsqlDeclaredSequenceAdoptionStep,
   createPostLockAdmissionEvidence,
+  executeGeneratorPlan,
   executePgDestructiveOutcome,
+  generateDDL,
+  generateDownSQL,
+  generateMigrationSQL,
   isPostLockAdmissionEvidence,
   lockPgJournalRun,
+  modelForDeclaredAdoption,
   openPgOutcomeClaim,
   openPgOutcomeClaimGroup,
+  pgsqlDeclaredAdoptionDeclaration,
+  pgsqlDeclaredSequenceAdoptionDeclaration,
+  planPgTransitionRun,
   readPgLedgerReservationsForPair,
   recoverPgAdmittedReaddressPair,
   recoverPgOutcomeClaim,
   resolvePgDestructiveOutcome,
   resolvePgOutcomeClaimGroup
-} from "./chunk-KZ3NLIZ5.js";
+} from "./chunk-NXGMFZ4E.js";
 export {
   PgCommitAcknowledgementAmbiguousError,
+  PgConvergeRefusalError,
+  PgTransitionRunPersistenceIndeterminateError,
   appendPgLedgerClaim,
   appendPgLedgerClaimGroup,
   appendPgLedgerProgress,
@@ -30,14 +50,30 @@ export {
   appendPgLedgerResolution,
   appendPgLedgerResolutionGroup,
   appendPgOutcomeResolution,
+  applyPgTransitionRun,
   classifyPgLedgerPhysicalShape,
+  collectReferencedKeyRemovalConflicts,
+  comparePgsqlDatabaseSchema,
+  comparePgsqlDeclaredAdoptionSchema,
+  compareSchemata,
+  convergePg,
   createPgLedgerShapeAllowance,
+  createPgsqlDeclaredAdoptionStep,
+  createPgsqlDeclaredSequenceAdoptionStep,
   createPostLockAdmissionEvidence,
+  executeGeneratorPlan,
   executePgDestructiveOutcome,
+  generateDDL,
+  generateDownSQL,
+  generateMigrationSQL,
   isPostLockAdmissionEvidence,
   lockPgJournalRun,
+  modelForDeclaredAdoption,
   openPgOutcomeClaim,
   openPgOutcomeClaimGroup,
+  pgsqlDeclaredAdoptionDeclaration,
+  pgsqlDeclaredSequenceAdoptionDeclaration,
+  planPgTransitionRun,
   readPgLedgerReservationsForPair,
   recoverPgAdmittedReaddressPair,
   recoverPgOutcomeClaim,