@adcp/sdk 15.3.0 → 15.5.0

package/dist/lib/reporting/ledger/row-storage.d.mts

@@ -0,0 +1,224 @@
+import { type ReportingEncodedRowsV1, type ReportingRowChunkManifestV1 } from './row-encoding.mjs';
+import { type ReportingRowObjectProviderV1 } from './row-storage-object.mjs';
+/**
+ * Revision row storage (shared SDK persistence spec,
+ * adcontextprotocol/adcp#7996 §3). Revision headers stay in the ledger
+ * document; rows live as canonical JSONL chunks in a storage binding, and
+ * every read is verified against digests committed in PostgreSQL before rows
+ * are released.
+ */
+export { ReportingRowStoreError, isReportingRowStoreError } from './row-storage-errors.mjs';
+export type { ReportingRowStoreErrorCode } from './row-storage-errors.mjs';
+/** Rows stored as chunk bodies in the ledger's own PostgreSQL schema. */
+export interface ReportingPostgresRowBindingV1 {
+    kind: 'postgres';
+}
+/**
+ * Rows stored as one object per chunk through a registered provider. The
+ * definition lives in host code, which makes it the allowlist: a row set
+ * whose recorded binding identity differs from the configured definition is
+ * never read from or written to.
+ */
+export interface ReportingObjectRowBindingV1 {
+    kind: 'object';
+    /** Name of a provider registered in `ReportingRowStorageOptionsV1.providers`. */
+    provider: string;
+    /** Non-secret provider coordinates, validated by the provider's closed schema. */
+    location: Readonly<Record<string, string>>;
+    /** Owned key prefix. Sweeps and deletes never touch keys outside it. */
+    prefix: string;
+    /** Object key template; see `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`. */
+    keyTemplate?: string;
+    /** Stored encoding; digests always cover uncompressed bytes. Default `gzip`. */
+    compression?: 'none' | 'gzip';
+    /** Host-mapped client reference passed to the provider; never a secret. */
+    credentialRef?: string;
+}
+export type ReportingRowBindingDefinitionV1 = ReportingPostgresRowBindingV1 | ReportingObjectRowBindingV1;
+export interface ReportingRowBindingSelectionInputV1 {
+    account_id: string;
+    reporting_obligation_id: string;
+    row_set_kind: 'revision' | 'adjustment';
+    finality?: 'snapshot' | 'official';
+    row_count: number;
+    canonical_byte_count: number;
+}
+export interface ReportingRowStorageOptionsV1 {
+    /**
+     * Logical binding ID → immutable definition. Defaults to a single
+     * `postgres` binding. Changing a definition requires a new ID; keep retired
+     * definitions configured while revisions still reference them.
+     */
+    bindings?: Readonly<Record<string, ReportingRowBindingDefinitionV1>>;
+    /** Object-storage providers by name. */
+    providers?: Readonly<Record<string, ReportingRowObjectProviderV1>>;
+    /** Picks the binding for each new row set. Defaults to the only binding, or `postgres`. */
+    selectRowBinding?(input: ReportingRowBindingSelectionInputV1): string | Promise<string>;
+    /**
+     * Stable deployment namespace, combined with the schema's installation
+     * identity into each binding's `namespace_key`. Defaults to `default`.
+     */
+    deploymentNamespace?: string;
+    /** Deadline for one row set's uploads. Default 60 seconds. */
+    writeDeadlineMilliseconds?: number;
+    /** Deadline for one object read. Default 30 seconds. */
+    readDeadlineMilliseconds?: number;
+}
+export interface ReportingRowSetPrepareInputV1 {
+    rowSetId: string;
+    rowSetKind: 'revision' | 'adjustment';
+    accountId: string;
+    obligationId: string;
+    rows: readonly Record<string, unknown>[];
+    finality?: 'snapshot' | 'official';
+    /** Reporting period start, used for `{period_date}` in object keys. */
+    periodStart?: string;
+    /** Committed protocol binding the chunks must reproduce. */
+    binding: {
+        sha256: string;
+        byteCount: number;
+        rowCount: number;
+    };
+    /** Required for revisions (`revision_envelope_v1`); omitted for adjustments (`rows_v1`). */
+    controlTotals?: readonly unknown[];
+    /** Overrides `selectRowBinding` (for example, to migrate inline rows into a PostgreSQL binding). */
+    bindingId?: string;
+}
+interface PreparedObjectV1 {
+    readonly key: string;
+    readonly physicalBytes: Buffer;
+    readonly physicalSha256: string;
+    readonly compression: 'none' | 'gzip';
+}
+export interface ReportingPreparedRowSetV1 {
+    readonly input: ReportingRowSetPrepareInputV1;
+    readonly encoded: ReportingEncodedRowsV1;
+    readonly bindingId: string;
+    readonly binding: ReportingRowBindingDefinitionV1;
+    readonly digestProfile: 'revision_envelope_v1' | 'rows_v1';
+    /** Object kind only: one planned object per chunk. */
+    readonly objects?: readonly PreparedObjectV1[];
+}
+/** Where one chunk was stored; recorded in the chunk manifest. */
+export interface ReportingRowChunkLocatorV1 {
+    objectKey: string;
+    nativeVersion: string;
+    compression: 'none' | 'gzip';
+    physicalSha256: string;
+    physicalByteCount: number;
+    /** Whether this upload created the object (as opposed to adopting identical bytes). */
+    created: boolean;
+}
+interface QueryableV1 {
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: Row[];
+        rowCount?: number | null;
+    }>;
+}
+/** A row set whose chunk manifest has been verified against its committed digest. */
+export interface ReportingRowSetHandleV1 {
+    readonly rowSetId: string;
+    readonly rowSetKind: 'revision' | 'adjustment';
+    readonly accountId: string;
+    readonly obligationId: string;
+    readonly digestProfile: 'revision_envelope_v1' | 'rows_v1';
+    readonly contentSha256: string;
+    readonly canonicalByteCount: number;
+    readonly rowCount: number;
+    readonly rowManifestSha256: string;
+    readonly bindingId: string;
+    readonly bindingIdentitySha256: string;
+    readonly kind: 'postgres' | 'object';
+    readonly manifests: readonly ReportingRowChunkManifestV1[];
+    /** Object kind only, by chunk index. */
+    readonly locators: readonly (Omit<ReportingRowChunkLocatorV1, 'created'> | undefined)[];
+}
+/**
+ * Reads and writes revision row sets. PostgreSQL-kind reads are always
+ * available once the row-storage migration is applied; object-kind reads need
+ * the binding and its provider configured. Writes require an explicit opt-in
+ * on the owning store.
+ */
+export declare class ReportingRowStorageV1 {
+    private readonly pool;
+    private readonly options;
+    private readonly bindings;
+    private readonly providers;
+    private readonly deploymentNamespace;
+    private readonly writeDeadline;
+    private readonly readDeadline;
+    private readied?;
+    private installation?;
+    constructor(pool: QueryableV1, options?: ReportingRowStorageOptionsV1);
+    /** Deadline budget a writer must still hold on its lease before uploading. */
+    get writeDeadlineMilliseconds(): number;
+    /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
+    ready(): Promise<void>;
+    /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */
+    prepare(input: ReportingRowSetPrepareInputV1): Promise<ReportingPreparedRowSetV1>;
+    /**
+     * Upload a prepared object-kind row set, create-only. An object already at a
+     * planned key is adopted only when its bytes decode to the exact chunk;
+     * otherwise `CONTENT_CONFLICT`. `onCreated` is awaited for every object this
+     * call created, before the next upload, so the caller can record it in its
+     * write intent.
+     */
+    upload(prepared: ReportingPreparedRowSetV1, intentId: string, onCreated: (object: {
+        objectKey: string;
+        nativeVersion: string;
+    }) => Promise<void>, signal?: AbortSignal): Promise<ReportingRowChunkLocatorV1[]>;
+    /**
+     * Persist a prepared row set inside the caller's ledger transaction:
+     * bodies for the `postgres` kind, or the uploaded locators for the object
+     * kind. Replays of an identical row set are no-ops; a conflicting row set
+     * under the same ID is refused.
+     */
+    writeInTransaction(transaction: QueryableV1, prepared: ReportingPreparedRowSetV1, locators?: readonly ReportingRowChunkLocatorV1[], sharedFromRowSetId?: string): Promise<void>;
+    /**
+     * Load a row set and verify its chunk manifest against the committed digest.
+     * Returns `null` when no row set exists (legacy inline rows) or it belongs
+     * to another account. Throws `ROWS_EXPIRED` / `ROWS_UNAVAILABLE` when the
+     * rows were pruned or lost.
+     */
+    find(rowSetId: string, accountId: string, queryable?: QueryableV1): Promise<ReportingRowSetHandleV1 | null>;
+    /** Verified rows `[offset, offset + limit)` in ordinal order. */
+    readPage(handle: ReportingRowSetHandleV1, offset: number, limit: number, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+    /**
+     * Every row, verified chunk by chunk and against the committed binding.
+     * `controlTotals` are required for revision row sets.
+     */
+    readAll(handle: ReportingRowSetHandleV1, controlTotals?: readonly unknown[], options?: {
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Delete exact object versions through the configured binding's provider.
+     * `absent` counts as success. Only object-kind bindings are accepted.
+     */
+    deleteObjects(bindingId: string, objects: readonly {
+        objectKey: string;
+        nativeVersion: string;
+    }[], signal?: AbortSignal): Promise<void>;
+    /**
+     * A live row set in the same obligation and binding whose rows are
+     * byte-identical (same manifest digest), with its chunk locations. Sharing
+     * never crosses obligations, so it never crosses consumers.
+     */
+    findShareable(queryable: QueryableV1, prepared: ReportingPreparedRowSetV1): Promise<{
+        rowSetId: string;
+        locators: ReportingRowChunkLocatorV1[];
+    } | undefined>;
+    /** Installation identity and namespace key; available after `ready()`. */
+    get installationIdentity(): {
+        installationId: string;
+        namespaceKey: string;
+    };
+    private readChunkRange;
+    private inflate;
+    private decode;
+    /** Collapse provider failures to stable, secret-free codes. */
+    private provider;
+    private register;
+}
+/** Fresh opaque intent identifier for one upload attempt. */
+export declare function reportingRowWriteIntentIdV1(): string;

package/dist/lib/reporting/ledger/row-storage.d.ts

@@ -0,0 +1,224 @@
+import { type ReportingEncodedRowsV1, type ReportingRowChunkManifestV1 } from './row-encoding';
+import { type ReportingRowObjectProviderV1 } from './row-storage-object';
+/**
+ * Revision row storage (shared SDK persistence spec,
+ * adcontextprotocol/adcp#7996 §3). Revision headers stay in the ledger
+ * document; rows live as canonical JSONL chunks in a storage binding, and
+ * every read is verified against digests committed in PostgreSQL before rows
+ * are released.
+ */
+export { ReportingRowStoreError, isReportingRowStoreError } from './row-storage-errors';
+export type { ReportingRowStoreErrorCode } from './row-storage-errors';
+/** Rows stored as chunk bodies in the ledger's own PostgreSQL schema. */
+export interface ReportingPostgresRowBindingV1 {
+    kind: 'postgres';
+}
+/**
+ * Rows stored as one object per chunk through a registered provider. The
+ * definition lives in host code, which makes it the allowlist: a row set
+ * whose recorded binding identity differs from the configured definition is
+ * never read from or written to.
+ */
+export interface ReportingObjectRowBindingV1 {
+    kind: 'object';
+    /** Name of a provider registered in `ReportingRowStorageOptionsV1.providers`. */
+    provider: string;
+    /** Non-secret provider coordinates, validated by the provider's closed schema. */
+    location: Readonly<Record<string, string>>;
+    /** Owned key prefix. Sweeps and deletes never touch keys outside it. */
+    prefix: string;
+    /** Object key template; see `REPORTING_ROW_DEFAULT_KEY_TEMPLATE`. */
+    keyTemplate?: string;
+    /** Stored encoding; digests always cover uncompressed bytes. Default `gzip`. */
+    compression?: 'none' | 'gzip';
+    /** Host-mapped client reference passed to the provider; never a secret. */
+    credentialRef?: string;
+}
+export type ReportingRowBindingDefinitionV1 = ReportingPostgresRowBindingV1 | ReportingObjectRowBindingV1;
+export interface ReportingRowBindingSelectionInputV1 {
+    account_id: string;
+    reporting_obligation_id: string;
+    row_set_kind: 'revision' | 'adjustment';
+    finality?: 'snapshot' | 'official';
+    row_count: number;
+    canonical_byte_count: number;
+}
+export interface ReportingRowStorageOptionsV1 {
+    /**
+     * Logical binding ID → immutable definition. Defaults to a single
+     * `postgres` binding. Changing a definition requires a new ID; keep retired
+     * definitions configured while revisions still reference them.
+     */
+    bindings?: Readonly<Record<string, ReportingRowBindingDefinitionV1>>;
+    /** Object-storage providers by name. */
+    providers?: Readonly<Record<string, ReportingRowObjectProviderV1>>;
+    /** Picks the binding for each new row set. Defaults to the only binding, or `postgres`. */
+    selectRowBinding?(input: ReportingRowBindingSelectionInputV1): string | Promise<string>;
+    /**
+     * Stable deployment namespace, combined with the schema's installation
+     * identity into each binding's `namespace_key`. Defaults to `default`.
+     */
+    deploymentNamespace?: string;
+    /** Deadline for one row set's uploads. Default 60 seconds. */
+    writeDeadlineMilliseconds?: number;
+    /** Deadline for one object read. Default 30 seconds. */
+    readDeadlineMilliseconds?: number;
+}
+export interface ReportingRowSetPrepareInputV1 {
+    rowSetId: string;
+    rowSetKind: 'revision' | 'adjustment';
+    accountId: string;
+    obligationId: string;
+    rows: readonly Record<string, unknown>[];
+    finality?: 'snapshot' | 'official';
+    /** Reporting period start, used for `{period_date}` in object keys. */
+    periodStart?: string;
+    /** Committed protocol binding the chunks must reproduce. */
+    binding: {
+        sha256: string;
+        byteCount: number;
+        rowCount: number;
+    };
+    /** Required for revisions (`revision_envelope_v1`); omitted for adjustments (`rows_v1`). */
+    controlTotals?: readonly unknown[];
+    /** Overrides `selectRowBinding` (for example, to migrate inline rows into a PostgreSQL binding). */
+    bindingId?: string;
+}
+interface PreparedObjectV1 {
+    readonly key: string;
+    readonly physicalBytes: Buffer;
+    readonly physicalSha256: string;
+    readonly compression: 'none' | 'gzip';
+}
+export interface ReportingPreparedRowSetV1 {
+    readonly input: ReportingRowSetPrepareInputV1;
+    readonly encoded: ReportingEncodedRowsV1;
+    readonly bindingId: string;
+    readonly binding: ReportingRowBindingDefinitionV1;
+    readonly digestProfile: 'revision_envelope_v1' | 'rows_v1';
+    /** Object kind only: one planned object per chunk. */
+    readonly objects?: readonly PreparedObjectV1[];
+}
+/** Where one chunk was stored; recorded in the chunk manifest. */
+export interface ReportingRowChunkLocatorV1 {
+    objectKey: string;
+    nativeVersion: string;
+    compression: 'none' | 'gzip';
+    physicalSha256: string;
+    physicalByteCount: number;
+    /** Whether this upload created the object (as opposed to adopting identical bytes). */
+    created: boolean;
+}
+interface QueryableV1 {
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: Row[];
+        rowCount?: number | null;
+    }>;
+}
+/** A row set whose chunk manifest has been verified against its committed digest. */
+export interface ReportingRowSetHandleV1 {
+    readonly rowSetId: string;
+    readonly rowSetKind: 'revision' | 'adjustment';
+    readonly accountId: string;
+    readonly obligationId: string;
+    readonly digestProfile: 'revision_envelope_v1' | 'rows_v1';
+    readonly contentSha256: string;
+    readonly canonicalByteCount: number;
+    readonly rowCount: number;
+    readonly rowManifestSha256: string;
+    readonly bindingId: string;
+    readonly bindingIdentitySha256: string;
+    readonly kind: 'postgres' | 'object';
+    readonly manifests: readonly ReportingRowChunkManifestV1[];
+    /** Object kind only, by chunk index. */
+    readonly locators: readonly (Omit<ReportingRowChunkLocatorV1, 'created'> | undefined)[];
+}
+/**
+ * Reads and writes revision row sets. PostgreSQL-kind reads are always
+ * available once the row-storage migration is applied; object-kind reads need
+ * the binding and its provider configured. Writes require an explicit opt-in
+ * on the owning store.
+ */
+export declare class ReportingRowStorageV1 {
+    private readonly pool;
+    private readonly options;
+    private readonly bindings;
+    private readonly providers;
+    private readonly deploymentNamespace;
+    private readonly writeDeadline;
+    private readonly readDeadline;
+    private readied?;
+    private installation?;
+    constructor(pool: QueryableV1, options?: ReportingRowStorageOptionsV1);
+    /** Deadline budget a writer must still hold on its lease before uploading. */
+    get writeDeadlineMilliseconds(): number;
+    /** Probe the schema and every provider, and register (or verify) every configured binding. Idempotent. */
+    ready(): Promise<void>;
+    /** Encode rows, prove the chunks reproduce the committed binding, select a binding and plan objects. */
+    prepare(input: ReportingRowSetPrepareInputV1): Promise<ReportingPreparedRowSetV1>;
+    /**
+     * Upload a prepared object-kind row set, create-only. An object already at a
+     * planned key is adopted only when its bytes decode to the exact chunk;
+     * otherwise `CONTENT_CONFLICT`. `onCreated` is awaited for every object this
+     * call created, before the next upload, so the caller can record it in its
+     * write intent.
+     */
+    upload(prepared: ReportingPreparedRowSetV1, intentId: string, onCreated: (object: {
+        objectKey: string;
+        nativeVersion: string;
+    }) => Promise<void>, signal?: AbortSignal): Promise<ReportingRowChunkLocatorV1[]>;
+    /**
+     * Persist a prepared row set inside the caller's ledger transaction:
+     * bodies for the `postgres` kind, or the uploaded locators for the object
+     * kind. Replays of an identical row set are no-ops; a conflicting row set
+     * under the same ID is refused.
+     */
+    writeInTransaction(transaction: QueryableV1, prepared: ReportingPreparedRowSetV1, locators?: readonly ReportingRowChunkLocatorV1[], sharedFromRowSetId?: string): Promise<void>;
+    /**
+     * Load a row set and verify its chunk manifest against the committed digest.
+     * Returns `null` when no row set exists (legacy inline rows) or it belongs
+     * to another account. Throws `ROWS_EXPIRED` / `ROWS_UNAVAILABLE` when the
+     * rows were pruned or lost.
+     */
+    find(rowSetId: string, accountId: string, queryable?: QueryableV1): Promise<ReportingRowSetHandleV1 | null>;
+    /** Verified rows `[offset, offset + limit)` in ordinal order. */
+    readPage(handle: ReportingRowSetHandleV1, offset: number, limit: number, signal?: AbortSignal): Promise<Record<string, unknown>[]>;
+    /**
+     * Every row, verified chunk by chunk and against the committed binding.
+     * `controlTotals` are required for revision row sets.
+     */
+    readAll(handle: ReportingRowSetHandleV1, controlTotals?: readonly unknown[], options?: {
+        maxBytes?: number;
+        signal?: AbortSignal;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Delete exact object versions through the configured binding's provider.
+     * `absent` counts as success. Only object-kind bindings are accepted.
+     */
+    deleteObjects(bindingId: string, objects: readonly {
+        objectKey: string;
+        nativeVersion: string;
+    }[], signal?: AbortSignal): Promise<void>;
+    /**
+     * A live row set in the same obligation and binding whose rows are
+     * byte-identical (same manifest digest), with its chunk locations. Sharing
+     * never crosses obligations, so it never crosses consumers.
+     */
+    findShareable(queryable: QueryableV1, prepared: ReportingPreparedRowSetV1): Promise<{
+        rowSetId: string;
+        locators: ReportingRowChunkLocatorV1[];
+    } | undefined>;
+    /** Installation identity and namespace key; available after `ready()`. */
+    get installationIdentity(): {
+        installationId: string;
+        namespaceKey: string;
+    };
+    private readChunkRange;
+    private inflate;
+    private decode;
+    /** Collapse provider failures to stable, secret-free codes. */
+    private provider;
+    private register;
+}
+/** Fresh opaque intent identifier for one upload attempt. */
+export declare function reportingRowWriteIntentIdV1(): string;