@kubun/store-connector 0.17.2 → 0.18.0

package/lib/document-sweep.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export declare class ConnectorDocumentSweepError extends Error {
+    get code(): 'CONNECTOR_SWEEP_UNFINISHED_OPERATION';
+    constructor(documentID: string);
+}
+export type DocumentSweepMethods = Pick<ConnectorStoreAPI, 'hasDocumentConnectorWork' | 'sweepDocumentRows'>;
+export declare function createDocumentSweepMethods({ db }: ConnectorStoreContext): DocumentSweepMethods;

package/lib/document-sweep.js

@@ -0,0 +1,46 @@
+const OBSERVATION_TYPE = 'connector.observation';
+/** States an operation can still leave: its row is the idempotency record of a provider write. */ const UNFINISHED = [
+    'attempted',
+    'reconcile_only'
+];
+const FINISHED = [
+    'committed',
+    'dead'
+];
+export class ConnectorDocumentSweepError extends Error {
+    get code() {
+        return 'CONNECTOR_SWEEP_UNFINISHED_OPERATION';
+    }
+    constructor(documentID){
+        super(`Document ${documentID} has an unfinished connector operation`);
+        this.name = 'ConnectorDocumentSweepError';
+    }
+}
+// Plain statements on `db`, never `db.transaction()`: both run inside the caller's sweep
+// transaction, where a nested transaction is refused.
+export function createDocumentSweepMethods({ db }) {
+    const unfinishedOperation = async (documentID)=>{
+        const row = await db.selectFrom('kubun_connector_operation').select('operation_id').where('document_id', '=', documentID).where('state', 'in', UNFINISHED).limit(1).executeTakeFirst();
+        return row !== undefined;
+    };
+    const anyRow = async (table, documentID)=>{
+        const row = await db.selectFrom(table).select('document_id').where('document_id', '=', documentID).limit(1).executeTakeFirst();
+        return row !== undefined;
+    };
+    return {
+        async hasDocumentConnectorWork (documentID) {
+            return await anyRow('kubun_connector_projection_watch', documentID) || await anyRow('kubun_connector_sweep_candidate', documentID) || await anyRow('kubun_connector_entity_trim', documentID) || await unfinishedOperation(documentID);
+        },
+        async sweepDocumentRows (documentID) {
+            // Deleting it would let a replayed request write to the provider again.
+            if (await unfinishedOperation(documentID)) throw new ConnectorDocumentSweepError(documentID);
+            // Every copy, whatever its owner or signer: the document ID names one document.
+            await db.deleteFrom('kubun_connector_observation_records').where('type', '=', OBSERVATION_TYPE).where('id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_observation_repair').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_entity_trim').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_projection_watch').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_sweep_candidate').where('document_id', '=', documentID).execute();
+            await db.deleteFrom('kubun_connector_operation').where('document_id', '=', documentID).where('state', 'in', FINISHED).execute();
+        }
+    };
+}

package/lib/entity-trim.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type EntityTrimMethods = Pick<ConnectorStoreAPI, 'getEntityTrim' | 'setEntityTrim' | 'clearEntityTrim'>;
+export declare function createEntityTrimMethods(context: ConnectorStoreContext): EntityTrimMethods;

package/lib/entity-trim.js

@@ -0,0 +1,36 @@
+import { decodeJSONColumn } from './serialization.js';
+export function createEntityTrimMethods(context) {
+    const { db } = context;
+    const methods = {
+        // --- Entity trim records ---
+        async getEntityTrim (documentID) {
+            const row = await db.selectFrom('kubun_connector_entity_trim').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            if (row == null) return null;
+            return {
+                documentID: row.document_id,
+                ownerDID: row.owner_did,
+                connectorName: row.connector_name,
+                trimmedFields: decodeJSONColumn(row.trimmed_fields),
+                updatedAt: row.updated_at
+            };
+        },
+        async setEntityTrim (input) {
+            const trimmedFields = JSON.stringify(input.trimmedFields);
+            const updatedAt = Date.now();
+            await db.insertInto('kubun_connector_entity_trim').values({
+                document_id: input.documentID,
+                owner_did: input.ownerDID,
+                connector_name: input.connectorName,
+                trimmed_fields: trimmedFields,
+                updated_at: updatedAt
+            }).onConflict((oc)=>oc.column('document_id').doUpdateSet({
+                    trimmed_fields: trimmedFields,
+                    updated_at: updatedAt
+                })).execute();
+        },
+        async clearEntityTrim (documentID) {
+            await db.deleteFrom('kubun_connector_entity_trim').where('document_id', '=', documentID).execute();
+        }
+    };
+    return methods;
+}

package/lib/index.d.ts

@@ -1,8 +1,11 @@
 import type { StoreProvider } from '@kubun/db';
 import type { ConnectorStoreAPI } from './api.js';
-export type { ArmWatchOptions, ArmWatchOutcome, ArmWatchReason, ClaimOperationInput, ConnectorOperation, ConnectorOperationOp, ConnectorOperationState, ConnectorStoreAPI, ConnectorStoreDeps, DeferReason, FinalizeOperationInput, PendingAuthRecord, ProjectionWatch, ProjectionWatchIdentity, ProjectionWatchVerificationStatus, ReadWinner, RecordOperationInput, RecordVerificationInput, RecordVerificationOutcome, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStatus, TrackedOperationFilter, } from './api.js';
+export type { AcquireLeaseParams, ArmWatchOptions, ArmWatchOutcome, ArmWatchReason, ClaimOperationInput, ConnectorOperation, ConnectorOperationOp, ConnectorOperationState, ConnectorStoreAPI, ConnectorStoreDeps, DeferReason, EntityTrimInput, EntityTrimRecord, FinalizeOperationInput, PendingAuthRecord, ProjectionWatch, ProjectionWatchIdentity, ProjectionWatchVerificationStatus, ReadWinner, ReadWinners, RecordOperationInput, RecordVerificationInput, RecordVerificationOutcome, ReleaseLeaseParams, RenewLeaseParams, SweepApplyFailureInput, SweepCandidate, SweepCandidateInput, SweepCandidateKey, SweepKey, SweepOutcomeInput, SweepReceipt, SweepReceiptKey, SyncProgressCASCurrent, SyncProgressCASResult, SyncProgressRecompute, SyncState, SyncStateEntry, SyncStatus, TrackedOperationFilter, UpdateSyncProgressParams, } from './api.js';
 export { createConnectorStore } from './api.js';
 export { createConnectorStoreDefinition } from './definition.js';
+export { ConnectorDocumentSweepError } from './document-sweep.js';
+export { ConnectorObservationRecordError, ConnectorObservationRecordTypeError, connectorObservationRecordAdapter, type ObservationRepair, type ObservationRepairWrite, type ObservationRepairWritePage, observationProviderOfRecords, type WrittenObservationRepair, } from './observation-records.js';
+export { MAX_SWEEP_APPLY_ATTEMPTS } from './sweep-state.js';
 export declare const CONNECTOR_STORE: "connector";
 export declare function getConnectorStore(provider: StoreProvider): Promise<ConnectorStoreAPI>;
-export type { ConnectorSyncState, ConnectorSyncStateTable, ConnectorTables, } from './tables.js';
+export type { ConnectorEntityTrim, ConnectorEntityTrimTable, ConnectorSyncState, ConnectorSyncStateTable, ConnectorTables, } from './tables.js';

package/lib/index.js

@@ -1,5 +1,8 @@
 export { createConnectorStore } from './api.js';
 export { createConnectorStoreDefinition } from './definition.js';
+export { ConnectorDocumentSweepError } from './document-sweep.js';
+export { ConnectorObservationRecordError, ConnectorObservationRecordTypeError, connectorObservationRecordAdapter, observationProviderOfRecords } from './observation-records.js';
+export { MAX_SWEEP_APPLY_ATTEMPTS } from './sweep-state.js';
 export const CONNECTOR_STORE = 'connector';
 export function getConnectorStore(provider) {
     return provider.getStore(CONNECTOR_STORE);

package/lib/migrations.js

@@ -2,6 +2,30 @@ export function getConnectorMigrations(ctx) {
     const t = ctx.types;
     const init = {
         async up (db) {
+            await db.schema.createTable('kubun_connector_sweep_receipt').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('sequence', t.bigint, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('scope', t.text, (col)=>col.notNull()).addColumn('keep', t.text, (col)=>col.notNull()).addColumn('source_fetch_hlc', t.text, (col)=>col.notNull()).addColumn('predicate', t.text).addColumn('kind', t.text, (col)=>col.notNull()).addColumn('complete', 'integer', (col)=>col.notNull()).addColumn('created_at', t.bigint, (col)=>col.notNull()).addColumn('committed_at', t.bigint).addPrimaryKeyConstraint('kubun_connector_sweep_receipt_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition',
+                'provenance'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_sweep_candidate').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('document_id', t.text, (col)=>col.notNull()).addColumn('source_id', t.text, (col)=>col.notNull()).addColumn('model_id', t.text, (col)=>col.notNull()).addColumn('state', t.text, (col)=>col.notNull()).addColumn('attempts', 'integer', (col)=>col.notNull()).addColumn('apply_failures', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('last_error', t.text).addColumn('next_attempt_at', t.bigint, (col)=>col.notNull().defaultTo(0)).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_sweep_candidate_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition',
+                'provenance',
+                'document_id'
+            ]).execute();
+            await db.schema.createIndex('kubun_connector_sweep_candidate_due_idx').ifNotExists().on('kubun_connector_sweep_candidate').columns([
+                'owner_did',
+                'connector_name',
+                'state',
+                'next_attempt_at'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_sweep_checkpoint').ifNotExists().addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('partition', t.text, (col)=>col.notNull()).addColumn('provenance', t.text, (col)=>col.notNull()).addColumn('receipt_sequence', t.bigint, (col)=>col.notNull()).addColumn('updated_at', t.bigint, (col)=>col.notNull()).addPrimaryKeyConstraint('kubun_connector_sweep_checkpoint_pkey', [
+                'owner_did',
+                'connector_name',
+                'partition'
+            ]).execute();
             // Connector sync state
             await db.schema.createTable('kubun_connector_sync_state').ifNotExists().addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('checkpoint', t.text).addColumn('last_synced_at', t.text, (col)=>col.notNull()).addColumn('entity_count', 'integer', (col)=>col.notNull().defaultTo(0)).addColumn('status', t.text, (col)=>col.notNull()).addColumn('error', t.text)// Lease expiry for atomic sync-claim coordination. ms-epoch (Date.now)
             // overflows int32 on Postgres; bigint holds it and the adapter's int8
@@ -29,7 +53,8 @@ export function getConnectorMigrations(ctx) {
             // time, both needed to complete the token exchange and to fill in
             // `PendingAuthRecord`'s required fields.
             .addColumn('redirect_url', t.text, (col)=>col.notNull())// JSON-encoded `Array<string>`.
-            .addColumn('scopes', t.text, (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            .addColumn('scopes', t.text, (col)=>col.notNull())// 1 when start-auth requested only the missing scopes, else 0.
+            .addColumn('is_incremental', 'integer', (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
             // the adapter's int8 parser reads it back as a JS number. The sweep in
             // `deleteExpiredPendingAuth` keys off this column, not `created_at`.
             .addColumn('expires_at', t.bigint, (col)=>col.notNull()).execute();
@@ -99,8 +124,33 @@ export function getConnectorMigrations(ctx) {
             // Document lookup: an applied write names only its document id
             // (`getWatchByDocument`), which the ingress index cannot serve alone.
             await db.schema.createIndex('idx_connector_watch_document').ifNotExists().on('kubun_connector_projection_watch').column('document_id').execute();
+            await db.schema.createTable('kubun_connector_observation_records').ifNotExists().addColumn('type', t.text, (col)=>col.notNull()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('id', t.text, (col)=>col.notNull()).addColumn('op_hash', t.text, (col)=>col.notNull()).addColumn('hlc', t.text, (col)=>col.notNull()).addColumn('op_jwt', t.text, (col)=>col.notNull()).addColumn('payload', t.binary).addPrimaryKeyConstraint('kubun_connector_observation_records_pkey', [
+                'type',
+                'owner',
+                'id',
+                'op_hash'
+            ]).execute();
+            await db.schema.createTable('kubun_connector_observation_repair').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner', t.text, (col)=>col.notNull()).addColumn('fetch_hlc', t.text, (col)=>col.notNull()).addColumn('decision_hlc', t.text, (col)=>col.notNull()).addColumn('present', 'integer', (col)=>col.notNull()).addColumn('value_digest', t.text)// When the obligation was last written, so a reader can take only the
+            // ones written since it last looked.
+            .addColumn('written_at', t.bigint, (col)=>col.notNull()).execute();
+            await db.schema.createIndex('idx_connector_observation_repair_written').ifNotExists().on('kubun_connector_observation_repair').columns([
+                'written_at',
+                'document_id'
+            ]).execute();
+            // The source values fitted to a model's caps when a document was last
+            // written, keyed by that document. Replaced on every write that trims,
+            // removed by one that does not.
+            await db.schema.createTable('kubun_connector_entity_trim').ifNotExists().addColumn('document_id', t.text, (col)=>col.notNull().primaryKey()).addColumn('owner_did', t.text, (col)=>col.notNull()).addColumn('connector_name', t.text, (col)=>col.notNull()).addColumn('trimmed_fields', t.text, (col)=>col.notNull())// ms-epoch (Date.now) overflows int32 on Postgres; bigint holds it and
+            // the adapter's int8 parser reads it back as a JS number.
+            .addColumn('updated_at', t.bigint, (col)=>col.notNull()).execute();
         },
         async down (db) {
+            await db.schema.dropTable('kubun_connector_sweep_checkpoint').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_sweep_candidate').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_sweep_receipt').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_observation_repair').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_observation_records').ifExists().execute();
+            await db.schema.dropTable('kubun_connector_entity_trim').ifExists().execute();
             await db.schema.dropTable('kubun_connector_projection_watch').ifExists().execute();
             await db.schema.dropTable('kubun_connector_operation').ifExists().execute();
             await db.schema.dropTable('kubun_connector_pending_auth').ifExists().execute();

package/lib/observation-records.d.ts

@@ -0,0 +1,52 @@
+import type { MethodRegistry } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import { type Adapter } from '@kubun/db-adapter';
+import { type RecordDecision, type RecordKey, type RecordStoreAdapter, type SignedRecord } from '@kubun/records';
+import { type Kysely } from 'kysely';
+import type { ConnectorTables } from './tables.js';
+export declare function observationProviderOfRecords(records: RecordStoreAdapter): StoreProvider | null;
+export declare class ConnectorObservationRecordTypeError extends Error {
+    constructor(type: string);
+}
+export declare class ConnectorObservationRecordError extends Error {
+    constructor(message: string);
+}
+export type ObservationRepair = {
+    documentID: string;
+    owner: string;
+    fetchHLC: string;
+    decisionHLC: string;
+    present: boolean;
+    valueDigest: string | null;
+};
+/** Where a reader of obligation writes stands: the last write it took. */
+export type ObservationRepairWrite = {
+    writtenAt: number;
+    documentID: string;
+};
+/** An obligation with the time it was last written. */
+export type WrittenObservationRepair = ObservationRepair & {
+    writtenAt: number;
+};
+export type ObservationRepairWritePage = {
+    after: ObservationRepairWrite | null;
+    limit: number;
+};
+export type ObservationRecordMethods = {
+    getObservationRecordDecision(key: RecordKey, methods?: MethodRegistry): Promise<RecordDecision | null>;
+    /** The decisions of many keys read together; a key with no valid copy is absent. */
+    getObservationRecordDecisions(keys: ReadonlyArray<RecordKey>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    listObservationRecordDecisions(types: ReadonlyArray<string>, methods?: MethodRegistry): Promise<Array<RecordDecision>>;
+    putObservationRecordCopy(record: SignedRecord, methods?: MethodRegistry): Promise<void>;
+    pruneObservationRecordCopy(key: RecordKey, signerDID: string, methods?: MethodRegistry): Promise<void>;
+    lockObservationRecordKeys(keys: ReadonlyArray<string>): Promise<void>;
+    getObservationRepair(documentID: string): Promise<ObservationRepair | null>;
+    /** The obligations of many documents read together; a document with none is absent. */
+    getObservationRepairs(documentIDs: ReadonlyArray<string>): Promise<Map<string, ObservationRepair>>;
+    /** One page of repair obligations in write order, written after `after`. */
+    listObservationRepairsWrittenSince(page: ObservationRepairWritePage): Promise<Array<WrittenObservationRepair>>;
+    putObservationRepair(repair: ObservationRepair): Promise<void>;
+    clearObservationRepair(documentID: string): Promise<void>;
+};
+export declare function createObservationRecordMethods(db: Kysely<ConnectorTables>, adapter: Adapter): ObservationRecordMethods;
+export declare function connectorObservationRecordAdapter(provider: StoreProvider, methods?: MethodRegistry): Promise<RecordStoreAdapter>;

package/lib/observation-records.js

@@ -0,0 +1,310 @@
+import { AbstractPostgresAdapter, chunked } from '@kubun/db-adapter';
+import { compareRecordDecisionHLC, parseCanonicalHLC, recordClaimDigest, recordDecisionFromVerifiedCopies, recordKeyText, recordPayloadMatches, recordSignerKey, verifySignedRecord } from '@kubun/records';
+import { sql } from 'kysely';
+const TYPE = 'connector.observation';
+const providers = new WeakMap();
+export function observationProviderOfRecords(records) {
+    return providers.get(records) ?? null;
+}
+export class ConnectorObservationRecordTypeError extends Error {
+    constructor(type){
+        super(`Unsupported connector observation record type: ${type}`);
+        this.name = 'ConnectorObservationRecordTypeError';
+    }
+}
+export class ConnectorObservationRecordError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'ConnectorObservationRecordError';
+    }
+}
+function requireType(type) {
+    if (type !== TYPE) throw new ConnectorObservationRecordTypeError(type);
+}
+function lockKey(key) {
+    return JSON.stringify([
+        key.type,
+        JSON.stringify([
+            key.owner,
+            key.id
+        ])
+    ]);
+}
+function copyFromRow(row) {
+    return {
+        type: row.type,
+        owner: row.owner,
+        id: row.id,
+        hlc: row.hlc,
+        opJWT: row.op_jwt,
+        opHash: row.op_hash,
+        payload: row.payload === null ? null : Uint8Array.from(row.payload)
+    };
+}
+async function verifiedRows(rows, methods) {
+    const result = [];
+    for (const row of rows){
+        const copy = copyFromRow(row);
+        const op = await verifySignedRecord(copy, methods);
+        if (op === null || !recordPayloadMatches(copy, op.claim)) continue;
+        if (typeof op.claim.meta.version !== 'string' || parseCanonicalHLC(op.claim.meta.version) === null) continue;
+        const signerKey = recordSignerKey(op.issuer, copy.opJWT);
+        if (signerKey !== null) result.push({
+            row,
+            copy,
+            op,
+            signerKey
+        });
+    }
+    return result;
+}
+function decision(key, rows) {
+    return recordDecisionFromVerifiedCopies(key, rows, 'version');
+}
+function repairFromRow(row) {
+    return {
+        documentID: row.document_id,
+        owner: row.owner,
+        fetchHLC: row.fetch_hlc,
+        decisionHLC: row.decision_hlc,
+        present: row.present === 1,
+        valueDigest: row.value_digest
+    };
+}
+export function createObservationRecordMethods(db, adapter) {
+    const rowsFor = async (key, tx = db)=>await tx.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', key.type).where('owner', '=', key.owner).where('id', '=', key.id).execute();
+    const lockKeys = async (tx, keys)=>{
+        if (!(adapter instanceof AbstractPostgresAdapter)) return;
+        for (const key of [
+            ...new Set(keys)
+        ].sort())await sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`.execute(tx);
+    };
+    const write = async (fn)=>db.isTransaction ? await fn(db) : await db.transaction().execute(fn);
+    return {
+        async getObservationRecordDecision (key, methods) {
+            requireType(key.type);
+            return decision(key, await verifiedRows(await rowsFor(key), methods));
+        },
+        async getObservationRecordDecisions (keys, methods) {
+            for (const key of keys)requireType(key.type);
+            const wanted = new Map();
+            for (const key of keys)wanted.set(JSON.stringify([
+                key.owner,
+                key.id
+            ]), key);
+            const ids = [
+                ...new Set(keys.map((key)=>key.id))
+            ];
+            const groups = new Map();
+            for (const chunk of chunked(ids)){
+                const rows = await db.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', TYPE).where('id', 'in', chunk).execute();
+                for (const row of rows){
+                    const address = JSON.stringify([
+                        row.owner,
+                        row.id
+                    ]);
+                    if (!wanted.has(address)) continue;
+                    const group = groups.get(address) ?? [];
+                    group.push(row);
+                    groups.set(address, group);
+                }
+            }
+            const result = [];
+            for (const [address, group] of groups){
+                const key = wanted.get(address);
+                if (key === undefined) continue;
+                const current = decision(key, await verifiedRows(group, methods));
+                if (current !== null) result.push(current);
+            }
+            return result;
+        },
+        async listObservationRecordDecisions (types, methods) {
+            for (const type of types)requireType(type);
+            if (types.length === 0) return [];
+            const rows = await db.selectFrom('kubun_connector_observation_records').selectAll().where('type', '=', TYPE).orderBy('owner').orderBy('id').execute();
+            const groups = new Map();
+            for (const row of rows){
+                const address = JSON.stringify([
+                    row.owner,
+                    row.id
+                ]);
+                const group = groups.get(address) ?? [];
+                group.push(row);
+                groups.set(address, group);
+            }
+            const result = [];
+            for (const group of groups.values()){
+                const first = group[0];
+                if (first === undefined) continue;
+                const current = decision({
+                    type: TYPE,
+                    owner: first.owner,
+                    id: first.id
+                }, await verifiedRows(group, methods));
+                if (current !== null) result.push(current);
+            }
+            return result;
+        },
+        async putObservationRecordCopy (record, methods) {
+            requireType(record.type);
+            const op = await verifySignedRecord(record, methods);
+            if (op === null || !recordPayloadMatches(record, op.claim)) throw new ConnectorObservationRecordError('Observation record is not a valid signed copy');
+            const version = op.claim.meta.version;
+            if (typeof version !== 'string' || parseCanonicalHLC(version) === null) throw new ConnectorObservationRecordError('Observation decision version is invalid');
+            const signerKey = recordSignerKey(op.issuer, record.opJWT);
+            if (signerKey === null) throw new ConnectorObservationRecordError('Observation signer key is invalid');
+            const key = {
+                type: TYPE,
+                owner: record.owner,
+                id: record.id
+            };
+            await write(async (tx)=>{
+                await lockKeys(tx, [
+                    lockKey(key)
+                ]);
+                const rows = await rowsFor(key, tx);
+                const valid = await verifiedRows(rows, methods);
+                const current = decision(key, valid);
+                const digest = recordClaimDigest(op.claim);
+                const order = current === null ? 1 : compareRecordDecisionHLC(version, current.decisionHLC) || (digest < current.contentDigest ? -1 : digest > current.contentDigest ? 1 : 0);
+                if (order < 0) return;
+                const retained = order === 0 ? valid.filter((entry)=>entry.op.claim.meta.version === version && recordClaimDigest(entry.op.claim) === digest) : [];
+                const sameSigner = retained.find((entry)=>entry.signerKey === signerKey);
+                const incomingWinsSigner = sameSigner === undefined || record.opHash < sameSigner.copy.opHash;
+                for (const row of rows){
+                    const entry = retained.find((candidate)=>candidate.row.op_hash === row.op_hash);
+                    if (entry !== undefined && entry.signerKey !== signerKey) continue;
+                    if (entry !== undefined && !incomingWinsSigner && entry.copy.opHash === sameSigner?.copy.opHash) continue;
+                    await tx.deleteFrom('kubun_connector_observation_records').where('type', '=', TYPE).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', row.op_hash).execute();
+                }
+                if (!incomingWinsSigner) return;
+                await tx.insertInto('kubun_connector_observation_records').values({
+                    type: TYPE,
+                    owner: record.owner,
+                    id: record.id,
+                    op_hash: record.opHash,
+                    hlc: record.hlc,
+                    op_jwt: record.opJWT,
+                    payload: record.payload === null ? null : adapter.encodeBinary(record.payload)
+                }).onConflict((oc)=>oc.columns([
+                        'type',
+                        'owner',
+                        'id',
+                        'op_hash'
+                    ]).doNothing()).execute();
+            });
+        },
+        async pruneObservationRecordCopy (key, signerDID, methods) {
+            requireType(key.type);
+            await write(async (tx)=>{
+                await lockKeys(tx, [
+                    lockKey(key)
+                ]);
+                const valid = await verifiedRows(await rowsFor(key, tx), methods);
+                if (valid.filter((entry)=>entry.op.issuer !== signerDID).length === 0) return;
+                for (const entry of valid){
+                    if (entry.op.issuer !== signerDID) continue;
+                    await tx.deleteFrom('kubun_connector_observation_records').where('type', '=', TYPE).where('owner', '=', key.owner).where('id', '=', key.id).where('op_hash', '=', entry.copy.opHash).execute();
+                }
+            });
+        },
+        async lockObservationRecordKeys (keys) {
+            if (!db.isTransaction) throw new ConnectorObservationRecordError('Observation locks require a transaction');
+            await lockKeys(db, keys);
+        },
+        async getObservationRepair (documentID) {
+            const row = await db.selectFrom('kubun_connector_observation_repair').selectAll().where('document_id', '=', documentID).executeTakeFirst();
+            return row === undefined ? null : repairFromRow(row);
+        },
+        async getObservationRepairs (documentIDs) {
+            const repairs = new Map();
+            for (const ids of chunked([
+                ...documentIDs
+            ])){
+                const rows = await db.selectFrom('kubun_connector_observation_repair').selectAll().where('document_id', 'in', ids).execute();
+                for (const row of rows)repairs.set(row.document_id, repairFromRow(row));
+            }
+            return repairs;
+        },
+        async listObservationRepairsWrittenSince (page) {
+            let query = db.selectFrom('kubun_connector_observation_repair').selectAll().orderBy('written_at').orderBy('document_id').limit(page.limit);
+            const after = page.after;
+            if (after !== null) {
+                query = query.where((eb)=>eb.or([
+                        eb('written_at', '>', after.writtenAt),
+                        eb.and([
+                            eb('written_at', '=', after.writtenAt),
+                            eb('document_id', '>', after.documentID)
+                        ])
+                    ]));
+            }
+            return (await query.execute()).map((row)=>({
+                    ...repairFromRow(row),
+                    writtenAt: Number(row.written_at)
+                }));
+        },
+        async putObservationRepair (repair) {
+            const values = {
+                owner: repair.owner,
+                fetch_hlc: repair.fetchHLC,
+                decision_hlc: repair.decisionHLC,
+                present: repair.present ? 1 : 0,
+                value_digest: repair.valueDigest,
+                written_at: Date.now()
+            };
+            await db.insertInto('kubun_connector_observation_repair').values({
+                document_id: repair.documentID,
+                ...values
+            }).onConflict((oc)=>oc.column('document_id').doUpdateSet(values)).execute();
+        },
+        async clearObservationRepair (documentID) {
+            await db.deleteFrom('kubun_connector_observation_repair').where('document_id', '=', documentID).execute();
+        }
+    };
+}
+export async function connectorObservationRecordAdapter(provider, methods) {
+    const connector = await provider.getStore('connector');
+    const records = {
+        isTransaction: provider.isTransactionBound,
+        async transaction (fn) {
+            return await provider.withTransaction(async (tx)=>await fn(await connectorObservationRecordAdapter(tx, methods)));
+        },
+        async get (key) {
+            requireType(key.type);
+            return await connector.getObservationRecordDecision(key, methods);
+        },
+        async getMany (keys) {
+            for (const key of keys)requireType(key.type);
+            const decisions = new Map();
+            for (const decision of (await connector.getObservationRecordDecisions(keys, methods))){
+                decisions.set(recordKeyText(decision.key), decision);
+            }
+            return decisions;
+        },
+        async list (types) {
+            for (const type of types)requireType(type);
+            return await connector.listObservationRecordDecisions(types, methods);
+        },
+        async putCopy (record) {
+            requireType(record.type);
+            await connector.putObservationRecordCopy(record, methods);
+        },
+        async pruneCopy (key, signerDID) {
+            requireType(key.type);
+            await connector.pruneObservationRecordCopy(key, signerDID, methods);
+        },
+        async lock (keys) {
+            for (const key of keys)requireType(key.type);
+            await connector.lockObservationRecordKeys(keys.map((key)=>JSON.stringify([
+                    key.type,
+                    key.key
+                ])));
+        },
+        async getObservationDocumentOwner (documentID) {
+            const graph = await provider.getStore('graph');
+            return (await graph.getDocument(documentID))?.owner ?? null;
+        }
+    };
+    providers.set(records, provider);
+    return records;
+}

package/lib/operations.d.ts

@@ -0,0 +1,4 @@
+import type { ConnectorStoreAPI } from './api-types.js';
+import type { ConnectorStoreContext } from './store-context.js';
+export type OperationsMethods = Pick<ConnectorStoreAPI, 'claimOperation' | 'acquireLease' | 'renewLease' | 'releaseLease' | 'getOperation' | 'listTrackedOperations' | 'hasNewerOperationOnDocument' | 'markSendStarted' | 'deferOperation' | 'recordOperation'>;
+export declare function createOperationsMethods(context: ConnectorStoreContext): OperationsMethods;