@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/reporting/ledger/postgres.d.mts

@@ -1,4 +1,5 @@
-import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1 } from './types.mjs';
+import { REPORTING_LEDGER_AUTHORITY } from './types.mjs';
+import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } from './types.mjs';
 import type { ReportingConsumerMismatchEscalationV1 } from './types.mjs';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
@@ -14,6 +15,30 @@ export interface ReportingPgPool {
     connect(): Promise<ReportingPgClient>;
 }
 export declare const REPORTING_LEDGER_MIGRATION: string;
+/** Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}. */
+export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
+/**
+ * Cutover migration that fences pre-SDK-14 writers out of the transition log.
+ *
+ * A pre-SDK-14 writer appends transitions with no `finality`. Each one becomes
+ * the latest row, gets its baseline committed as `none`, and can therefore
+ * produce another redundant finality-only transition — so "at most one per
+ * obligation at upgrade" only holds once no such writer remains. Wall clocks
+ * and deploy ordering cannot establish that; a database constraint can.
+ *
+ * The constraint is added `NOT VALID`, which enforces it for every INSERT and
+ * UPDATE while leaving historical rows untouched and unvalidated. Existing
+ * finality-less rows keep working — the baseline resolver and
+ * `markTransitionNotified` both write `finality` as part of their update, so the
+ * new row version satisfies the check.
+ *
+ * Run it as part of the cutover, **after** legacy writers are drained. A legacy
+ * writer that is still running will fail closed on append rather than silently
+ * multiply finality-only events, which is the intended trade: loud rejection
+ * beats a quietly broken invariant. Idempotent and re-runnable; it takes no lock
+ * once installed.
+ */
+export declare const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION: string;
 export interface PostgresReportingLedgerStoreOptions {
     /** Assert that the supplied PostgreSQL database/schema is isolated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
@@ -26,6 +51,41 @@ export interface PostgresReportingLedgerStoreOptions {
      * the unfiltered read shows.
      */
     consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    /** Explicitly opt this Core store into projecting the additive #2944 tables. */
+    managedDelivery?: boolean;
+    /**
+     * Supplies the principals that owe a receipt for one obligation.
+     *
+     * Nothing durable in the managed tables enumerates them — destination
+     * authorizations and bindings are keyed by
+     * `(account_id, destination_ref, generation)` with no consumer dimension — so
+     * without this the store can only report who has already submitted, and must
+     * stay conservative: a `consumer_receipt` obligation is then never reported
+     * reconciled on a lifecycle transition. Wire this to whatever your
+     * authorization layer knows and return `complete: true` to get accurate
+     * reconciled transitions and webhooks.
+     *
+     * `complete: true` is taken at your word, and this is the only place in the
+     * subsystem where an adopter assertion can mark billing reconciled: a roster
+     * omitting a principal that owes a receipt makes that duty vanish from the
+     * fold, so the obligation can be persisted and notified reconciled while
+     * that principal never accepted. It is invoked outside the store's
+     * transaction and under a deadline, so it may do I/O — but it must not be
+     * slower than that deadline.
+     */
+    obligatedConsumers?: (input: {
+        reporting_obligation_id: string;
+        account_id: string;
+    }) => Promise<{
+        ids: readonly string[];
+        complete: boolean;
+        version?: string;
+    }>;
+    /**
+     * Durable notification/activity port invoked inside the authoritative
+     * lifecycle transaction. Its tables must be migrated before transitions run.
+     */
+    notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
 }
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
@@ -48,6 +108,11 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      * contradict the summary.
      */
     readonly consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    readonly [REPORTING_LEDGER_AUTHORITY]: ReportingLedgerAuthorityV1;
+    private readonly managedDelivery;
+    private readonly obligatedConsumers;
+    readonly transactionalNotificationActivity: boolean;
+    private readonly notificationActivityPort?;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
     putConfiguration(configuration: ReportingLedgerConfigurationV1): Promise<{
         inserted: boolean;
@@ -95,22 +160,35 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     putIssue(issue: ReportingLedgerIssueV1): Promise<void>;
     resolveIssue(issueId: string, resolvedAt: string): Promise<void>;
     listIssues(obligationId: string): Promise<ReportingLedgerIssueV1[]>;
+    /**
+     * Resolves — and for pre-SDK-14 rows persists — the observed finality baseline
+     * of the obligation's latest transition, so the lifecycle decision and this
+     * store's compare-and-set read one committed value.
+     */
+    resolveTransitionFinalityBaseline(obligationId: string): Promise<ReportingObservedFinalityV1>;
     appendTransition(transition: ReportingLedgerStatusTransitionV1): Promise<{
         inserted: boolean;
     }>;
+    private appendTransitionWithinLock;
     applyLifecycleProjection(input: {
         reporting_obligation_id: string;
         expectedRevisionIds: string[];
         expectedPreviousHealth: import('./types.mjs').ReportingHealthV1;
+        expectedPreviousFinality?: ReportingObservedFinalityV1;
         expectedObligationState: ReportingLedgerObligationV1['state'];
         expectedAttemptCount: number;
         projectedIssues: ReportingLedgerIssueV1[];
         ledgerAsOf: string;
         transition?: ReportingLedgerStatusTransitionV1;
+        expectedManagedStateVersion?: string;
+        processedManagedStateVersion?: string;
+        processedObligatedConsumerRosterVersion?: string;
+        expectedObligatedConsumerRosterVersion?: string;
     }): Promise<{
         applied: boolean;
         transitionInserted: boolean;
     }>;
+    private applyLifecycleProjectionWithinLock;
     markTransitionNotified(transitionId: string, notifiedAt: string): Promise<void>;
     listTransitions(obligationId: string): Promise<ReportingLedgerStatusTransitionV1[]>;
     listPendingTransitions(input?: {
@@ -126,6 +204,88 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private listSnapshotRevisions;
     private listSnapshotIssues;
     private listSnapshotAdjustments;
+    /**
+     * Managed Delivery projection inputs for one obligation, grouped per consumer.
+     *
+     * The lifecycle reconciler folds these through the same
+     * `projectManagedDelivery` the read path uses, so a persisted transition and
+     * its webhook report the health a read of the same obligation would return.
+     * Returns `null` when Managed Delivery is not installed or the obligation's
+     * configuration has no binding, which keeps a Core-only ledger unchanged.
+     */
+    getManagedLifecycleProjection(input: {
+        reporting_obligation_id: string;
+        ledgerAsOf?: string;
+    }): Promise<ReportingManagedLifecycleProjectionV1 | null>;
+    /**
+     * Digest over every managed row that can change this obligation's projected
+     * health: materialization status, receipt existence and current-leaf flag,
+     * adjustments, and the destination authorization's revocation/cleanup state.
+     *
+     * `is_current` is included because superseding a receipt flips it with no
+     * timestamp of its own, and the authorization's `cleanup_completed_at` is
+     * included because `completeRevocation` does not touch `changed_at`.
+     */
+    private readManagedStateVersion;
+    /**
+     * Current external roster version, read outside any transaction so the
+     * reconciler can re-check it immediately before an apply.
+     */
+    /**
+     * Publishes the roster version currently observed for an obligation.
+     *
+     * The roster is external, so nothing in this database changes when it does.
+     * Recording what a reader saw is what lets the due query notice drift from
+     * the version last reconciled. Never lowers a watermark; it only reports.
+     */
+    recordObligatedConsumerRosterVersion(input: {
+        reporting_obligation_id: string;
+        version: string;
+    }): Promise<void>;
+    /**
+     * Re-reads the external roster for managed obligations and publishes what
+     * it saw, so a change made while nothing was scheduled can re-arm.
+     *
+     * Ordered by least-recently-refreshed and bounded, so a large account is
+     * swept over successive passes rather than in one burst of callbacks.
+     */
+    refreshObligatedConsumerRosterVersions(input: {
+        account_id?: string;
+        limit: number;
+    }): Promise<number>;
+    /**
+     * Records a failed reconcile so the obligation backs off instead of
+     * re-occupying the head of every sweep, without ever hiding it: the
+     * watermark is untouched, so it stays unresolved work.
+     */
+    recordLifecycleFailure(input: {
+        reporting_obligation_id: string;
+    }): Promise<void>;
+    /** Authoritative instant from the database clock, at microsecond precision. */
+    readLedgerInstant(): Promise<string>;
+    readObligatedConsumerRosterVersion(input: {
+        reporting_obligation_id: string;
+    }): Promise<string | undefined>;
+    /** Principals that have engaged with this obligation, as the projection sees them. */
+    private observedConsumerIds;
+    private managedDueTablesReadyCache;
+    /** Whether the managed schema exists, resolved once per store instance. */
+    private managedDueTablesReady;
+    /**
+     * Terminal receipt subjects whose bodies have been pruned.
+     *
+     * The projection decides reconciliation from the receipt rows it can see,
+     * so once an accepted leaf ages out the subject looks unreconciled again
+     * and a settled billing period reopens. The tombstone is the only remaining
+     * proof, so the projection has to consult it.
+     */
+    private listTombstonedAcceptedSubjects;
+    private managedTablesInstalled;
+    private listManagedChangedObligationIds;
+    private listSnapshotManagedBindings;
+    private listSnapshotMaterializations;
+    private listSnapshotMaterializationProjection;
+    private listSnapshotReceipts;
     private one;
     private putImmutable;
     private accountLockForObligation;

package/dist/lib/reporting/ledger/postgres.d.ts

@@ -1,4 +1,5 @@
-import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1 } from './types';
+import { REPORTING_LEDGER_AUTHORITY } from './types';
+import type { ReportingLedgerConfigurationV1, ReportingLedgerAdjustmentV1, ReportingLedgerConsumerStatusV1, ReportingLedgerIssueV1, ReportingLedgerLeaseV1, ReportingLedgerObligationV1, ReportingLedgerPageV1, ReportingLedgerRevisionV1, ReportingLedgerSnapshotQueryV1, ReportingLedgerSnapshotV1, ReportingLedgerStatusTransitionV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1, ReportingLedgerStore, ReportingConsumerStatusBatchInputV1, ReportingConsumerStatusBatchResultV1, ReportingConsumerStatusReplayInputV1, ReportingLedgerRevisionMetadataV1, ReportingManagedLifecycleProjectionV1, ReportingLedgerAuthorityV1 } from './types';
 import type { ReportingConsumerMismatchEscalationV1 } from './types';
 type QueryResultRow = Record<string, unknown>;
 interface ReportingPgResult<Row extends QueryResultRow> {
@@ -14,6 +15,30 @@ export interface ReportingPgPool {
     connect(): Promise<ReportingPgClient>;
 }
 export declare const REPORTING_LEDGER_MIGRATION: string;
+/** Constraint installed by {@link REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION}. */
+export declare const REPORTING_LEDGER_FINALITY_FENCE_CONSTRAINT = "adcp_reporting_transitions_finality_recorded";
+/**
+ * Cutover migration that fences pre-SDK-14 writers out of the transition log.
+ *
+ * A pre-SDK-14 writer appends transitions with no `finality`. Each one becomes
+ * the latest row, gets its baseline committed as `none`, and can therefore
+ * produce another redundant finality-only transition — so "at most one per
+ * obligation at upgrade" only holds once no such writer remains. Wall clocks
+ * and deploy ordering cannot establish that; a database constraint can.
+ *
+ * The constraint is added `NOT VALID`, which enforces it for every INSERT and
+ * UPDATE while leaving historical rows untouched and unvalidated. Existing
+ * finality-less rows keep working — the baseline resolver and
+ * `markTransitionNotified` both write `finality` as part of their update, so the
+ * new row version satisfies the check.
+ *
+ * Run it as part of the cutover, **after** legacy writers are drained. A legacy
+ * writer that is still running will fail closed on append rather than silently
+ * multiply finality-only events, which is the intended trade: loud rejection
+ * beats a quietly broken invariant. Idempotent and re-runnable; it takes no lock
+ * once installed.
+ */
+export declare const REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION: string;
 export interface PostgresReportingLedgerStoreOptions {
     /** Assert that the supplied PostgreSQL database/schema is isolated to this deployment. */
     acknowledgeIsolatedDatabase?: boolean;
@@ -26,6 +51,41 @@ export interface PostgresReportingLedgerStoreOptions {
      * the unfiltered read shows.
      */
     consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    /** Explicitly opt this Core store into projecting the additive #2944 tables. */
+    managedDelivery?: boolean;
+    /**
+     * Supplies the principals that owe a receipt for one obligation.
+     *
+     * Nothing durable in the managed tables enumerates them — destination
+     * authorizations and bindings are keyed by
+     * `(account_id, destination_ref, generation)` with no consumer dimension — so
+     * without this the store can only report who has already submitted, and must
+     * stay conservative: a `consumer_receipt` obligation is then never reported
+     * reconciled on a lifecycle transition. Wire this to whatever your
+     * authorization layer knows and return `complete: true` to get accurate
+     * reconciled transitions and webhooks.
+     *
+     * `complete: true` is taken at your word, and this is the only place in the
+     * subsystem where an adopter assertion can mark billing reconciled: a roster
+     * omitting a principal that owes a receipt makes that duty vanish from the
+     * fold, so the obligation can be persisted and notified reconciled while
+     * that principal never accepted. It is invoked outside the store's
+     * transaction and under a deadline, so it may do I/O — but it must not be
+     * slower than that deadline.
+     */
+    obligatedConsumers?: (input: {
+        reporting_obligation_id: string;
+        account_id: string;
+    }) => Promise<{
+        ids: readonly string[];
+        complete: boolean;
+        version?: string;
+    }>;
+    /**
+     * Durable notification/activity port invoked inside the authoritative
+     * lifecycle transaction. Its tables must be migrated before transitions run.
+     */
+    notificationActivityPort?: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
 }
 export declare class ReportingLedgerLeaseLostError extends Error {
     constructor(message?: string);
@@ -48,6 +108,11 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
      * contradict the summary.
      */
     readonly consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
+    readonly [REPORTING_LEDGER_AUTHORITY]: ReportingLedgerAuthorityV1;
+    private readonly managedDelivery;
+    private readonly obligatedConsumers;
+    readonly transactionalNotificationActivity: boolean;
+    private readonly notificationActivityPort?;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
     putConfiguration(configuration: ReportingLedgerConfigurationV1): Promise<{
         inserted: boolean;
@@ -95,22 +160,35 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     putIssue(issue: ReportingLedgerIssueV1): Promise<void>;
     resolveIssue(issueId: string, resolvedAt: string): Promise<void>;
     listIssues(obligationId: string): Promise<ReportingLedgerIssueV1[]>;
+    /**
+     * Resolves — and for pre-SDK-14 rows persists — the observed finality baseline
+     * of the obligation's latest transition, so the lifecycle decision and this
+     * store's compare-and-set read one committed value.
+     */
+    resolveTransitionFinalityBaseline(obligationId: string): Promise<ReportingObservedFinalityV1>;
     appendTransition(transition: ReportingLedgerStatusTransitionV1): Promise<{
         inserted: boolean;
     }>;
+    private appendTransitionWithinLock;
     applyLifecycleProjection(input: {
         reporting_obligation_id: string;
         expectedRevisionIds: string[];
         expectedPreviousHealth: import('./types').ReportingHealthV1;
+        expectedPreviousFinality?: ReportingObservedFinalityV1;
         expectedObligationState: ReportingLedgerObligationV1['state'];
         expectedAttemptCount: number;
         projectedIssues: ReportingLedgerIssueV1[];
         ledgerAsOf: string;
         transition?: ReportingLedgerStatusTransitionV1;
+        expectedManagedStateVersion?: string;
+        processedManagedStateVersion?: string;
+        processedObligatedConsumerRosterVersion?: string;
+        expectedObligatedConsumerRosterVersion?: string;
     }): Promise<{
         applied: boolean;
         transitionInserted: boolean;
     }>;
+    private applyLifecycleProjectionWithinLock;
     markTransitionNotified(transitionId: string, notifiedAt: string): Promise<void>;
     listTransitions(obligationId: string): Promise<ReportingLedgerStatusTransitionV1[]>;
     listPendingTransitions(input?: {
@@ -126,6 +204,88 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private listSnapshotRevisions;
     private listSnapshotIssues;
     private listSnapshotAdjustments;
+    /**
+     * Managed Delivery projection inputs for one obligation, grouped per consumer.
+     *
+     * The lifecycle reconciler folds these through the same
+     * `projectManagedDelivery` the read path uses, so a persisted transition and
+     * its webhook report the health a read of the same obligation would return.
+     * Returns `null` when Managed Delivery is not installed or the obligation's
+     * configuration has no binding, which keeps a Core-only ledger unchanged.
+     */
+    getManagedLifecycleProjection(input: {
+        reporting_obligation_id: string;
+        ledgerAsOf?: string;
+    }): Promise<ReportingManagedLifecycleProjectionV1 | null>;
+    /**
+     * Digest over every managed row that can change this obligation's projected
+     * health: materialization status, receipt existence and current-leaf flag,
+     * adjustments, and the destination authorization's revocation/cleanup state.
+     *
+     * `is_current` is included because superseding a receipt flips it with no
+     * timestamp of its own, and the authorization's `cleanup_completed_at` is
+     * included because `completeRevocation` does not touch `changed_at`.
+     */
+    private readManagedStateVersion;
+    /**
+     * Current external roster version, read outside any transaction so the
+     * reconciler can re-check it immediately before an apply.
+     */
+    /**
+     * Publishes the roster version currently observed for an obligation.
+     *
+     * The roster is external, so nothing in this database changes when it does.
+     * Recording what a reader saw is what lets the due query notice drift from
+     * the version last reconciled. Never lowers a watermark; it only reports.
+     */
+    recordObligatedConsumerRosterVersion(input: {
+        reporting_obligation_id: string;
+        version: string;
+    }): Promise<void>;
+    /**
+     * Re-reads the external roster for managed obligations and publishes what
+     * it saw, so a change made while nothing was scheduled can re-arm.
+     *
+     * Ordered by least-recently-refreshed and bounded, so a large account is
+     * swept over successive passes rather than in one burst of callbacks.
+     */
+    refreshObligatedConsumerRosterVersions(input: {
+        account_id?: string;
+        limit: number;
+    }): Promise<number>;
+    /**
+     * Records a failed reconcile so the obligation backs off instead of
+     * re-occupying the head of every sweep, without ever hiding it: the
+     * watermark is untouched, so it stays unresolved work.
+     */
+    recordLifecycleFailure(input: {
+        reporting_obligation_id: string;
+    }): Promise<void>;
+    /** Authoritative instant from the database clock, at microsecond precision. */
+    readLedgerInstant(): Promise<string>;
+    readObligatedConsumerRosterVersion(input: {
+        reporting_obligation_id: string;
+    }): Promise<string | undefined>;
+    /** Principals that have engaged with this obligation, as the projection sees them. */
+    private observedConsumerIds;
+    private managedDueTablesReadyCache;
+    /** Whether the managed schema exists, resolved once per store instance. */
+    private managedDueTablesReady;
+    /**
+     * Terminal receipt subjects whose bodies have been pruned.
+     *
+     * The projection decides reconciliation from the receipt rows it can see,
+     * so once an accepted leaf ages out the subject looks unreconciled again
+     * and a settled billing period reopens. The tombstone is the only remaining
+     * proof, so the projection has to consult it.
+     */
+    private listTombstonedAcceptedSubjects;
+    private managedTablesInstalled;
+    private listManagedChangedObligationIds;
+    private listSnapshotManagedBindings;
+    private listSnapshotMaterializations;
+    private listSnapshotMaterializationProjection;
+    private listSnapshotReceipts;
     private one;
     private putImmutable;
     private accountLockForObligation;