@framers/agentos-ext-account-sources 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @framers/agentos-ext-account-sources
 
-A person's own accounts as sources. This library defines `AccountSourceConnector` and the `SourceRef` every passage carries, with helpers for line ranges, links, bounded body reads, requests under the shared public-sources limiter and the cache lifetime of a read, and the contracts and pure rules of a durable, resumable synchronization.
+A person's own accounts as sources. This library defines `AccountSourceConnector` and the `SourceRef` every passage carries, with helpers for line ranges, links, bounded body reads, requests under the shared public-sources limiter and the cache lifetime of a read, and the contracts, pure rules and PostgreSQL store of a durable, resumable synchronization.
 
-Install `@framers/agentos-ext-account-sources` with its peer `@framers/agentos` 0.10.40 or later. Node.js 20.19 or later is required. The runtime dependency is `@framers/agentos-ext-public-sources`.
+Install `@framers/agentos-ext-account-sources` with its peer `@framers/agentos` 0.13.134 or later. Node.js 20.19 or later is required. The runtime dependencies are `@framers/agentos-ext-public-sources` and `@framers/sql-storage-adapter`.
 
 ## Connector
 
@@ -184,6 +184,50 @@ The rules are pure and take no lock: the store that commits a cursor reads the s
 
 `new SourceSyncFault(code, retryAt?)` carries a fixed failure code as its message (`source_sync_<code>`), never a provider's text, exposes `code` and `retryAt`, and throws `invalid_source_sync_fault` for an unknown code or a `retryAt` that is not a nonnegative safe integer. `assertSourceSyncPolicy(policy)` throws `invalid_source_sync_policy` unless every policy value is a positive safe integer.
 
+### The SQL store
+
+```ts
+import { createPostgresAdapter } from '@framers/sql-storage-adapter';
+import { sourceDerivationSchema } from '@framers/agentos/cognition/library';
+import { SqlAccountSourceSyncStore, sourceSyncSchema } from '@framers/agentos-ext-account-sources';
+
+const db = createPostgresAdapter({ connectionString: process.env.DATABASE_URL! });
+await db.open();
+// The host's migration runs the DDL; the store never does.
+for (const sql of [...sourceDerivationSchema(), ...sourceSyncSchema()]) await db.exec(sql);
+
+const store = new SqlAccountSourceSyncStore<PreparedPassages>(db, { bindings });
+const scope = { tenantId: 'tenant-1', ownerId: 'owner-1', connectionId: 'connection-1' };
+await store.create(scope, policy);
+await store.control(scope, { type: 'connect_started' });
+await store.control(scope, { type: 'grant_ready', use: { searchAskEnabled: true, liveEnabled: false } });
+const handle = await store.claim(scope, 'scheduled'); // null unless the connection is due and free
+```
+
+`SqlAccountSourceSyncStore` keeps each connection's state, policy, open checkpoint, lease and barrier, the cycle's work rows, the provenance of retained sources and the connection's exclusions in the tables `sourceSyncSchema(prefix)` creates: six statements, with a prefix of a lower-case letter and at most 31 lower-case letters, digits or underscores (`agentos_source_sync` unless given). It needs a PostgreSQL adapter with transactions and runs no DDL. Its `fence` is the core `SqlSourceDerivationStore` on the same adapter, over the tables of `sourceDerivationSchema(derivationPrefix)`: every change to an owner's sources runs under that owner's fence, the one that also commits and delivers results derived from them.
+
+The host supplies seven bindings. The store calls each inside its own transaction, on the transaction adapter it passes:
+
+| Binding | What it does |
+|---|---|
+| `active(tx, owner)` | Answers false for an account that is deleted or being deleted, whose admission is off or whose purge is pending; the store then claims, commits and reactivates nothing for it and answers no source state |
+| `allowance(tx, scope)` | Answers the connection's document and held-character ceilings after unrelated sources, and the remaining indexing balance |
+| `write(tx, scope, dependency, document, prepared)` | Writes the document's text and the host's prepared passages and vectors |
+| `chargeIndexed(tx, scope, characters)` | Charges committed characters to the indexing allowance |
+| `purge(tx, owner, affected)` | Deletes the host's text, passages and vectors in the affected scope |
+| `purgeResults(tx, owner, ids)` | Deletes the host's rows for these derived results |
+| `rebind(tx, scope, generation)` | Moves the connection's host rows to a new generation without changing their content, version or expiry |
+
+Provider reads, embedding and model calls run between store calls, never inside a binding.
+
+A sync holds a lease. `claim(scope, trigger)` answers a handle only when the owner is active, the `active` binding agrees, no barrier or live lease is set and `sourceSyncDue` holds; `renew(handle)` extends the lease by `leaseMs`; `release(handle, event?)` gives it up, records a deferral or a fixed failure when one is given, and keeps the checkpoint and work for the next claim. `openCycle` opens a checkpoint or answers the one already open, `page` records a page and queues its ids in one transaction (the same page sent again right after answers the same checkpoint; any other stale revision answers null), and `takeWork` marks the next due item attempted before the read. Every call made with a handle checks the owner fence, the lease token and expiry, the generation and the `active` binding in the same transaction, and answers null once any of them has moved on.
+
+`applyResult(handle, work, result, prepared)` keeps a `retry` result unresolved. Any other result first removes the source's previous copy and every derived result that depends on it, through the fence. A `document` result then replaces it in the same transaction (host write, indexing charge and provenance) when the source is not excluded and fits: the store ranks this connection's retained sources and the new one by activity time, newest first with ties broken by source id, keeps those inside `maxRetainedDocuments`, `maxHeldCharacters` and the allowance, and removes this connection's other sources, never another connection's. A document that does not fit is recorded as skipped with `document_limit`, `held_limit` or `indexing_limit`, and an excluded one with `excluded`. A failing binding rolls the whole application back. The answer carries a new handle, because each removal advances the owner's fence; later calls use it. `finish` commits the cycle's target cursor once every work item is terminal, counting from the stored work, and `progress` records the counts so far.
+
+Controls run with the owner blocked. `control(scope, event, policy?)` applies `connect_started`, `grant_ready`, `pause`, `resume`, `use_changed`, `policy_changed` (with the new policy), `grant_lost` or `disconnect`: it records a content-free barrier and drops the open cycle in one transaction, then completes the barrier and reactivates the owner. Connecting, grant loss and disconnecting remove the connection's sources, their derived results and its exclusions. Pause, resume, a use change and a policy change move retained content to the new generation with its version kept and its expiry never extended, so no result derived before the change can be delivered again; a policy change also removes the sources the new limits leave out and shortens the expiry of the rest to the new window. `exclude(scope, sourceId)` removes one source and keeps a content-free exclusion; `resetExclusions(scope)` clears them. Both raise the generation and clear the cursor. A control other than disconnecting throws `stale_source_sync` while the `active` binding refuses the owner. A barrier left by a failure blocks claims and reactivation until `recoverControl(scope)` completes it, and a lifecycle worker calls it even for a paused connection. `expire(scope, limit)` removes retained sources whose expiry has passed, also while the connection is paused, then the owner's expired derived results; reads refuse an expired source either way.
+
+`readCurrent(tx, derivation)` answers the current state of a derivation's sources for the fence's commit and delivery checks, and a connection with a barrier or pending revalidation reads as disconnected. `snapshot(scope)` answers metadata for authenticated controls and `documents(scope)` the retained provenance; neither authorizes delivery. Work rows and barriers hold ids and fixed values only. The documents table holds provenance, message timing and counts, never text; treat it, like the host's own tables, as restricted data for retention and backups.
+
 ## License
 
 Apache-2.0. This pack carries a copy of the repository's license.

package/dist/index.d.ts

@@ -11,4 +11,7 @@ export * from './cachePolicy.js';
 /** Durable synchronization contracts and pure state/checkpoint rules. */
 export * from './sync/types.js';
 export * from './sync/state.js';
+/** The migration-owned schema and the SQL store that persists synchronization under the owner fence. */
+export { sourceSyncSchema } from './sync/schema.js';
+export { SqlAccountSourceSyncStore, type SourceSyncStoredDocument, type SourceSyncAllowance, type SourceSyncStorageBindings, type SourceSyncStoreOptions, type SourceSyncHandle, type SourceSyncSnapshot, type SourceSyncControl, type SourceSyncApplication, type SourceSyncBarrier, } from './sync/SqlAccountSourceSyncStore.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC;AACjC,yEAAyE;AACzE,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC;AACjC,yEAAyE;AACzE,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,wGAAwG;AACxG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,KAAK,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,KAAK,yBAAyB,EACvF,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,kBAAkB,EAC3E,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,GAC3E,MAAM,qCAAqC,CAAC"}

package/dist/index.js

@@ -11,4 +11,7 @@ export * from './cachePolicy.js';
 /** Durable synchronization contracts and pure state/checkpoint rules. */
 export * from './sync/types.js';
 export * from './sync/state.js';
+/** The migration-owned schema and the SQL store that persists synchronization under the owner fence. */
+export { sourceSyncSchema } from './sync/schema.js';
+export { SqlAccountSourceSyncStore, } from './sync/SqlAccountSourceSyncStore.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC;AACjC,yEAAyE;AACzE,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,cAAc,YAAY,CAAC;AAC3B,yDAAyD;AACzD,cAAc,gBAAgB,CAAC;AAC/B,8DAA8D;AAC9D,cAAc,iBAAiB,CAAC;AAChC,oEAAoE;AACpE,cAAc,cAAc,CAAC;AAC7B,0EAA0E;AAC1E,cAAc,kBAAkB,CAAC;AACjC,yEAAyE;AACzE,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,wGAAwG;AACxG,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,yBAAyB,GAI1B,MAAM,qCAAqC,CAAC"}

package/dist/sync/SqlAccountSourceSyncStore.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview The durable source synchronization store on PostgreSQL through `@framers/sql-storage-adapter`:
+ * connection state, leases, checkpoints, work rows and the provenance of retained documents, with every change to
+ * an owner's content made under that owner's fence from the core derivation store.
+ * @module account-sources/sync/SqlAccountSourceSyncStore
+ */
+import type { StorageAdapter } from '@framers/sql-storage-adapter';
+import { SqlSourceDerivationStore, type SourceDependency, type SourceDependencyState, type SourceDerivation, type SourceOwnerScope, type SourceInvalidation, type SourceFenceTicket } from '@framers/agentos/cognition/library';
+import type { SourceSyncScope, SourceSyncState, SourceSyncPolicy, SourceSyncLease, SourceSyncTrigger, SourceSyncCheckpoint, SourceSyncCycleInput, SourceSyncPage, SourceSyncWork, SourceSyncDocument, SourceSyncMessageSpan, SourceSyncReadResult, SourceSyncWorkDisposition, SourceSyncTransition } from './types.js';
+/**
+ * The provenance kept for one retained source: its dependency, message spans, activity time, character count and
+ * content hash, never its text.
+ */
+export interface SourceSyncStoredDocument {
+    readonly dependency: SourceDependency;
+    readonly messages: readonly SourceSyncMessageSpan[];
+    readonly activityAt: number;
+    readonly characters: number;
+    readonly contentHash: string;
+}
+/** The host's limits for one connection, read under the owner fence in the transaction that uses them. */
+export interface SourceSyncAllowance {
+    readonly maximumConnectionDocuments: number;
+    readonly maximumConnectionHeldCharacters: number;
+    readonly additionalIndexedCharacters: number;
+}
+/**
+ * The host's table bindings. The store calls each one inside the owner fence, on the transaction adapter it is given
+ * and only there; a binding never calls a provider, embeds, generates, delivers over the network or refreshes a grant.
+ *
+ * @typeParam Prepared - The host's in-memory value for one document, such as its computed passages and vectors.
+ */
+export interface SourceSyncStorageBindings<Prepared> {
+    /**
+     * False for an account that is deleted or being deleted, disabled admission or a pending host purge: the store then
+     * claims, commits and reactivates nothing for the owner and answers no source state.
+     */
+    active(tx: StorageAdapter, scope: SourceOwnerScope): Promise<boolean>;
+    /** Absolute ceilings for this connection after subtracting unrelated sources; indexing is the remaining period balance. All writers take the owner fence first. */
+    allowance(tx: StorageAdapter, scope: SourceSyncScope): Promise<SourceSyncAllowance>;
+    /** Writes the document's content and the prepared value under this dependency, on the given transaction. */
+    write(tx: StorageAdapter, scope: SourceSyncScope, dependency: SourceDependency, document: SourceSyncDocument, prepared: Prepared): Promise<void>;
+    /** Charges committed sanitized characters to the owner's indexing allowance. */
+    chargeIndexed(tx: StorageAdapter, scope: SourceSyncScope, characters: number): Promise<void>;
+    /** Removes the host's source content in the affected scope: text, passages and vectors. */
+    purge(tx: StorageAdapter, scope: SourceOwnerScope, affected: SourceInvalidation): Promise<void>;
+    /** Removes every host row stored for these derived result ids, whole. */
+    purgeResults(tx: StorageAdapter, scope: SourceOwnerScope, ids: readonly string[]): Promise<void>;
+    /** Moves this connection's host rows to a new generation without changing their content, version or expiry. */
+    rebind(tx: StorageAdapter, scope: SourceSyncScope, generation: number): Promise<void>;
+}
+/** The store's table prefixes, clock and host bindings. */
+export interface SourceSyncStoreOptions<Prepared> {
+    /** Prefix of the synchronization tables, the one given to `sourceSyncSchema`; `agentos_source_sync` unless given. */
+    readonly tablePrefix?: string;
+    /** Prefix of the core derivation store's tables, the one given to `sourceDerivationSchema`; core's default unless given. */
+    readonly derivationPrefix?: string;
+    /** Current time as integer UTC epoch milliseconds; `Date.now` unless given. */
+    readonly clock?: () => number;
+    /** The host's table bindings. */
+    readonly bindings: SourceSyncStorageBindings<Prepared>;
+}
+/**
+ * A claimed lease with the owner fence ticket it was claimed under. A source change advances the owner's fence, so
+ * `applyResult` answers a handle with the new ticket: later calls use that handle.
+ */
+export interface SourceSyncHandle {
+    readonly ticket: SourceFenceTicket;
+    readonly lease: SourceSyncLease;
+}
+/**
+ * The transitions a host control applies: connecting, a ready or lost grant, pause, resume, a use or policy change,
+ * and disconnecting.
+ */
+export type SourceSyncControl = Extract<SourceSyncTransition, {
+    type: 'connect_started' | 'grant_ready' | 'pause' | 'resume' | 'use_changed' | 'policy_changed' | 'grant_lost' | 'disconnect';
+}>;
+/**
+ * A control's durable, content-free record of the work it still owes: purging the connection, pruning it to its
+ * limits, excluding one source, or completing a rebind or a reset. No claim succeeds and the owner is not reactivated
+ * while one is set; `recoverControl` completes it.
+ */
+export interface SourceSyncBarrier {
+    readonly token: string;
+    readonly action: 'rebind' | 'purge' | 'prune' | 'exclude' | 'reset';
+    readonly sourceId: string | null;
+}
+/**
+ * A connection's metadata for authenticated host controls: state, policy, open checkpoint, barrier and last
+ * reconciliation time.
+ */
+export interface SourceSyncSnapshot {
+    readonly state: SourceSyncState;
+    readonly policy: SourceSyncPolicy;
+    readonly checkpoint: SourceSyncCheckpoint | null;
+    readonly barrier: SourceSyncBarrier | null;
+    readonly lastReconcileAt: number | null;
+}
+/** What applying one read result answers: the handle to use next and the work's disposition. */
+export interface SourceSyncApplication {
+    readonly handle: SourceSyncHandle;
+    readonly disposition: SourceSyncWorkDisposition;
+}
+/**
+ * Durable synchronization state for account sources on PostgreSQL. Every change to an owner's content runs under
+ * that owner's fence (`fence`), and a change made with a handle checks its lease, generation and host liveness in
+ * the same transaction. Applying a source purges its old copy and every derived result that depends on it before the
+ * replacement is written. Provider reads, embedding and model calls stay outside the store. The constructor runs no
+ * DDL: the host's migration runs `sourceSyncSchema` and core's `sourceDerivationSchema` first.
+ *
+ * @typeParam Prepared - The host's in-memory value for one document, passed through to its `write` binding.
+ */
+export declare class SqlAccountSourceSyncStore<Prepared = unknown> {
+    private readonly db;
+    private readonly options;
+    private readonly t;
+    private readonly clock;
+    /**
+     * The owner fence. The same instance commits and delivers derived results and fences account deletion. Host code
+     * never activates an owner through it with a callback that answers true unconditionally.
+     */
+    readonly fence: SqlSourceDerivationStore;
+    /**
+     * @param db - A PostgreSQL adapter with transactions.
+     * @param options - Table prefixes, clock and the host's bindings.
+     * @throws {Error} `source_sync_requires_postgres` for another kind of adapter or one without transactions, and
+     *   `invalid_source_sync_prefix` or core's `invalid_derivation_table_prefix` for a malformed prefix.
+     */
+    constructor(db: StorageAdapter, options: SourceSyncStoreOptions<Prepared>);
+    private now;
+    private fenceOn;
+    private row;
+    private save;
+    private clearCycle;
+    private activate;
+    /**
+     * Creates the connection in `not_connected` and activates its owner when the host's `active` binding allows it and
+     * no barrier of the owner is pending; otherwise nothing changes. An existing connection is kept as it is.
+     *
+     * @throws {Error} `invalid_source_sync_policy` for an invalid policy and `invalid_source_sync_state` for an
+     *   invalid scope.
+     */
+    create(scope: SourceSyncScope, policy: SourceSyncPolicy): Promise<void>;
+    /** Metadata for authenticated host controls only; no content-delivery authorization. */
+    snapshot(scope: SourceSyncScope): Promise<SourceSyncSnapshot | null>;
+    /** Operator scheduler only. The claim performs fresh host and owner checks. */
+    scopes(after?: SourceSyncScope | null, limit?: number): Promise<readonly SourceSyncScope[]>;
+    /**
+     * Connections whose next sync time has come, with no barrier and no live lease, earliest first.
+     *
+     * @param limit - At most this many, an integer from 1 to 1,000.
+     * @throws {Error} `invalid_sync_batch` for another limit.
+     */
+    due(limit?: number): Promise<readonly SourceSyncScope[]>;
+    /**
+     * Claims the connection's lease for one sync. The owner must be active, the host's `active` binding must allow it,
+     * no barrier or live lease may be set and the connection must be due for `trigger`; a manual claim records the
+     * request.
+     *
+     * @returns The handle, or null.
+     */
+    claim(scope: SourceSyncScope, trigger: SourceSyncTrigger): Promise<SourceSyncHandle | null>;
+    private checked;
+    private withHandle;
+    /**
+     * Extends a live lease by the policy's `leaseMs`.
+     *
+     * @returns The renewed handle, or null when the lease, its generation or the owner fence has moved on.
+     */
+    renew(h: SourceSyncHandle): Promise<SourceSyncHandle | null>;
+    /**
+     * Opens a cycle's durable checkpoint and drops the previous cycle's work, or answers the checkpoint already open.
+     * An incremental cycle starts from the committed cursor. With `replaceExpiredHistory`, a `recovery` cycle replaces
+     * the open one. The cutoff defaults to the connection's last change.
+     *
+     * @returns The checkpoint, or null for a stale handle or an incremental cycle from another cursor.
+     * @throws {SourceSyncFault} `invalid_response` for a cutoff in the future or a replacement that is not `recovery`.
+     */
+    openCycle(h: SourceSyncHandle, input: Pick<SourceSyncCycleInput, 'mode' | 'fromCursor'> & {
+        readonly cutoff?: number;
+        readonly cycleId?: string;
+    }, replaceExpiredHistory?: boolean): Promise<SourceSyncCheckpoint | null>;
+    /**
+     * Records one page: the next checkpoint and its queued work, in one transaction. The same page sent again right
+     * after it was recorded answers the same checkpoint; any other stale revision answers null.
+     *
+     * @throws {SourceSyncFault} `invalid_response` for an id longer than 512 characters, and the page rules'
+     *   `invalid_source_sync_page` for a page the checkpoint does not admit.
+     */
+    page(h: SourceSyncHandle, expected: SourceSyncCheckpoint, page: SourceSyncPage): Promise<SourceSyncCheckpoint | null>;
+    private putWork;
+    /** Null id takes the first due item. Increment before external work; a crash leaves it pending. */
+    takeWork(h: SourceSyncHandle, id?: string | null): Promise<SourceSyncWork | null>;
+    private currentWork;
+    private normalized;
+    private documentRows;
+    /** Internal provenance enumeration. Never expose this as a browser retrieval response. */
+    documents(scope: SourceSyncScope): Promise<readonly SourceSyncStoredDocument[]>;
+    /** Whether the connection holds an exclusion for this source id. */
+    isExcluded(scope: SourceSyncScope, id: string): Promise<boolean>;
+    private choose;
+    /**
+     * Applies one read result for a work item taken in this cycle, under a live lease and the owner fence. A retry
+     * keeps the work unresolved. Any other result first purges the source's old copy and every result derived from it;
+     * a document then replaces it in the same transaction (host write, indexing charge and provenance) when it is not
+     * excluded and fits the retained and indexing limits, evicting this connection's older sources the limits no
+     * longer admit. A document that is excluded or does not fit is recorded as a skip with its reason.
+     *
+     * @param prepared - The host's prepared value for a document result; null for any other result.
+     * @returns The disposition and the handle later calls use, whose ticket reflects the purge; null for a stale
+     *   handle or work item.
+     * @throws {SourceSyncFault} `invalid_response` for a result that does not match its work item or is malformed.
+     * @throws {Error} `invalid_source_allowance` when the host's allowance is not made of nonnegative safe integers.
+     */
+    applyResult(h: SourceSyncHandle, work: SourceSyncWork, result: SourceSyncReadResult, prepared: Prepared | null): Promise<SourceSyncApplication | null>;
+    private summary;
+    /**
+     * Records the cycle's progress, counted from its stored work and the retained documents.
+     *
+     * @returns The state, or null for a stale handle.
+     */
+    progress(h: SourceSyncHandle): Promise<SourceSyncState | null>;
+    /**
+     * Commits the cycle's target cursor once every work item is terminal, counting from the stored work and never from
+     * a caller's numbers, then clears the cycle, releases the lease and schedules the next poll.
+     *
+     * @returns The connected state, or null while work is unresolved or for a stale handle.
+     */
+    finish(h: SourceSyncHandle, expected: SourceSyncCheckpoint): Promise<SourceSyncState | null>;
+    /**
+     * Releases the lease, recording a deferral or a fixed failure when one is given; the cycle's checkpoint and work
+     * stay for the next claim.
+     *
+     * @returns Whether the lease was released.
+     */
+    release(h: SourceSyncHandle, event?: Extract<SourceSyncTransition, {
+        type: 'sync_deferred' | 'sync_failed';
+    }> | null): Promise<boolean>;
+    /**
+     * The current state of each of the derivation's retained sources, read in the given transaction for the fence's
+     * commit and delivery checks; not an authorization answer of its own. An owner the host's `active` binding refuses
+     * has no sources, and a connection with a barrier or pending revalidation reads as disconnected.
+     */
+    readCurrent(tx: StorageAdapter, derivation: SourceDerivation): Promise<readonly SourceDependencyState[]>;
+    /** Removes the host's content and this store's provenance in the affected scope; the fence calls it inside an invalidation. */
+    purgeSources(tx: StorageAdapter, scope: SourceOwnerScope, affected: SourceInvalidation): Promise<void>;
+    /**
+     * Applies a host control: completes any earlier barrier, then blocks the owner, moves the connection, records a
+     * barrier and drops the open cycle in one transaction, and completes the barrier before reactivating the owner.
+     * Connecting, grant loss and disconnecting purge the connection and its exclusions; a policy change, which takes
+     * the new policy, prunes retained sources to it and shortens their expiry to its window; the other controls rebind
+     * content to the new generation without changing its version or expiry.
+     *
+     * @returns The snapshot after the barrier is complete.
+     * @throws {Error} `source_policy_control_required` unless a policy comes exactly with `policy_changed`, and
+     *   `stale_source_sync` when the host's `active` binding refuses anything but disconnecting or a barrier is still set.
+     */
+    control(scope: SourceSyncScope, event: SourceSyncControl, policy?: SourceSyncPolicy): Promise<SourceSyncSnapshot | null>;
+    private rebind;
+    /** Called by the lifecycle worker even when a connection is paused or the owner is blocked. */
+    recoverControl(scope: SourceSyncScope): Promise<void>;
+    /**
+     * Removes one source and every result derived from it, and keeps a content-free exclusion so later syncs skip it.
+     * The connection moves to a new generation, its cursor is cleared and its open cycle is dropped.
+     *
+     * @throws {SourceSyncFault} `invalid_response` for an empty id or one longer than 512 characters.
+     */
+    exclude(scope: SourceSyncScope, sourceId: string): Promise<void>;
+    /**
+     * Clears the connection's exclusions. The connection moves to a new generation, its cursor is cleared and its open
+     * cycle is dropped.
+     */
+    resetExclusions(scope: SourceSyncScope): Promise<void>;
+    /**
+     * Removes retained sources whose expiry has passed, with every result derived from them, also while the connection
+     * is paused, then expires the owner's derived results. Sources are removed only while the owner's fence is active;
+     * reads refuse an expired source regardless.
+     *
+     * @param limit - At most this many sources, an integer from 1 to 1,000.
+     * @returns How many sources were removed.
+     * @throws {Error} `invalid_sync_batch` for another limit.
+     */
+    expire(scope: SourceSyncScope, limit?: number): Promise<number>;
+}
+//# sourceMappingURL=SqlAccountSourceSyncStore.d.ts.map

package/dist/sync/SqlAccountSourceSyncStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqlAccountSourceSyncStore.d.ts","sourceRoot":"","sources":["../../src/sync/SqlAccountSourceSyncStore.ts"],"names":[],"mappings":"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"}