@knowledge-medium/agent-cli 0.1.0

package/dist/kernel-types/src/data/internals/kernelQueries.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Kernel queries — raw SQL constants + `defineQuery` facet contributions
+ * for outside-tx reads (UI hooks, search, alias lookup, type
+ * filters, tree walks).
+ *
+ * Surface: SQL constants up top (used by tests, kept stable for plugin
+ * authors who want the same queries without going through the facet),
+ * then `KERNEL_QUERIES` (Phase 4 chunk B) — the bundle that the kernel
+ * data extension and the Repo's construction-time registration consume.
+ * Each `defineQuery` wraps a SQL constant and re-declares the same
+ * dependencies the legacy `repo.X(id)` factories on `Repo` did.
+ *
+ * Property-shape note: the new `BlockData.properties` is flat
+ * `{name: encodedValue}`, NOT the legacy `{name: {name, type, value}}`
+ * record. So `json_extract(properties_json, '$.alias')` returns the
+ * encoded value directly (string[] for alias, string for type, etc.).
+ * The legacy `'$.alias.value'` paths don't exist anymore.
+ */
+import { type AnyQuery, type BlockData, type QueryCtx, type ResolvedTypedBlockQuery } from '@/data/api';
+export declare const SELECT_BLOCK_BY_ID_SQL: string;
+/** Type filter — array membership via the trigger-maintained block_types index. */
+export declare const SELECT_BLOCKS_BY_TYPE_SQL: string;
+/** Content search — case-insensitive substring match. */
+export declare const SELECT_BLOCKS_BY_CONTENT_SQL: string;
+/** Recent non-empty blocks in a workspace, used by empty-query pickers. */
+export declare const SELECT_RECENT_BLOCKS_SQL: string;
+/** Distinct alias values in a workspace, optionally substring-filtered.
+ *  Reads `block_aliases` (the trigger-maintained side index in
+ *  clientSchema.ts) instead of scanning `json_each(properties_json,
+ *  '$.alias')` per query. The case-insensitive filter rides
+ *  `idx_block_aliases_ws_alias_lower`; the case-preserving GROUP BY
+ *  collapses duplicate aliases that appear on multiple blocks. The
+ *  `MIN(b.created_at)` ordering keeps the historical "oldest-first"
+ *  sort even though the index itself doesn't carry timestamps. */
+export declare const SELECT_ALIASES_IN_WORKSPACE_SQL = "\n  SELECT ba.alias AS alias\n  FROM block_aliases ba\n  JOIN blocks b ON b.id = ba.block_id\n  WHERE ba.workspace_id = ?\n    AND b.deleted = 0\n    AND (? = '' OR ba.alias_lower LIKE '%' || LOWER(?) || '%')\n  GROUP BY ba.alias\n  ORDER BY\n    MIN(CASE\n      WHEN ba.alias_lower = LOWER(?) THEN 0\n      WHEN ba.alias_lower LIKE LOWER(?) || '%' THEN 1\n      ELSE 2\n    END),\n    MIN(b.created_at),\n    ba.alias\n";
+/** Single-block lookup by exact alias (used by createOrRestore wrappers
+ *  and call-site alias jumps). Returns the oldest match (deterministic
+ *  tie-break on workspaces with two blocks accidentally claiming the
+ *  same alias). Lookups go through `idx_block_aliases_ws_alias`; the
+ *  blocks JOIN reads the row by primary key. */
+export declare const SELECT_BLOCK_BY_ALIAS_IN_WORKSPACE_SQL: string;
+/** Variant of `SELECT_BLOCK_BY_ALIAS_IN_WORKSPACE_SQL` that ignores
+ *  one specific block. Same plan as above with an extra `blocks.id !=
+ *  ?` predicate. Used exclusively by the same-tx collision-detection
+ *  path: when a row writes its own alias inside the user's tx, the
+ *  trigger-maintained index already contains that row by the time the
+ *  processor runs, so a plain "oldest claimant of alias X" would
+ *  return the row itself when it happens to be the oldest claimant —
+ *  silently missing collisions where the actual conflicting claimant
+ *  is younger. Excluding the attempting row fixes that. */
+export declare const SELECT_BLOCK_BY_ALIAS_IN_WORKSPACE_EXCLUDING_SQL: string;
+/** Alias substring match used by alias-search surfaces; one row per
+ *  (alias, block) pair. Same index plan as the distinct-aliases query
+ *  above: filter on alias_lower, JOIN blocks for content + ordering. */
+export declare const SELECT_ALIAS_MATCHES_IN_WORKSPACE_SQL = "\n  SELECT\n    ba.alias AS alias,\n    b.id AS blockId,\n    b.content AS content\n  FROM block_aliases ba\n  JOIN blocks b ON b.id = ba.block_id\n  WHERE ba.workspace_id = ?\n    AND b.deleted = 0\n    AND (? = '' OR ba.alias_lower LIKE '%' || LOWER(?) || '%')\n  ORDER BY\n    CASE\n      WHEN ba.alias_lower = LOWER(?) THEN 0\n      WHEN ba.alias_lower LIKE LOWER(?) || '%' THEN 1\n      ELSE 2\n    END,\n    b.created_at,\n    ba.alias\n  LIMIT ?\n";
+/** First child of `parentId` whose content matches exactly. Tree-shape:
+ *  joins on `blocks.parent_id`, ordered by `(order_key, id)` so the
+ *  "first" tie-breaks deterministically. */
+export declare const SELECT_FIRST_CHILD_BY_CONTENT_SQL: string;
+export interface AliasMatch {
+    alias: string;
+    blockId: string;
+    content: string;
+}
+/** Subtree rooted at `id`, includeRoot=true (spec §11). Identity-stable
+ *  via the dispatcher's handle-store key. Dep declaration mirrors the
+ *  legacy `repo.subtree(id)` factory in `repo.ts`. */
+export declare const subtreeQuery: import("@/data/api").Query<{
+    id: string;
+}, BlockData[]>;
+/** Ancestor chain (excludes `id` itself). */
+export declare const ancestorsQuery: import("@/data/api").Query<{
+    id: string;
+}, BlockData[]>;
+interface ManyAncestorsEntry {
+    startId: string;
+    ancestors: BlockData[];
+}
+/** Batched ancestor walk. Returns one entry per input id, in input
+ *  order, with the leaf-to-root chain (depth-ascending) — same
+ *  ordering as the single-id `core.ancestors` query.
+ *
+ *  Use over N `core.ancestors` calls when a UI needs ancestors for
+ *  many ids known up front (e.g. a backlinks panel rendering N
+ *  source blocks each with breadcrumbs). One round-trip vs. N gives
+ *  a meaningful cold-start win when the SQLite connection is
+ *  contended. Empty entries are returned for ids whose row doesn't
+ *  exist or is soft-deleted, so consumers can map 1:1 over the input
+ *  list without nullable lookups. */
+export declare const manyAncestorsQuery: import("@/data/api").Query<{
+    ids: readonly string[];
+}, ManyAncestorsEntry[]>;
+/** Direct children of `id`, ordered `(order_key, id)`. */
+export declare const childrenQuery: import("@/data/api").Query<{
+    id: string;
+}, BlockData[]>;
+/** Child-id list of `id` (lean shape). With `hydrate: true`, also runs
+ *  the full row SELECT and primes the cache — the consumer-facing
+ *  variant the React hooks use to avoid N+1 row loads on mount. */
+export declare const childIdsQuery: import("@/data/api").Query<{
+    id: string;
+    hydrate?: boolean;
+}, string[]>;
+/** Live blocks in `workspaceId` whose `type` property equals `type`.
+ *  Membership reactivity rides the `typedBlocks.type` channel — fired
+ *  by the kernel invalidation rule when a block's `block_types` row for
+ *  `(workspaceId, type)` is inserted/removed (creation, restore,
+ *  type-add/remove, soft-delete). Per-row deps from `hydrateBlocks`
+ *  cover edits to currently-matched rows. */
+export declare const byTypeQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    type: string;
+}, BlockData[]>;
+/** Resolve a typed block query against the given context. Used both
+ *  by `typedBlocksQuery` and by thin wrappers like `backlinksForBlockQuery`
+ *  that compose typed-query semantics — sharing this resolver keeps
+ *  the dep declarations and SQL in one place. */
+export declare const resolveTypedBlocks: (query: ResolvedTypedBlockQuery, ctx: QueryCtx) => Promise<BlockData[]>;
+/** Id projection for typed queries. Same typed-query semantics and
+ *  membership invalidation as `resolveTypedBlocks`, but it intentionally
+ *  avoids hydrating result rows, so content-only edits to current
+ *  members do not invalidate collection consumers. */
+export declare const resolveTypedBlockIds: (query: ResolvedTypedBlockQuery, ctx: QueryCtx) => Promise<string[]>;
+/** SQLite-backed typed block query. Repo.queryBlocks / subscribeBlocks
+ *  default workspaceId before dispatching here; direct query callers
+ *  should pass workspaceId explicitly.
+ *
+ *  Reactivity (spec §9.2 + §9.4): each filter dimension contributes its
+ *  own narrow dep so the handle re-resolves only when something that
+ *  could flip membership actually changes:
+ *
+ *    - per `type` in `types`     → `typedBlocks.type` channel
+ *    - per name in `where`        → `typedBlocks.property` channel
+ *    - `referencedBy.id` (no field) → `typedBlocks.reference` channel
+ *    - `referencedBy.id + sourceField` → `typedBlocks.referenceField` channel
+ *    - per name in any `match`/`exclude` predicate's `where` → `typedBlocks.property`
+ *    - per `referencedBy` in any `match`/`exclude` predicate → reference channels
+ *    - any ancestor-scope predicate → row deps on every walked ancestor id
+ *    - no filter at all           → `typedBlocks.live` channel
+ *
+ *  Per-row deps from `hydrateBlocks` cover edits to rows already in the
+ *  result. The old `{kind:'workspace', workspaceId}` dep was too coarse
+ *  — UiState focus writes (and unrelated content edits) re-fired it
+ *  needlessly. */
+export declare const typedBlocksQuery: import("@/data/api").Query<import("@/data/api").TypedBlockQuery, BlockData[]>;
+export declare const typedBlockIdsQuery: import("@/data/api").Query<import("@/data/api").TypedBlockQuery, string[]>;
+/** Substring-match content search. Empty `query` returns []. */
+export declare const searchByContentQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    query: string;
+    limit?: number;
+}, BlockData[]>;
+/** Recent non-empty block candidates. Empty workspaceId returns []. */
+export declare const recentBlocksQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    limit?: number;
+}, BlockData[]>;
+/** First child of `parentId` whose content matches exactly. */
+export declare const firstChildByContentQuery: import("@/data/api").Query<{
+    parentId: string;
+    content: string;
+}, BlockData | null>;
+/** Distinct alias values in a workspace, optionally substring-filtered. */
+export declare const aliasesInWorkspaceQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    filter?: string;
+}, string[]>;
+/** Alias autocomplete: one row per `(alias, blockId)` pair. */
+export declare const aliasMatchesQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    filter: string;
+    limit?: number;
+}, AliasMatch[]>;
+/** Single-block lookup by exact alias in a workspace. */
+export declare const aliasLookupQuery: import("@/data/api").Query<{
+    workspaceId: string;
+    alias: string;
+}, BlockData | null>;
+/** Workspace's `type: 'extension'` blocks (spec §8 Stage 2 — Phase 4
+ *  switches `dynamicExtensionsExtension` from the legacy `byType` call
+ *  to this dedicated query). Mechanically `byType('extension')`; lives
+ *  as its own kernel query so callers can register against a stable
+ *  name without depending on the convention.
+ *
+ *  No reactive dep: the only consumer (AppRuntimeProvider) calls
+ *  `.load()` once at FacetRuntime build time and feeds the result into
+ *  `resolveFacetRuntime`. Nothing observes the handle after that, so a
+ *  `workspace` dep would just churn the loader on every workspace write
+ *  without changing any observable behavior — installing or removing
+ *  an extension is picked up via the `refresh_extensions` command
+ *  (`Reload extensions` in the palette / `defaultShortcuts.ts`), which
+ *  re-runs `dynamicExtensionsExtension` and re-calls
+ *  `repo.setFacetRuntime`. */
+export declare const findExtensionBlocksQuery: import("@/data/api").Query<{
+    workspaceId: string;
+}, BlockData[]>;
+/** All kernel queries — registered at construction time when
+ *  `RepoOptions.registerKernelQueries` is true (default), and
+ *  contributed to the FacetRuntime via `kernelDataExtension`. */
+export declare const KERNEL_QUERIES: ReadonlyArray<AnyQuery>;
+/** Register every kernel query with `QueryRegistry` so call sites
+ *  using `repo.query.<name>(args)` and `repo.query['core.<name>'](args)`
+ *  get precise arg + result types without `as` casts. Plugins extend the
+ *  same interface from their own module per §12.1. */
+declare module '@/data/api' {
+    interface QueryRegistry {
+        'core.subtree': typeof subtreeQuery;
+        'core.ancestors': typeof ancestorsQuery;
+        'core.manyAncestors': typeof manyAncestorsQuery;
+        'core.children': typeof childrenQuery;
+        'core.childIds': typeof childIdsQuery;
+        'core.byType': typeof byTypeQuery;
+        'core.typedBlocks': typeof typedBlocksQuery;
+        'core.typedBlockIds': typeof typedBlockIdsQuery;
+        'core.searchByContent': typeof searchByContentQuery;
+        'core.recentBlocks': typeof recentBlocksQuery;
+        'core.firstChildByContent': typeof firstChildByContentQuery;
+        'core.aliasesInWorkspace': typeof aliasesInWorkspaceQuery;
+        'core.aliasMatches': typeof aliasMatchesQuery;
+        'core.aliasLookup': typeof aliasLookupQuery;
+        'core.findExtensionBlocks': typeof findExtensionBlocksQuery;
+    }
+}
+export {};
+//# sourceMappingURL=kernelQueries.d.ts.map

package/dist/kernel-types/src/data/internals/kernelQueries.d.ts.map

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

package/dist/kernel-types/src/data/internals/mergeProperties.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Merge two encoded property bags into one. Used by `core.merge` to fold
+ * the source block's properties into the target.
+ *
+ * Generic by design — knows nothing about specific property names; behaviour
+ * is driven entirely by the encoded value's shape. That keeps the kernel
+ * free of plugin coupling: list-coded properties (`alias`, `types`,
+ * `refList`-flavoured props) get a natural set-union, and scalars get a
+ * predictable target-wins rule.
+ *
+ * Rules per key:
+ *   1. Key in only one side  → take that value.
+ *   2. Both arrays           → concat with target order first, then
+ *                              source-only entries (JSON-keyed dedupe).
+ *   3. Both deep-equal       → keep target's value.
+ *   4. Otherwise (collision) → target wins.
+ *
+ * Inputs are never mutated; a fresh object is returned.
+ */
+export declare const mergeProperties: (intoProps: Record<string, unknown>, fromProps: Record<string, unknown>) => Record<string, unknown>;
+//# sourceMappingURL=mergeProperties.d.ts.map

package/dist/kernel-types/src/data/internals/mergeProperties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeProperties.d.ts","sourceRoot":"","sources":["../../../../../../../src/data/internals/mergeProperties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAC1B,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAiBxB,CAAA"}

package/dist/kernel-types/src/data/internals/normalizeReferencesProcessor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Same-tx processor: canonicalize `blocks.references_json` on every
+ * write. Replaces the inline `normalizeReferences(...)` calls that
+ * previously lived in `txEngine.ts` (`update`, `restore`,
+ * `insertBlockData`). Equivalent end-state — the row commits with
+ * normalized references — but pluggable, so other plugins can
+ * compose value-level normalizers onto the same pipeline stage
+ * without modifying the engine.
+ *
+ * Why the canonical form matters (excerpted from
+ * `blockData.ts:normalizeReferences` doc): on-disk shape is
+ * independent of writer-side iteration order, so equality reduces
+ * to JSON text compare; consumers (`json_each` backlinks index,
+ * BACKLINKS_FOR_BLOCK_QUERY, Map-keyed invalidation) treat
+ * references as a set.
+ *
+ * Same-tx placement notes (per docs/alias-rename-cases.html):
+ *   - Cheap (pure compute, no I/O), correctness-critical (commit
+ *     invariant), single-row (each tx may write several blocks but
+ *     each row's normalization is independent).
+ *   - Latency added is paid by the user-commit path; matches the
+ *     pre-existing inline cost.
+ */
+import { type AnySameTxProcessor } from '@/data/api';
+export declare const NORMALIZE_REFERENCES_PROCESSOR_NAME = "core.normalizeReferences";
+export declare const NORMALIZE_REFERENCES_PROCESSOR: import("@/data/api").SameTxProcessor;
+export declare const KERNEL_SAME_TX_PROCESSORS: ReadonlyArray<AnySameTxProcessor>;
+//# sourceMappingURL=normalizeReferencesProcessor.d.ts.map

package/dist/kernel-types/src/data/internals/normalizeReferencesProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeReferencesProcessor.d.ts","sourceRoot":"","sources":["../../../../../../../src/data/internals/normalizeReferencesProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAA;AAUnB,eAAO,MAAM,mCAAmC,6BAA6B,CAAA;AAE7E,eAAO,MAAM,8BAA8B,sCAgBzC,CAAA;AAEF,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,kBAAkB,CAEvE,CAAA"}

package/dist/kernel-types/src/data/internals/processorRunner.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Post-commit processor framework (spec §5.7, §7).
+ *
+ * Two firing channels:
+ *   1. Field-watching processors fire when a tx wrote to one of the
+ *      named fields on `blocks`. Engine determines this by walking the
+ *      tx's snapshots map: for each (id, before, after) where any
+ *      watched field changed value, the row is added to the
+ *      processor's CommittedEvent.changedRows. If at least one row
+ *      changed, the processor fires once with the aggregated list.
+ *
+ *   2. Explicit processors fire only when a tx called
+ *      `tx.afterCommit(name, args)`. Args are validated by the
+ *      processor's `scheduledArgsSchema` at enqueue time so a buggy
+ *      caller fails the originating tx (clean rollback) instead of
+ *      failing silently when the processor would otherwise fire.
+ *
+ * The framework does NOT auto-open a writeTransaction for the processor
+ * (v4.32 — see §5.7). `apply(event, ctx)` runs as a plain async function
+ * with `ctx = { db, repo }`. Pure-side-effect processors do nothing more;
+ * write processors open their own `ctx.repo.tx(...)` when they decide to
+ * write. This avoids holding a writer slot through read phases (the
+ * shape that produced the §10 / `tasks/processor-tx-deadlock.md`
+ * deadlock under PowerSync's serialized single-connection config) and
+ * lets pure-side-effect processors skip the writer cost entirely.
+ *
+ * Failures are caught + logged so a crashing processor can't poison
+ * subsequent jobs.
+ *
+ * Stage-1.5 deferred:
+ *   - per-block content debouncing (§7.2 row "Trigger on content change"):
+ *     v1 ships every fire immediately. The dispatcher ordering is
+ *     append-only and sequential, so two close-together content writes
+ *     run parseReferences twice — that's slightly more work than the
+ *     legacy debounced behavior, but is easier to reason about and
+ *     covers correctness. Add coalescing if profiling shows pain.
+ */
+import { type AnyPostCommitProcessor, type AnyPropertySchema, type User } from '@/data/api';
+import type { AfterCommitJob } from './txEngine';
+import type { SnapshotsMap } from './txSnapshots';
+import type { PowerSyncDb } from './commitPipeline';
+import type { Repo } from '../repo';
+/** Tx-grain inputs the runner needs to decide what fires + with which
+ *  changedRows. Built by the commit pipeline from the snapshots map +
+ *  collected afterCommit jobs. */
+export interface CommittedTxOutcome {
+    txId: string;
+    user: User;
+    workspaceId: string | null;
+    /** Snapshots map walked into a flat list. */
+    snapshots: SnapshotsMap;
+    /** afterCommit jobs scheduled by the user fn. */
+    afterCommitJobs: AfterCommitJob[];
+    /** Processor registry snapshot taken at tx start (spec §3, §8). The
+     *  runner iterates this — not its own current registry — so a
+     *  `setFacetRuntime` call landing mid-flight can't change which
+     *  processors fire (or with what apply fn) for an already-running tx. */
+    processors: ReadonlyMap<string, AnyPostCommitProcessor>;
+    /** Merged property-schema registry snapshot taken at the same
+     *  boundary as `processors`. */
+    propertySchemas: ReadonlyMap<string, AnyPropertySchema>;
+}
+export declare class ProcessorRunner {
+    private readonly repo;
+    private readonly db;
+    /** In-flight processor promises. Tracked so tests (and any caller
+     *  who needs deterministic ordering) can `awaitIdle()` before
+     *  assertions. Each promise removes itself from the set on
+     *  settlement (success or failure). */
+    private readonly pending;
+    constructor(repo: Repo, db: PowerSyncDb);
+    /** Wait until every currently-pending processor (synchronous + any
+     *  already-fired delayed jobs) resolves. Does NOT advance timers —
+     *  delayed jobs that haven't started yet aren't pending. Tests that
+     *  need to flush a delayed job should use vi.useFakeTimers /
+     *  vi.runAllTimers (or just sleep). */
+    awaitIdle(): Promise<void>;
+    /** Dispatch all matching processors for one committed tx. Called by
+     *  Repo after `repo.tx` resolves. Walks the tx's processor snapshot
+     *  (`outcome.processors`), not the runner's current registry — that's
+     *  the §3/§8 contract: a tx fires the processors that were registered
+     *  when it started, even if `setFacetRuntime` has since replaced them.
+     *  Errors in any one processor are caught + logged; subsequent ones
+     *  still run. */
+    dispatch(outcome: CommittedTxOutcome): Promise<void>;
+    private track;
+    /** Invoke the processor's apply with a `{db, repo}` ctx. The framework
+     *  does not wrap apply in a writeTransaction (v4.32) — apply is a
+     *  plain async fn that reads via `ctx.db` and (if it needs to write)
+     *  opens its own tx via `ctx.repo.tx(...)`. Errors are caught + logged
+     *  with the processor name + txId so one buggy processor can't poison
+     *  the dispatch loop. */
+    private runOne;
+}
+//# sourceMappingURL=processorRunner.d.ts.map

package/dist/kernel-types/src/data/internals/processorRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processorRunner.d.ts","sourceRoot":"","sources":["../../../../../../../src/data/internals/processorRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EAItB,KAAK,IAAI,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAEnC;;kCAEkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;IACV,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,YAAY,CAAA;IACvB,iDAAiD;IACjD,eAAe,EAAE,cAAc,EAAE,CAAA;IACjC;;;6EAGyE;IACzE,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAA;IACvD;oCACgC;IAChC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CACxD;AAyCD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAM;IAC3B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAa;IAChC;;;2CAGuC;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;gBAE5C,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW;IAKvC;;;;2CAIuC;IACjC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAQhC;;;;;;qBAMiB;IACX,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkE1D,OAAO,CAAC,KAAK;IAKb;;;;;6BAKyB;YACX,MAAM;CAwBrB"}

package/dist/kernel-types/src/data/internals/rowEventsTail.d.ts

@@ -0,0 +1,70 @@
+/**
+ * row_events tail — sync-applied invalidation path (spec §9.3 path 2).
+ *
+ * Local writes go through `repo.tx`, which fires the engine's fast-path
+ * `handleStore.invalidate(...)` and updates the cache directly. PowerSync
+ * sync-applied writes land in SQLite via the CRUD-apply path, BYPASSING
+ * `repo.tx` — they never set `tx_context.source`, so the `row_events`
+ * trigger COALESCEs source to `'sync'`.
+ *
+ * This tail subscribes to the `row_events` table, filters to
+ * `source = 'sync'` (avoiding overlap with the engine fast-path), and:
+ *
+ *   - Reads new rows since the last consumed `id`.
+ *   - Updates the BlockCache with the after_json snapshot (or evicts
+ *     on hard-delete) so Block facades subscribed via cache.subscribe
+ *     reflect remote changes — without this, sync writes are invisible
+ *     to UI consumers that don't go through a collection handle.
+ *   - Calls `handleStore.invalidate(...)` with a `ChangeNotification`
+ *     that lists `rowIds` + `parentIds` + `workspaceIds` so collection
+ *     handles re-resolve. `parentIds` covers both before- and after-
+ *     parents of sync-applied edge changes, plus same-parent order_key
+ *     changes, matching the `parent-edge` dep declared by
+ *     `repo.children` / `repo.childIds`.
+ *
+ * Throttling: db.onChange's `throttleMs` coalesces sync-burst arrivals
+ * into batched processing. 100ms is the spec's recommendation (§9.3).
+ *
+ * The tail is a single subscription on the `row_events` table —
+ * regardless of how many handles exist, only one query runs per
+ * throttle window, and the dep-matching walk inside HandleStore is
+ * O(handles × deps).
+ */
+import type { CycleDetectedEvent } from '@/data/api';
+import type { BlockCache } from '@/data/blockCache';
+import type { PowerSyncDb } from './commitPipeline';
+import type { HandleStore } from './handleStore';
+import { type InvalidationRule } from '@/data/invalidation.js';
+export interface RowEventsTailOptions {
+    throttleMs?: number;
+    /** Optional override for the initial high-watermark query. Tests inject
+     *  this to start the tail from id=0 (consume historical rows too). */
+    initialLastId?: number;
+    onError?: (err: unknown) => void;
+    /** Fired once per drain pass when the bounded cycle scan finds at
+     *  least one affected id closing back on itself. One event per
+     *  workspace involved (single-workspace per cycle by construction
+     *  — server FK + invariant trigger keep parent_id mutations within
+     *  a workspace). Spec §4.7. */
+    onCycleDetected?: (event: CycleDetectedEvent) => void;
+}
+export interface RowEventsTail {
+    /** Stop the subscription. Idempotent. */
+    dispose(): void;
+    /** Run one tail-pass synchronously. Used by tests to flush without
+     *  waiting on the throttle window. */
+    flush(): Promise<void>;
+    /** The id of the most recent row we consumed. Useful for tests. */
+    lastId(): number;
+}
+/** Start the tail subscription. Returns a handle for disposal + manual
+ *  flush. The async initialization runs in the background; the returned
+ *  object is usable immediately (`flush()` will await initialization). */
+export declare const startRowEventsTail: (args: {
+    db: PowerSyncDb;
+    cache: BlockCache;
+    handleStore: HandleStore;
+    getInvalidationRules?: () => readonly InvalidationRule[];
+    options?: RowEventsTailOptions;
+}) => RowEventsTail;
+//# sourceMappingURL=rowEventsTail.d.ts.map

package/dist/kernel-types/src/data/internals/rowEventsTail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rowEventsTail.d.ts","sourceRoot":"","sources":["../../../../../../../src/data/internals/rowEventsTail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAa,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAsB,WAAW,EAAE,MAAM,eAAe,CAAA;AAEpE,OAAO,EAEL,KAAK,gBAAgB,EAEtB,MAAM,wBAAwB,CAAA;AAe/B,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;0EACsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;IAChC;;;;mCAI+B;IAC/B,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAA;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAA;IACf;0CACsC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,mEAAmE;IACnE,MAAM,IAAI,MAAM,CAAA;CACjB;AAED;;0EAE0E;AAC1E,eAAO,MAAM,kBAAkB,GAAI,MAAM;IACvC,EAAE,EAAE,WAAW,CAAA;IACf,KAAK,EAAE,UAAU,CAAA;IACjB,WAAW,EAAE,WAAW,CAAA;IACxB,oBAAoB,CAAC,EAAE,MAAM,SAAS,gBAAgB,EAAE,CAAA;IACxD,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAC/B,KAAG,aAgVH,CAAA"}

package/dist/kernel-types/src/data/internals/timingMetrics.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Timing-based metrics: bounded reservoir + DB / query wrappers
+ * (perf-baseline follow-up #4 extension).
+ *
+ * Counterpart to the simple-counter metrics on HandleStore / BlockCache.
+ * Where those answer "how often", these answer "how long":
+ *
+ *   - `DbMetrics` aggregates wall-clock timings for every PowerSyncDb
+ *     call site that flows through the Repo (`getAll`, `getOptional`,
+ *     `get`, `execute`, `writeTransaction`). Use to tell whether
+ *     a slow cold-start lives in raw SQL roundtrip cost or above it.
+ *   - `QueryMetrics` keys by query name (e.g. `core.subtree`,
+ *     `plugin:tasks/dueSoon`) and records the wall-clock time of each
+ *     `loader(ctx)` invocation. Re-resolves (LoaderHandle.invalidate)
+ *     count as separate samples — the dispatcher path runs the loader
+ *     fresh each time, and that's the unit you care about for "open
+ *     page → ms to settle".
+ *
+ * Approximate percentiles via a fixed-capacity ring buffer (default 256
+ * samples). Cheap, bounded memory, and accurate enough for the
+ * "is this 10 ms or 100 ms?" decisions we'd make from a debug panel.
+ * For higher-precision distributions, use the bench harness instead —
+ * this exists for in-app awareness, not benchmark output.
+ *
+ * Cost: a `performance.now()` pair + ring-buffer write per call. At
+ * the rates the data layer hits (a few thousand SQL calls/sec under
+ * worst-case sync bursts) that's well under 1% of wall time.
+ */
+/** Approximate-percentile ring buffer. Records the last `capacity`
+ *  samples; `snapshot()` sorts a copy on demand. `calls` is the total
+ *  observed across the lifetime of the reservoir (not bounded by
+ *  capacity), so consumers can still read "how many samples have we
+ *  seen?" even after the buffer wrapped. */
+export declare class TimingReservoir {
+    private readonly capacity;
+    private readonly samples;
+    private writeIdx;
+    private filled;
+    private callsTotal;
+    private sumMs;
+    constructor(capacity?: number);
+    record(ms: number): void;
+    reset(): void;
+    /** Frozen plain-object summary. Percentile values are 0 when
+     *  `sampleCount === 0` (no samples yet); consumers should branch
+     *  on that field rather than treating 0 as a real measurement. */
+    snapshot(): TimingSnapshot;
+}
+/** Frozen summary returned by `TimingReservoir.snapshot()`. */
+export interface TimingSnapshot {
+    /** Total samples observed since last reset (NOT bounded by buffer
+     *  capacity). */
+    readonly calls: number;
+    /** Samples actually retained in the ring buffer (capped at
+     *  `capacity`). p50/p95/p99 are computed over these. */
+    readonly sampleCount: number;
+    /** Mean of the samples in the window (not the lifetime sum / calls
+     *  — that pairs poorly with windowed percentiles when the buffer
+     *  has wrapped). */
+    readonly meanMs: number;
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+    readonly p99Ms: number;
+    readonly minMs: number;
+    readonly maxMs: number;
+    /** Sum of every observed call's duration, across the full lifetime
+     *  of the reservoir (not bounded by capacity). Useful for "this
+     *  query has spent X ms total since the page opened." */
+    readonly totalMs: number;
+}
+/** Aggregate timings for every PowerSyncDb call that flows through the
+ *  Repo (read calls + writeTransaction wall-clock). One instance per
+ *  Repo. */
+export declare class DbMetrics {
+    readonly getAll: TimingReservoir;
+    readonly getOptional: TimingReservoir;
+    readonly get: TimingReservoir;
+    readonly execute: TimingReservoir;
+    /** Total `db.writeTransaction(...)` wall time, including commit
+     *  overhead. Tx-internal SQL calls (via the LockContext) are timed
+     *  separately under their respective fields above — so a single
+     *  `mutate.setContent` typically registers 1 writeTransaction sample
+     *  AND a handful of `getAll`/`execute` samples for the inner work. */
+    readonly writeTransaction: TimingReservoir;
+    reset(): void;
+    snapshot(): Readonly<Record<string, TimingSnapshot>>;
+}
+/** Per-query-name resolve timings. Keys are full query names
+ *  (`core.subtree`, `plugin:foo/bar`, …). Empty entries don't appear
+ *  in the snapshot — only queries that actually ran are surfaced. */
+export declare class QueryMetrics {
+    private readonly perName;
+    /** Record one `loader(ctx)` invocation for `queryName`. Lazily
+     *  creates a reservoir on first call so unused queries cost nothing.
+     *  Capacity defaults to 256 — same as the DbMetrics reservoirs. */
+    record(queryName: string, ms: number): void;
+    reset(): void;
+    snapshot(): Readonly<Record<string, TimingSnapshot>>;
+}
+/** Wrap a `PowerSyncDb` with timing instrumentation. Returns a Proxy
+ *  over the input — five methods (`getAll`, `getOptional`, `get`,
+ *  `execute`, `writeTransaction`) are intercepted and timed; everything
+ *  else (`onChange`, `close`, …) passes through to the original db.
+ *  This means consumers like `exportSqliteDb` that need
+ *  PowerSyncDatabase-only methods continue to work without us
+ *  re-declaring them.
+ *
+ *  `writeTransaction` also wraps the LockContext passed to the callback
+ *  so tx-internal SQL is timed under the same metrics buckets.
+ *
+ *  Type-erased to `unknown` here so the module doesn't import
+ *  `PowerSyncDb`; `Repo` casts at the call site (it owns the
+ *  `PowerSyncDb` type contract). */
+export declare const wrapDbWithMetrics: (rawDb: unknown, metrics: DbMetrics) => unknown;
+//# sourceMappingURL=timingMetrics.d.ts.map

package/dist/kernel-types/src/data/internals/timingMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timingMetrics.d.ts","sourceRoot":"","sources":["../../../../../../../src/data/internals/timingMetrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;4CAI4C;AAC5C,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,KAAK,CAAI;gBAEL,QAAQ,SAAM;IAM1B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAYxB,KAAK,IAAI,IAAI;IAQb;;sEAEkE;IAClE,QAAQ,IAAI,cAAc;CAkC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B;qBACiB;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;4DACwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;wBAEoB;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;6DAEyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;YAEY;AACZ,qBAAa,SAAS;IACpB,QAAQ,CAAC,MAAM,kBAAwB;IACvC,QAAQ,CAAC,WAAW,kBAAwB;IAC5C,QAAQ,CAAC,GAAG,kBAAwB;IACpC,QAAQ,CAAC,OAAO,kBAAwB;IACxC;;;;0EAIsE;IACtE,QAAQ,CAAC,gBAAgB,kBAAwB;IAEjD,KAAK,IAAI,IAAI;IAQb,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CASrD;AAED;;qEAEqE;AACrE,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D;;uEAEmE;IACnE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAS3C,KAAK,IAAI,IAAI;IAOb,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAKrD;AAwBD;;;;;;;;;;;;;oCAaoC;AACpC,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,EAAE,SAAS,SAAS,KAAG,OAuEtE,CAAA"}