@syncular/server 0.1.3 → 0.2.1

package/dist/prune.d.ts

@@ -1,44 +1,29 @@
 /**
- * @syncular/server - Pruning utilities
+ * Commit-log pruning (SPEC.md §4.6) — normative retention floors.
  *
- * Pruning strategy (initial):
- * - Track per-client cursors in `sync_client_cursors`
- * - Consider a client "active" if it has pulled within `activeWindowMs`
- * - Compute watermark = min(cursor) across active clients (ignoring cursor < 0)
- * - Delete commits with commit_seq <= watermark (cascade deletes changes)
- *
- * Clients behind pruned history will be forced to bootstrap.
+ * The horizon never advances past `min(active-client cursors)` (clients
+ * whose cursor record was touched within the active window), except that
+ * commits older than the age-force limit may be pruned regardless; at
+ * least the newest `minRetainedCommits` commits are always retained.
  */
-import type { Kysely } from 'kysely';
-import type { SyncCoreDb } from './schema';
-export interface PruneOptions {
-    /** Clients with updated_at older than this are ignored for watermark. Default: 14 days. */
-    activeWindowMs?: number;
-    /**
-     * Time-based retention safety cap.
-     *
-     * The server prunes commits older than this age even if watermark pruning
-     * is stuck (e.g. a client never advances).
-     * Default: 30 days.
-     */
-    fallbackMaxAgeMs?: number;
-    /** Soft cap: keep at least this many newest commits even if watermark is high. Default: 1000. */
-    keepNewestCommits?: number;
+import { type SyncularServerEvents } from './events.js';
+import type { ServerStorage } from './storage.js';
+export interface RetentionPolicy {
+    /** Active window for laggard cursors (default 14 days). */
+    readonly activeWindowMs: number;
+    /** Force-advance past commits older than this (default 30 days). */
+    readonly ageForceMs: number;
+    /** Always retain at least this many newest commits (default 1000). */
+    readonly minRetainedCommits: number;
 }
-export interface PartitionPrunePreview {
-    partitionId: string;
-    watermarkCommitSeq: number;
-    commitsToDelete: number;
+export declare const DEFAULT_RETENTION: RetentionPolicy;
+export interface PruneOptions {
+    readonly storage: ServerStorage;
+    readonly partition: string;
+    readonly nowMs: number;
+    readonly retention?: Partial<RetentionPolicy>;
+    /** Optional structured-events sink (`prune.completed`). */
+    readonly events?: SyncularServerEvents;
 }
-export declare function computePruneWatermarkCommitSeq<DB extends SyncCoreDb>(db: Kysely<DB>, options?: PruneOptions, partitionId?: string): Promise<number>;
-export declare function pruneSync<DB extends SyncCoreDb>(db: Kysely<DB>, args: {
-    partitionId?: string;
-    watermarkCommitSeq: number;
-    keepNewestCommits?: number;
-}): Promise<number>;
-export declare function previewPruneSync<DB extends SyncCoreDb>(db: Kysely<DB>, options?: PruneOptions): Promise<PartitionPrunePreview[]>;
-export declare function maybePruneSync<DB extends SyncCoreDb>(db: Kysely<DB>, args: {
-    minIntervalMs: number;
-    options?: PruneOptions;
-}): Promise<number>;
-//# sourceMappingURL=prune.d.ts.map
+/** Advance the horizon per §4.6 and delete commits at or below it. */
+export declare function pruneCommitLog(options: PruneOptions): Promise<number>;

package/dist/prune.js

@@ -1,152 +1,50 @@
 /**
- * @syncular/server - Pruning utilities
+ * Commit-log pruning (SPEC.md §4.6) — normative retention floors.
  *
- * Pruning strategy (initial):
- * - Track per-client cursors in `sync_client_cursors`
- * - Consider a client "active" if it has pulled within `activeWindowMs`
- * - Compute watermark = min(cursor) across active clients (ignoring cursor < 0)
- * - Delete commits with commit_seq <= watermark (cascade deletes changes)
- *
- * Clients behind pruned history will be forced to bootstrap.
+ * The horizon never advances past `min(active-client cursors)` (clients
+ * whose cursor record was touched within the active window), except that
+ * commits older than the age-force limit may be pruned regardless; at
+ * least the newest `minRetainedCommits` commits are always retained.
  */
-import { sql } from 'kysely';
-import { coerceNumber } from './dialect/helpers.js';
-async function readPrunePartitionIds(db) {
-    const res = await sql `
-    SELECT DISTINCT partition_id
-    FROM sync_commits
-    ORDER BY partition_id ASC
-  `.execute(db);
-    return res.rows
-        .map((row) => row.partition_id)
-        .filter((partitionId) => typeof partitionId === 'string' && partitionId);
-}
-async function computePruneUpToCommitSeq(db, partitionId, watermarkCommitSeq, keepNewestCommits) {
-    if (watermarkCommitSeq <= 0)
-        return 0;
-    const syncDb = db;
-    const commitsQ = syncDb.selectFrom('sync_commits');
-    const maxRow = await commitsQ
-        .select(({ fn }) => [fn.max('commit_seq').as('maxSeq')])
-        .where('partition_id', '=', partitionId)
-        .executeTakeFirst();
-    const maxSeq = coerceNumber(maxRow?.maxSeq) ?? 0;
-    const minKept = Math.max(0, maxSeq - keepNewestCommits);
-    return Math.min(watermarkCommitSeq, minKept);
-}
-export async function computePruneWatermarkCommitSeq(db, options = {}, partitionId = 'default') {
-    const syncDb = db;
-    const activeWindowMs = options.activeWindowMs ?? 14 * 24 * 60 * 60 * 1000;
-    const cutoffIso = new Date(Date.now() - activeWindowMs).toISOString();
-    const cursorsQ = syncDb.selectFrom('sync_client_cursors');
-    const row = await cursorsQ
-        .select(({ fn }) => [fn.min('cursor').as('minCursor')])
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `updated_at >= ${cutoffIso}`)
-        .where(sql `cursor >= ${0}`)
-        .executeTakeFirst();
-    const minCursor = coerceNumber(row?.minCursor) ?? 0;
-    const fallbackMaxAgeMs = options.fallbackMaxAgeMs ?? 30 * 24 * 60 * 60 * 1000;
-    if (fallbackMaxAgeMs <= 0)
-        return minCursor;
-    const ageCutoffIso = new Date(Date.now() - fallbackMaxAgeMs).toISOString();
-    const commitsQ = syncDb.selectFrom('sync_commits');
-    const ageRow = await commitsQ
-        .select(({ fn }) => [fn.max('commit_seq').as('maxSeq')])
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `created_at < ${ageCutoffIso}`)
-        .executeTakeFirst();
-    const ageSeq = coerceNumber(ageRow?.maxSeq) ?? 0;
-    return Math.max(minCursor, ageSeq);
-}
-export async function pruneSync(db, args) {
-    if (args.watermarkCommitSeq <= 0)
-        return 0;
-    const syncDb = db;
-    const partitionId = args.partitionId ?? 'default';
-    const keepNewestCommits = args.keepNewestCommits ?? 1000;
-    const pruneUpTo = await computePruneUpToCommitSeq(db, partitionId, args.watermarkCommitSeq, keepNewestCommits);
-    if (pruneUpTo <= 0)
-        return 0;
-    // Delete dependent rows explicitly to be robust across dialects and older
-    // schemas that may not have FK cascade enabled.
-    await syncDb.deleteFrom('sync_scope_commits')
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `commit_seq <= ${pruneUpTo}`)
-        .executeTakeFirst();
-    await syncDb.deleteFrom('sync_table_commits')
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `commit_seq <= ${pruneUpTo}`)
-        .executeTakeFirst();
-    await syncDb.deleteFrom('sync_changes')
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `commit_seq <= ${pruneUpTo}`)
-        .executeTakeFirst();
-    const res = await syncDb.deleteFrom('sync_commits')
-        .where(sql `partition_id = ${partitionId}`)
-        .where(sql `commit_seq <= ${pruneUpTo}`)
-        .executeTakeFirst();
-    return Number(res?.numDeletedRows ?? 0);
-}
-export async function previewPruneSync(db, options = {}) {
-    const syncDb = db;
-    const partitionIds = await readPrunePartitionIds(db);
-    const previews = [];
-    for (const partitionId of partitionIds) {
-        const watermarkCommitSeq = await computePruneWatermarkCommitSeq(db, options, partitionId);
-        const pruneUpToCommitSeq = await computePruneUpToCommitSeq(db, partitionId, watermarkCommitSeq, options.keepNewestCommits ?? 1000);
-        const commitsQ = syncDb.selectFrom('sync_commits');
-        const countRow = await commitsQ
-            .select(({ fn }) => [fn.countAll().as('count')])
-            .where('partition_id', '=', partitionId)
-            .where('commit_seq', '<=', pruneUpToCommitSeq)
-            .executeTakeFirst();
-        previews.push({
-            partitionId,
-            watermarkCommitSeq,
-            commitsToDelete: coerceNumber(countRow?.count) ?? 0,
+import { emitEvent } from './events.js';
+export const DEFAULT_RETENTION = {
+    activeWindowMs: 14 * 24 * 60 * 60 * 1000,
+    ageForceMs: 30 * 24 * 60 * 60 * 1000,
+    minRetainedCommits: 1000,
+};
+/** Advance the horizon per §4.6 and delete commits at or below it. */
+export async function pruneCommitLog(options) {
+    const { storage, partition, nowMs } = options;
+    const policy = { ...DEFAULT_RETENTION, ...options.retention };
+    const maxSeq = await storage.getMaxCommitSeq(partition);
+    const cursors = await storage.listClientCursors(partition);
+    const activeCursors = cursors
+        .filter((c) => c.updatedAtMs >= nowMs - policy.activeWindowMs)
+        .map((c) => c.cursor);
+    const cursorFloor = activeCursors.length > 0
+        ? Math.min(...activeCursors)
+        : Number.MAX_SAFE_INTEGER;
+    const forcedSeq = await storage.getCommitSeqBefore(partition, nowMs - policy.ageForceMs);
+    const retainFloor = maxSeq - policy.minRetainedCommits;
+    const target = Math.min(Math.max(cursorFloor, forcedSeq), retainFloor);
+    const current = await storage.getHorizonSeq(partition);
+    const horizon = Math.max(current, Math.max(0, target));
+    let removedCommits = 0;
+    if (horizon > current) {
+        await storage.setHorizonSeq(partition, horizon);
+        removedCommits = await storage.pruneCommitsThrough(partition, horizon);
+    }
+    const events = options.events;
+    if (events !== undefined) {
+        emitEvent(events, {
+            type: 'prune.completed',
+            atMs: nowMs,
+            partition,
+            previousHorizonSeq: current,
+            horizonSeq: horizon,
+            advanced: horizon > current,
+            removedCommits,
         });
     }
-    return previews;
-}
-const pruneStateByDb = new WeakMap();
-function getPruneState(db) {
-    const existing = pruneStateByDb.get(db);
-    if (existing)
-        return existing;
-    const created = {
-        lastPruneAtMs: 0,
-        pruneInFlight: null,
-    };
-    pruneStateByDb.set(db, created);
-    return created;
-}
-export async function maybePruneSync(db, args) {
-    const state = getPruneState(db);
-    const now = Date.now();
-    if (now - state.lastPruneAtMs < args.minIntervalMs)
-        return 0;
-    if (state.pruneInFlight)
-        return state.pruneInFlight;
-    state.pruneInFlight = (async () => {
-        try {
-            const partitionIds = await readPrunePartitionIds(db);
-            let deleted = 0;
-            for (const partitionId of partitionIds) {
-                const watermark = await computePruneWatermarkCommitSeq(db, args.options, partitionId);
-                deleted += await pruneSync(db, {
-                    partitionId,
-                    watermarkCommitSeq: watermark,
-                    keepNewestCommits: args.options?.keepNewestCommits,
-                });
-            }
-            state.lastPruneAtMs = Date.now();
-            return deleted;
-        }
-        finally {
-            state.pruneInFlight = null;
-        }
-    })();
-    return state.pruneInFlight;
+    return horizon;
 }
-//# sourceMappingURL=prune.js.map

package/dist/pull.d.ts

@@ -1,69 +1,44 @@
-import { type ScopeValues, type SyncPullRequest, type SyncPullResponse } from '@syncular/core';
-import type { Kysely } from 'kysely';
-import type { ServerSyncDialect } from './dialect/types';
-import { type ServerHandlerCollection } from './handlers/collection';
-import type { SyncServerAuth } from './handlers/types';
-import { type SyncServerPullPlugin } from './plugins/types';
-import type { SyncCoreDb } from './schema';
-import type { SnapshotChunkStorage } from './snapshot-chunks/types';
-import { type ScopeCacheBackend } from './subscriptions/cache';
-interface PullBootstrapTimings {
-    snapshotQueryMs: number;
-    binaryEncodeMs: number;
-    chunkCacheLookupMs: number;
-    artifactCacheLookupMs: number;
-    chunkGzipMs: number;
-    chunkHashMs: number;
-    chunkPersistMs: number;
+/**
+ * Pull: incremental commit delivery, cursors, bootstrap segments
+ * (SPEC.md §4, §5).
+ */
+import { type PullHeaderFrame, type ResponseFrame, type ScopeMap, type SubscriptionFrame } from '@syncular/core';
+import type { SyncRequestContext } from './context.js';
+import type { PullSegmentSummary } from './events.js';
+import type { CompiledSchema, CompiledTable } from './schema.js';
+/** §4.2 accept bitmask. */
+export declare const ACCEPT_INLINE_ROWS: number;
+export declare const ACCEPT_EXTERNAL_ROWS: number;
+export declare const ACCEPT_SQLITE: number;
+export declare const ACCEPT_SIGNED_URLS: number;
+export interface PullLimits {
+    readonly limitCommits: number;
+    readonly limitSnapshotRows: number;
+    readonly maxSnapshotPages: number;
+    readonly accept: number;
 }
-export interface PullResult {
-    response: SyncPullResponse;
-    /**
-     * Effective scopes for all active subscriptions (for cursor tracking).
-     * Maps subscription ID to effective scopes.
-     */
-    effectiveScopes: ScopeValues;
-    /** Minimum nextCursor across active subscriptions (for pruning cursor tracking). */
-    clientCursor: number;
-    /** Internal bootstrap timing breakdown used for benchmark-gated diagnostics. */
-    bootstrapTimings?: PullBootstrapTimings;
+/** §4.2 defaults and silent clamps (the v1 values). */
+export declare function clampPullLimits(header: PullHeaderFrame): PullLimits;
+export interface SubscriptionPlan {
+    readonly frame: SubscriptionFrame;
+    readonly table: CompiledTable;
+    readonly status: 'active' | 'revoked';
+    readonly effective: ScopeMap;
 }
-export declare function pull<DB extends SyncCoreDb, Auth extends SyncServerAuth>(args: {
-    db: Kysely<DB>;
-    dialect: ServerSyncDialect;
-    handlers: ServerHandlerCollection<DB, Auth>;
-    auth: Auth;
-    request: SyncPullRequest;
-    /**
-     * Optional snapshot chunk storage adapter.
-     * When provided, stores chunk bodies in external storage (S3, etc.)
-     * instead of inline in the database.
-     */
-    chunkStorage?: SnapshotChunkStorage;
-    /**
-     * Optional shared scope cache backend.
-     * Request-local memoization is always applied, even with custom backends.
-     * Defaults to process-local memory cache.
-     */
-    scopeCache?: ScopeCacheBackend;
-    /**
-     * Gzip compression level for generated snapshot chunks. The protocol remains
-     * gzip-only; this tunes CPU/size tradeoffs for deployments that know their
-     * network constraints.
-     *
-     * Default: 1, range: 0-9.
-     */
-    snapshotChunkGzipLevel?: number;
-    /**
-     * Schema/cache semantic version included in generated snapshot chunk cache
-     * keys. Changing this value invalidates cached bootstrap chunks without
-     * requiring table data to change.
-     */
-    snapshotChunkCacheSchemaVersion?: number | string | null;
-    /**
-     * Optional server plugins for protocol-level pull transforms.
-     */
-    plugins?: readonly SyncServerPullPlugin<DB, Auth>[];
-}): Promise<PullResult>;
-export {};
-//# sourceMappingURL=pull.d.ts.map
+export interface SubscriptionResult {
+    readonly nextCursor: number;
+    readonly active: boolean;
+}
+/**
+ * Mutable per-section collector for the `pull.served` event. Only created
+ * when an events sink is configured — with `trace` undefined the pull path
+ * does zero extra work (`trace?.…` short-circuits argument evaluation).
+ */
+export interface PullSectionTrace {
+    readonly segments: PullSegmentSummary[];
+}
+/**
+ * Produce the `SUB_START … SUB_END` section for one subscription (§1.6),
+ * returning the cursor recorded for the retention watermark (§4.5).
+ */
+export declare function subscriptionSection(ctx: SyncRequestContext, schema: CompiledSchema, limits: PullLimits, plan: SubscriptionPlan, maxSeq: number, horizonSeq: number, trace?: PullSectionTrace): AsyncGenerator<ResponseFrame, SubscriptionResult>;