@knowledge-medium/agent-cli 0.1.0

package/dist/kernel-types/src/data/repo.d.ts

@@ -0,0 +1,745 @@
+/**
+ * New `Repo` class for the data-layer redesign (spec §3, §8).
+ *
+ * Stage 1.4 scope: holds `db` + `cache` + `user` + the mutator registry
+ * (kernel mutators registered at construction time). Exposes:
+ *   - `repo.tx(fn, opts)` — primitive transactional session
+ *   - `repo.mutate.X(args)` — typed-dispatch sugar (1-mutator tx wrapping)
+ *   - `repo.run(name, args)` — runtime-validated dispatch (dynamic plugins)
+ *   - `repo.setFacetRuntime(runtime)` — refresh mutator registry from a
+ *     FacetRuntime. Minimal impl reads `mutatorsFacet` contributions.
+ *
+ * Stage 2 of Phase 1 (post-1.6) adds:
+ *   - HandleStore + `repo.block(id)` / `repo.children(id)` / etc.
+ *   - row_events tail subscription for sync-applied invalidation
+ */
+import type { FacetRuntime, Facet } from '@/extensions/facet';
+import type { AnyMutator, AnyPostCommitProcessor, AnySameTxProcessor, AnyPropertyEditorOverride, AnyPropertySchema, AnyQuery, AnyValuePreset, BlockData, Mutator, MutatorRegistry, Query, QueryRegistry, RepoTxOptions, TypedBlockQuery, TypeContribution, TypeRegistrySnapshot, Tx, Unsubscribe, User } from '@/data/api';
+import { ChangeScope, ProcessorRejection } from '@/data/api';
+import { type PowerSyncDb } from './internals/commitPipeline';
+import type { BlockCache } from '@/data/blockCache';
+import { Block } from './block';
+import { HandleStore, LoaderHandle } from './internals/handleStore';
+import { DbMetrics, QueryMetrics } from './internals/timingMetrics';
+import { type RowEventsTail, type RowEventsTailOptions } from './internals/rowEventsTail';
+import { UndoManager } from './internals/undoManager';
+import { UserSchemasService } from './userSchemasService';
+import { UserTypesService } from './userTypesService';
+/** Convert a `Mutator<Args, Result>` into the `repo.mutate` dispatcher
+ *  signature `(args: Args) => Promise<Result>`. Used to project
+ *  augmented `MutatorRegistry` entries into precise per-key types on
+ *  the proxy field. */
+type DispatchFor<M> = M extends Mutator<infer A, infer R> ? (args: A) => Promise<R> : never;
+/** Per-key dispatcher types for every mutator known at compile time —
+ *  every `MutatorRegistry` member, plus the bare `core.<name>`-stripped
+ *  shortcut. Plugins extend this surface by augmenting the
+ *  `MutatorRegistry` interface from `@/data/api`; kernel mutators are
+ *  augmented in `kernelMutators.ts`. */
+type KnownMutateDispatch = {
+    [K in keyof MutatorRegistry]: DispatchFor<MutatorRegistry[K]>;
+} & {
+    [K in keyof MutatorRegistry as K extends `core.${infer Bare}` ? Bare : never]: DispatchFor<MutatorRegistry[K]>;
+};
+/** Proxy contract surface. Known keys (above) get precise typing;
+ *  unknown keys fall through the `any` index signature so dynamically
+ *  loaded plugins that haven't augmented `MutatorRegistry` are still
+ *  callable via `repo.mutate['plugin:foo'](args)`. The runtime
+ *  argsSchema validation in `dispatchMutator` stays the source of truth
+ *  for safety on those paths. */
+export type MutateProxy = KnownMutateDispatch & {
+    [name: string]: (args: any) => Promise<any>;
+};
+/** Convert a `Query<Args, Result>` into the `repo.query` dispatcher
+ *  signature `(args: Args) => LoaderHandle<Result>`. Mirrors
+ *  `DispatchFor` for mutators. Returning the concrete `LoaderHandle<R>`
+ *  (not just `Handle<R>`) keeps consistency with the existing
+ *  `repo.subtree(id)` / `repo.children(id)` factories. */
+type DispatchQueryFor<Q> = Q extends Query<infer A, infer R> ? (args: A) => LoaderHandle<R> : never;
+type KnownQueryDispatch = {
+    [K in keyof QueryRegistry]: DispatchQueryFor<QueryRegistry[K]>;
+} & {
+    [K in keyof QueryRegistry as K extends `core.${infer Bare}` ? Bare : never]: DispatchQueryFor<QueryRegistry[K]>;
+};
+/** Proxy contract surface for `repo.query`. Mirrors `MutateProxy`:
+ *  known keys (kernel + augmented plugins per `QueryRegistry`) get
+ *  precise typing; unknown string keys fall through the `any` index
+ *  so dynamically-loaded plugins are still callable via
+ *  `repo.query['plugin:foo'](args)`. The argsSchema validation in
+ *  `dispatchQuery` is the runtime safety boundary for those paths. */
+export type QueryProxy = KnownQueryDispatch & {
+    [name: string]: (args: any) => LoaderHandle<any>;
+};
+export interface RepoOptions {
+    db: PowerSyncDb;
+    cache: BlockCache;
+    user: User;
+    /** Read-only mode disables `BlockDefault` / `References` writes.
+     *  `UiState` stays local-only and `UserPrefs` degrades to local-only.
+     *  Default false. */
+    isReadOnly?: boolean;
+    /** Now provider — default `Date.now`. Injected for test determinism. */
+    now?: () => number;
+    /** UUID provider — default `crypto.randomUUID`. Injected for tests
+     *  that want deterministic ids. */
+    newId?: () => string;
+    /** Monotonic INTEGER tx-grouping key provider, written into
+     *  `tx_context.tx_seq` and copied to `ps_crud.tx_id` by the upload
+     *  triggers. Default: a counter seeded from `Date.now()` so values
+     *  never collide with anything from a prior run. Tests can inject a
+     *  deterministic counter. */
+    newTxSeq?: () => number;
+    /** When true (default), kernel mutators are registered at
+     *  construction time so `repo.mutate.indent({...})` works
+     *  immediately. Set false when a test wants to populate the registry
+     *  explicitly (or when `setFacetRuntime` is the only registration
+     *  path). */
+    registerKernelMutators?: boolean;
+    /** When true (default), kernel post-commit processors are registered
+     *  at construction time. The kernel set is currently empty; plugin
+     *  processors arrive through `setFacetRuntime`. Kept as a test/tooling
+     *  switch for any future core-only processors. */
+    registerKernelProcessors?: boolean;
+    /** When true (default), kernel same-tx processors are registered at
+     *  construction time. Today that's `core.normalizeReferences`. Set
+     *  false in tests that need to exercise the engine without
+     *  reference normalization (e.g. asserting raw-shape round-trip). */
+    registerKernelSameTxProcessors?: boolean;
+    /** When true (default), kernel queries are registered at construction
+     *  time so `repo.query.subtree({id})` etc. work immediately without a
+     *  `setFacetRuntime` call. Set false when a test wants to populate
+     *  the query registry explicitly. Mirrors `registerKernelMutators` /
+     *  `registerKernelProcessors`. */
+    registerKernelQueries?: boolean;
+    /** When true (default), the kernel `kernelInvalidationRule` is
+     *  registered at construction time so `core.byType` / `core.typedBlocks`
+     *  / alias / content queries fire correctly without a `setFacetRuntime`
+     *  call. Tests that want to populate the invalidation-rules registry
+     *  explicitly can disable this. */
+    registerKernelInvalidationRules?: boolean;
+    /** When true (default), the row_events tail subscription is started
+     *  at construction time so sync-applied writes propagate into the
+     *  cache + invalidate handles (spec §9.3). Set false in unit tests
+     *  that want explicit control over tail timing — they can call
+     *  `repo.startRowEventsTail({initialLastId: 0})` to opt back in
+     *  with deterministic semantics. */
+    startRowEventsTail?: boolean;
+    /** Options forwarded to the row_events tail when started. */
+    rowEventsTailOptions?: RowEventsTailOptions;
+}
+export declare class Repo {
+    readonly db: PowerSyncDb;
+    readonly cache: BlockCache;
+    user: User;
+    /** Read-only mode disables `BlockDefault` / `References` writes;
+     *  UI-state and UserPrefs writes still pass through and queue to
+     *  ps_crud — server-side rejection (RLS) lands in the rejection
+     *  quarantine. Mutate via `repo.setReadOnly(value)` rather than
+     *  direct field assignment so callers from inside React hooks don't
+     *  trip `react-hooks/immutability` lint (the mutation should travel
+     *  through a method, not a property write). */
+    isReadOnly: boolean;
+    private readonly now;
+    private readonly newId;
+    private readonly newTxSeq;
+    private mutators;
+    private processors;
+    /** Same-tx processor registry — runs inside the user's
+     *  writeTransaction in `runTx`. Kept separate from
+     *  `this.processors` (post-commit) because the two have different
+     *  ctx shapes and run at different pipeline stages; see
+     *  `sameTxProcessorsFacet` doc in `facets.ts`. */
+    private sameTxProcessors;
+    private queries;
+    private _types;
+    private _propertySchemas;
+    private _propertyEditorOverrides;
+    private _valuePresets;
+    private invalidationRules;
+    /** Currently-installed FacetRuntime, retained so
+     *  `setRuntimeContributions` can mutate runtime contribution buckets
+     *  without going through a fresh runtime resolution. Null until the
+     *  first setFacetRuntime call. */
+    private runtime;
+    /** Per-facet listener disposers from `onFacetChange` registrations.
+     *  Cleared when `setFacetRuntime` swaps to a fresh runtime — old
+     *  listeners would fire against stale rebuild closures otherwise. */
+    private runtimeFacetUnsubs;
+    /** Repo-owned runtime contribution buckets. Persisted across
+     *  `setFacetRuntime` swaps and replayed onto the fresh runtime so
+     *  user-data schemas (et al.) survive the dynamic-extension reload.
+     *  Without this, the user-data bucket would live only on whichever
+     *  FacetRuntime was current at `setRuntimeContributions` time and
+     *  evaporate on the next `setFacetRuntime`.
+     *
+     *  NOTE for agent-side introspection: this is a *replay cache*, NOT
+     *  a general "what's registered" map. It only holds dynamic
+     *  contributions added via `setRuntimeContributions` (user-data
+     *  schemas, etc.), so it looks sparse compared to the full
+     *  registry. The full registry lives on the FacetRuntime
+     *  (`facetRuntime.facetIds()` / `contributionsById(id)`), and the
+     *  agent-facing surface is `yarn agent describe-runtime`. Inner
+     *  keys here are arbitrary source-id strings chosen by the caller
+     *  of `setRuntimeContributions`. */
+    private readonly runtimeContributionBuckets;
+    /** Per-facet refs needed to replay buckets onto a fresh runtime —
+     *  setRuntimeContributions takes a `Facet` reference (not a string
+     *  id), so we cache it the first time the caller passes one. */
+    private readonly runtimeContributionFacets;
+    /** Listeners for property-schema map changes (full rebuild OR
+     *  runtime-bucket update). Used by `usePropertySchemas` to drive
+     *  React reruns. */
+    private readonly propertySchemasListeners;
+    /** Listeners for `_types` map changes (full rebuild OR runtime-bucket
+     *  update on `typesFacet`). Symmetric to propertySchemasListeners.
+     *  Used by `createTypeBlock`'s commit→registration handoff to bridge
+     *  two txs without polling: once UserTypesService's subscription
+     *  publishes a new type contribution, the rebuild step re-reads
+     *  typesFacet, this listener fires, and the bridge wait resolves. */
+    private readonly typesListeners;
+    /** Listeners for property-editor-override map changes. */
+    private readonly propertyEditorOverridesListeners;
+    /** Listeners for value-preset map changes. */
+    private readonly valuePresetsListeners;
+    /** Listeners for user-surfaceable errors thrown from inside a
+     *  `repo.tx` — currently `ProcessorRejection` from same-tx
+     *  processors. Subscribers are responsible for the UI side
+     *  (toast routing); the data layer stays UI-agnostic. */
+    private readonly userErrorListeners;
+    /** Rebuild step descriptors. Defined once per Repo at construction;
+     *  each step declares which facets it reads. `setFacetRuntime` runs
+     *  every step; `setRuntimeContributions` runs only the steps whose
+     *  inputs include the changed facet. */
+    private readonly rebuildSteps;
+    /** Per-query-name generation counter. Bumped by `setFacetRuntime`
+     *  (and `__setQueriesForTesting`) whenever a name's registered Query
+     *  instance changes — including when a name is added or removed. The
+     *  generation is folded into the query handle-store key so cached
+     *  handles that closed over the OLD resolver no longer collide with
+     *  fresh lookups, which produce a new LoaderHandle bound to the NEW
+     *  resolver. Old handles GC after their subscribers detach (the
+     *  HandleStore's normal ref-count path). Reviewer P2: prevents
+     *  same-name plugin updates from continuing to dispatch through the
+     *  pre-swap resolver / argsSchema. */
+    private queryGenerations;
+    private readonly processorRunner;
+    /** Per-scope undo / redo stacks (spec §10 step 7, §17 line 2228).
+     *  `repo.tx` records every undoable commit here; `repo.undo` /
+     *  `repo.redo` pop entries and replay them via `TxImpl.applyRaw`. */
+    readonly undoManager: UndoManager;
+    /** Identity-stable Block facades, keyed by id. Block satisfies
+     *  Handle<BlockData|null> structurally (spec §5.1, §5.2) — its
+     *  row-grain reactivity goes through BlockCache.subscribe directly,
+     *  so it doesn't need a HandleStore entry; this map IS its identity
+     *  table. */
+    private readonly blockFacades;
+    /** Handle registry for query-backed collection factories: `children`,
+     *  `subtree`, `ancestors`, plugin queries, etc. Identity rule:
+     *  same key → same LoaderHandle instance. GC after `gcTimeMs` of
+     *  zero subscribers + zero in-flight loads. The store also walks
+     *  invalidation: TxEngine fast path + row_events tail (Phase 2.C)
+     *  call `handleStore.invalidate({…})` to fan out to dep-matching
+     *  handles. */
+    readonly handleStore: HandleStore;
+    /** Per-PowerSyncDb-call timings (getAll / getOptional / get /
+     *  execute / writeTransaction). Populated by the metrics-wrapping
+     *  proxy installed around `this.db` at construction. */
+    readonly dbMetrics: DbMetrics;
+    /** Per-query-name resolve timings. The dispatcher records each
+     *  `loader(ctx)` invocation here keyed by the query's full name. */
+    readonly queryMetrics: QueryMetrics;
+    /** Counters for `reprojectRefTypedProperties`. Each call to the
+     *  reprojection path increments these — useful when investigating
+     *  bootstrap-time write-tx amplification triggered by user/plugin
+     *  schema changes. Surfaced through `repo.metrics().reprojection`. */
+    private readonly reprojectionMetrics;
+    /** Lazy in-memory mirror of the per-name reprojection markers in
+     *  `client_schema_state` (rows keyed `reproject_ref:<name>`). `null`
+     *  until the first reprojection call hydrates it via a single
+     *  `SELECT key … LIKE 'reproject_ref:%'` round-trip; afterwards
+     *  `reprojectRefTypedProperties` skips ref-typed names already in
+     *  this set without further SQL. Tests / migrations that wipe the
+     *  table can call `__resetReprojectionMarkerCache` to force a reload. */
+    private reprojectionMarkers;
+    /** Slowest writeTransaction observed since the last reset, by
+     *  description (`opts.description` passed to `repo.tx`). Updated only
+     *  when a tx exceeds the previous high-water mark, so the field is
+     *  cheap to maintain in the hot path. Surfaces through
+     *  `repo.metrics().db.slowestTx`. */
+    private slowestTx;
+    /** Bounded log of recent tx (description, ms) — used to attribute
+     *  cold-start `writeTransaction` totals to specific call sites. The
+     *  most recent `TX_LOG_CAPACITY` entries are retained; older drops
+     *  are silent. Surfaces through `repo.metrics().txLog`. */
+    private readonly txLog;
+    /** Active row_events tail (spec §9.3 path 2). Lazy: created on first
+     *  start, replaced on subsequent starts. Tests can `dispose()` and
+     *  re-`start` for deterministic flushing. */
+    private rowEventsTail;
+    /** Backing field for `activeWorkspaceId` (see getter/setter below). */
+    private _activeWorkspaceId;
+    /** Instance discriminator for memoization keys that need to vary
+     *  across Repo instances (e.g. lodash.memoize calls in the panel /
+     *  user-page bootstrap). Auto-incremented per construction. */
+    private static nextInstanceId;
+    readonly instanceId: number;
+    /** Hydrate a list of `BlockRow`s into the cache + return parsed
+     *  BlockData[]. Internal helper for kernel queries. Callers choose
+     *  whether returned rows are part of the query result (`row` deps) or
+     *  only cache priming (`no row` deps). Accepts readonly so it pairs
+     *  cleanly with the QueryCtx plumbing in `dispatchQuery`. */
+    private hydrateRows;
+    get types(): ReadonlyMap<string, TypeContribution>;
+    get propertySchemas(): ReadonlyMap<string, AnyPropertySchema>;
+    get propertyEditorOverrides(): ReadonlyMap<string, AnyPropertyEditorOverride>;
+    get valuePresets(): ReadonlyMap<string, AnyValuePreset>;
+    /** Deterministic id of the workspace's Properties page (parent of
+     *  all `'property-schema'` blocks). Created lazily by
+     *  `getOrCreatePropertiesPage` during workspace bootstrap. */
+    get propertiesPageId(): string | null;
+    /** UserSchemasService singleton bound to this Repo. Owns the
+     *  user-data contribution bucket on `propertySchemasFacet`; sharing
+     *  one instance means imperative call sites (the AddPropertyForm,
+     *  the Roam importer) all hit the same in-memory list rather than
+     *  each fresh instance clobbering the bucket from an empty start.
+     *  The block-subscription path is opt-in via `start()`; the React
+     *  provider starts it once per workspace. */
+    readonly userSchemas: UserSchemasService;
+    /** UserTypesService singleton bound to this Repo. Symmetric to
+     *  `userSchemas`: owns the user-data contribution bucket on
+     *  `typesFacet` and is started once per workspace by the React
+     *  provider. Depends on `userSchemas` for resolving
+     *  block-type:properties refList entries to live property schemas. */
+    readonly userTypes: UserTypesService;
+    /** Deterministic id of the workspace's Types page (parent of every
+     *  `'block-type'` block in the workspace). Created lazily by
+     *  `getOrCreateTypesPage` during workspace bootstrap. */
+    get typesPageId(): string | null;
+    /** Run `CHILDREN_SQL` for `parentId` and hydrate every row into the
+     *  per-row cache. Shared by the `repo.load(id, {children: true})`
+     *  opts path, `repo.children(id)` handle, and the hydrating variant
+     *  of `repo.childIds(id)`. Collection-level reactivity is owned by
+     *  the `LoaderHandle` returned from `repo.children` / `repo.childIds`
+     *  — `BlockCache` doesn't track per-parent "loaded" state. */
+    private hydrateChildren;
+    /** Typed-dispatch sugar. `repo.mutate.indent({id})` opens a 1-mutator
+     *  tx with the mutator's scope and runs it. Lookup tries the literal
+     *  key first (`'tasks:setDueDate'` for plugin mutators), then
+     *  `'core.${name}'` (so the bare `repo.mutate.indent` resolves to
+     *  `'core.indent'`).
+     *
+     *  Typing surface (Phase 3 — chunk C): keys present in
+     *  `MutatorRegistry` (kernel + augmented plugins, see §12.1) get
+     *  precise `(args: Args) => Promise<Result>` types; the
+     *  `core.<name>`-stripped form is also typed. Unknown keys
+     *  (dynamically-loaded plugins that haven't augmented the registry)
+     *  fall back to a permissive `(args: any) => Promise<any>` index
+     *  signature so string-key access stays callable. */
+    readonly mutate: MutateProxy;
+    /** Typed query dispatch. `repo.query.subtree({id})` returns an
+     *  identity-stable `LoaderHandle<R>` (the same instance for the same
+     *  args, GC'd via HandleStore). Lookup tries the literal `name` first
+     *  (`'core.subtree'` or `'plugin:foo'`), then `'core.${name}'` so the
+     *  bare `repo.query.subtree` resolves to `'core.subtree'`. Args are
+     *  validated against `Query.argsSchema` on every call.
+     *
+     *  Typing surface mirrors `repo.mutate`: keys present in
+     *  `QueryRegistry` (kernel + augmented plugins) get precise
+     *  `(args: Args) => LoaderHandle<Result>` types; the
+     *  `core.<name>`-stripped form is also typed. Unknown keys
+     *  (dynamically-loaded plugins that haven't augmented the registry)
+     *  fall back to a permissive `(args: any) => LoaderHandle<any>` index
+     *  signature so string-key access stays callable. The runtime
+     *  `argsSchema` validation in `dispatchQuery` is the safety boundary
+     *  for those paths. */
+    readonly query: QueryProxy;
+    constructor(opts: RepoOptions);
+    /** Start the row_events tail subscription (spec §9.3). Idempotent
+     *  in spirit: if a tail is already running, it's disposed first so
+     *  the new options take effect. Returns the tail for inspection /
+     *  manual flushing. */
+    startRowEventsTail(options?: RowEventsTailOptions): RowEventsTail;
+    /** Dispose the active row_events tail (no-op if none). Tests use
+     *  this to detach the subscription before tearing down the test DB. */
+    stopRowEventsTail(): void;
+    /** Manually flush the row_events tail — synchronously consumes any
+     *  rows not yet processed and walks `handleStore.invalidate(...)`.
+     *  Tests use this instead of waiting on the throttle window. */
+    flushRowEventsTail(): Promise<void>;
+    /** Frozen snapshot of internal data-layer counters + timings
+     *  (perf-baseline follow-up #4). Returns four subsections:
+     *
+     *    - `handleStore` — invalidate fan-out (`invalidations`,
+     *      `handlesWalked`, `handlesMatched`) and per-LoaderHandle
+     *      lifecycle (`loaderInvalidations`, `loaderRuns`,
+     *      `midLoadInvalidations`, `reloadsAfterSettle`,
+     *      `notifiesFired`, `notifiesSkippedByDiff`).
+     *    - `blockCache` — write/notify activity
+     *      (`setSnapshotCalls`, `setSnapshotDedupHits/Misses`,
+     *      `applySyncSnapshotCalls`, `applySyncSnapshotRejected`,
+     *      `notifies`).
+     *    - `queries` — per-query-name resolve timings keyed by full
+     *      name (e.g. `core.subtree`, `plugin:tasks/dueSoon`). Each
+     *      entry is a `TimingSnapshot` with `calls`, mean, p50/p95/p99,
+     *      min/max, and totalMs. Empty until a query runs.
+     *    - `db` — aggregate PowerSyncDb call timings split by method
+     *      (`getAll`, `getOptional`, `get`, `execute`, `writeTransaction`).
+     *      `writeTransaction` records full wall-clock for the tx; the
+     *      tx-internal SQL calls also count against their respective
+     *      buckets — so a single `mutate.X` typically registers one
+     *      `writeTransaction` sample plus several inner-SQL samples.
+     *
+     *  Plain counters are monotonic from the last `resetMetrics()` (or
+     *  Repo construction). Timing reservoirs hold the last 256 samples
+     *  for percentile estimation; their `calls` field is unbounded.
+     *
+     *  Each call returns a fresh frozen object so callers can keep two
+     *  snapshots and diff them.
+     *
+     *  Useful as:
+     *    - regression detection in production (`handlesWalked /
+     *      invalidations` should drop once the inverted-index lands;
+     *      `queries['backlinks.forBlock'].p95Ms` should drop once the
+     *      backlinks index lands),
+     *    - cold-start investigation (open a page, `repo.metrics()`,
+     *      see which queries dominated and how many SQL roundtrips
+     *      they incurred),
+     *    - in-app debug panels that surface latency distributions
+     *      without needing a Playwright + profiler harness. */
+    metrics(): Readonly<{
+        handleStore: Readonly<Record<string, number>>;
+        /** Live-state aggregates over the registered handle set: handle
+         *  count, dep-count percentiles, and the top-3 keys by dep count.
+         *  Pairs with `handleStore` counters — counters describe events
+         *  since the last reset, this describes the store right now. Use
+         *  the top-heavy list to spot resolvers that are over-registering
+         *  deps. */
+        handleStoreInventory: ReturnType<HandleStore['snapshotInventory']>;
+        blockCache: Readonly<Record<string, number>>;
+        queries: Readonly<Record<string, ReturnType<QueryMetrics['snapshot']>[string]>>;
+        db: ReturnType<DbMetrics['snapshot']>;
+        /** High-water mark across all `repo.tx` calls since the last reset.
+         *  Pairs with `db.writeTransaction.maxMs` to attribute outliers to a
+         *  concrete description (e.g. 'reproject ref-typed properties after
+         *  schema swap'). `description: null` means the slowest tx so far
+         *  was opened without a description. */
+        slowestTx: Readonly<{
+            description: string | null;
+            ms: number;
+        }>;
+        /** Bounded list of recent (description, ms) entries — the most
+         *  recent `TX_LOG_CAPACITY` writeTransactions across the Repo's
+         *  lifetime since the last reset. Lets a cold-start metrics dump
+         *  attribute every observed writeTransaction sample to a concrete
+         *  call site. Order is oldest-to-newest. */
+        txLog: ReadonlyArray<Readonly<{
+            description: string | null;
+            ms: number;
+        }>>;
+        reprojection: Readonly<{
+            calls: number;
+            schemasReprojected: number;
+            rowsScanned: number;
+            blocksUpdated: number;
+            msTotal: number;
+            skippedByMarker: number;
+        }>;
+    }>;
+    /** Zero every counter and reservoir in `repo.metrics()`. Use to
+     *  mark a baseline before measuring a discrete operation (e.g. a
+     *  benchmark iteration, a UI interaction in a soak test, or a
+     *  cold-start "open page → metrics" investigation). */
+    resetMetrics(): void;
+    /** Get a `Block` facade for `id`. Sync — does NOT load. Read access
+     *  on the returned facade (`block.data`, `block.peek()`, etc.) is gated
+     *  by what's in cache; call `block.load()` or `repo.load(id)` first
+     *  for guaranteed availability. The same `Block` instance is returned
+     *  on repeat calls so identity-based React keys / memo work. */
+    block(id: string): Block;
+    /** Load a row + (optionally) a neighborhood into the cache. Spec §5.2.
+     *
+     *    repo.load(id)                          → just the row
+     *    repo.load(id, {children: true})        → row + immediate children
+     *    repo.load(id, {ancestors: true})       → row + full parent chain
+     *    repo.load(id, {descendants: N})        → row + subtree clipped at
+     *                                              depth N (or whole tree
+     *                                              if N is omitted/falsy
+     *                                              for descendants:true)
+     *
+     *  Hydrates rows into the cache so subsequent `block.peek()` /
+     *  `block.data` calls succeed. Collection reactivity (children /
+     *  subtree handles) is owned by the HandleStore, not this loader —
+     *  use `repo.query.children({id}).load()` if you want a
+     *  handle-cached child-rows list with structural invalidation.
+     *
+     *  Concurrency note: this method does NOT use `BlockCache.dedupLoad`.
+     *  That helper keys by id only, which silently merged a plain
+     *  `repo.load(id)` with a concurrent `repo.load(id, {children: true})`
+     *  — the second caller would see the plain promise resolve and miss
+     *  the children. Inlining the load costs at most one extra row read
+     *  per concurrent caller; the cache's `setSnapshot` is
+     *  fingerprint-deduplicated so listeners don't fire twice. */
+    load(id: string, opts?: {
+        children?: boolean;
+        ancestors?: boolean;
+        descendants?: boolean | number;
+    }): Promise<BlockData | null>;
+    /** Async existence check — cache-first, falls back to a single SQL
+     *  hit. Soft-deleted rows count as MISSING here so create/restore
+     *  flows on the caller side get the consistent "not found" signal.
+     *  The cache holds tombstone snapshots after `tx.delete` (so peek
+     *  can show `deleted: true`); `hasSnapshot` alone would falsely
+     *  report a tombstoned row as existing, hence the `deleted` gate. */
+    exists(id: string): Promise<boolean>;
+    /** UI-visible "active" workspace pin — used by plugin hooks and
+     *  panels that need a default workspace when there's no other
+     *  context. `repo.tx` does NOT consult this; tx workspaces come from
+     *  the first write's row per spec §5.3. */
+    get activeWorkspaceId(): string | null;
+    setActiveWorkspaceId(workspaceId: string | null): void;
+    /** Toggle read-only mode. Wrapping the field write in a method
+     *  keeps call sites that come from inside React hooks lint-clean
+     *  (`react-hooks/immutability` flags direct property writes on
+     *  hook outputs). UI-state writes still pass through regardless of
+     *  this flag; UserPrefs writes pass through but stop uploading. */
+    setReadOnly(value: boolean): void;
+    /** Run a transactional session. Spec §3, §10. */
+    tx<R>(fn: (tx: Tx) => Promise<R>, opts: RepoTxOptions): Promise<R>;
+    /** Undo the most recent committed `repo.tx` for `scope`. Default
+     *  scope is `BlockDefault` (the cmd-Z target). Resolves to true if
+     *  an entry was popped + replayed, false if the stack was empty.
+     *  Replay opens its own `repo.tx` with `source = 'user'` so the
+     *  inverse syncs upstream just like the original write did (per the
+     *  spec's §7.3 + the follow-ups doc's "undo of a content edit
+     *  should sync the un-edit"). Throws `ReadOnlyError` in read-only
+     *  mode for scopes that cannot write locally — matches normal
+     *  `repo.tx` gating. */
+    undo(scope?: ChangeScope): Promise<boolean>;
+    /** Redo the most recently undone tx for `scope`. Same default + same
+     *  semantics as `undo`, mirrored. */
+    redo(scope?: ChangeScope): Promise<boolean>;
+    /** Shared `runTx` + processor-dispatch path. Used by both `tx`
+     *  (records on undo stack) and `_replay` (does not).
+     *
+     *  Storage-layer integrity errors are translated to user-domain
+     *  exceptions here so every caller — `repo.tx`, `repo.undo`,
+     *  `repo.redo` — surfaces the same shape. Currently:
+     *    - `alias_collision` RAISE → `ProcessorRejection('alias.collision',
+     *      …)` via the trigger on `block_aliases`.
+     *    - `parent_deleted` RAISE → `ParentDeletedError(parentId)` via the
+     *      trigger on `blocks` — kept as a typed error rather than a
+     *      ProcessorRejection because no toast surface is wired for it and
+     *      existing callers `instanceof`-check the class.
+     *  Listeners (`onUserError`) fire on translated ProcessorRejections
+     *  here so the toast layer sees collisions from undo/redo replay,
+     *  not just from `repo.tx` directly. */
+    private _runAndDispatch;
+    /** Replay an undo / redo entry. Opens a tx in the entry's scope and
+     *  raw-applies each (id → snap.before) (undo) or (id → snap.after)
+     *  (redo) via the engine-internal `applyRaw` primitive. Replays do
+     *  NOT push themselves onto the undo stack — the caller manages
+     *  stack motion (manager.pushRedo / manager.pushUndo) so the same
+     *  entry shuttles symmetrically between stacks. */
+    private _replay;
+    /** Dynamic dispatch — used by runtime-loaded plugins where the
+     *  TypeScript identity isn't available. `name` is the full mutator
+     *  name (e.g. `'tasks:setDueDate'` or `'core.indent'`). Args are
+     *  validated at the boundary via the mutator's argsSchema. */
+    run<R = unknown>(name: string, args: unknown): Promise<R>;
+    /** Dynamic query dispatch — `repo.query[name]` for runtime-loaded
+     *  plugins. Resolves the query, runs `.load()`, and returns the
+     *  result. The same `core.${name}` shortcut as the proxy applies. */
+    runQuery<R = unknown>(name: string, args: unknown): Promise<R>;
+    private resolveTypedBlockQuery;
+    /** Run a typed block query once. `workspaceId` is required: callers
+     *  that want the user's currently-active workspace use
+     *  `queryActiveWorkspace` instead — making the workspace explicit at
+     *  the call site prevents background flows / import runs from silently
+     *  mis-scoping on a workspace switch (PR #47 review). */
+    queryBlocks(query: TypedBlockQuery): Promise<BlockData[]>;
+    /** Subscribe to a typed block query. `workspaceId` is required: callers
+     *  that want the user's currently-active workspace use
+     *  `subscribeActiveWorkspace` instead. */
+    subscribeBlocks(query: TypedBlockQuery, listener: (rows: BlockData[]) => void): Unsubscribe;
+    /** Active-workspace shorthand for `queryBlocks`. Resolves
+     *  `activeWorkspaceId` at call time; if no workspace is active,
+     *  returns an empty list (mirrors the historical fallback behaviour
+     *  for the rare callers that legitimately want "whatever the user is
+     *  looking at right now"). Most non-UI code should NOT use this —
+     *  prefer the bare `queryBlocks` with an explicit workspaceId. */
+    queryActiveWorkspace(query: Omit<TypedBlockQuery, 'workspaceId'>): Promise<BlockData[]>;
+    /** Active-workspace shorthand for `subscribeBlocks`. Same caveat as
+     *  `queryActiveWorkspace`: the workspace is captured at subscription
+     *  time and does NOT re-resolve on later workspace switches. UI
+     *  surfaces that need switch-following behaviour should resubscribe
+     *  themselves when `activeWorkspaceId` changes (e.g. via
+     *  `useActiveWorkspaceId`). */
+    subscribeActiveWorkspace(query: Omit<TypedBlockQuery, 'workspaceId'>, listener: (rows: BlockData[]) => void): Unsubscribe;
+    /** Count non-deleted blocks in `workspaceId` whose `properties` map
+     *  has a value at `name`. Used by the property-schema editor to warn
+     *  the user before deleting a schema definition that's still in use.
+     *  Workspace defaults to the active one; missing workspace returns 0. */
+    countBlocksUsingProperty(name: string, workspaceId?: string): Promise<number>;
+    /** Update the data-layer registries from a FacetRuntime. Spec §8.
+     *  Decomposes into named rebuild steps (per user-defined-properties
+     *  §3); the same step set runs for full-runtime swaps and for the
+     *  per-facet `setRuntimeContributions` change path. Kernel mutators
+     *  must be present in the runtime if the caller wants them — pass
+     *  them in via the static-facet bundle the kernel ships. */
+    /** Read-only handle on the currently-installed FacetRuntime. Used by
+     *  non-React callers that need to consult facets at action-handler
+     *  time (e.g. `pickBlockDateAdapter` from a multi-select handler
+     *  where `useAppRuntime()` isn't available). Returns null before the
+     *  first `setFacetRuntime` call. */
+    get facetRuntime(): FacetRuntime | null;
+    setFacetRuntime(runtime: FacetRuntime): void;
+    /** Replace the runtime contribution bucket for `facet` keyed by
+     *  `sourceId`. Triggers a re-run of every rebuild step whose
+     *  declared inputs include this facet, plus per-facet listener
+     *  fan-out for React subscribers (e.g. usePropertySchemas).
+     *  No-op if no FacetRuntime has been installed yet — callers must
+     *  setFacetRuntime first. */
+    setRuntimeContributions<Input>(facet: Facet<Input, unknown>, sourceId: string, contributions: readonly Input[]): void;
+    /** Subscribe to changes on `_propertySchemas`. Fires when
+     *  `setFacetRuntime` rebuilds the schema map AND when
+     *  `setRuntimeContributions(propertySchemasFacet, ...)` updates the
+     *  user-data bucket. Used by `usePropertySchemas` so React rerenders
+     *  on user-schema add/edit/remove without a runtime swap. */
+    onPropertySchemasChange(listener: () => void): () => void;
+    /** Subscribe to changes on `_types`. Fires whenever the rebuild step
+     *  that owns `_types` re-runs — i.e. after `setFacetRuntime` AND
+     *  after `setRuntimeContributions(typesFacet, ...)` publishes into
+     *  the user-data bucket. Symmetric to `onPropertySchemasChange`.
+     *  Consumers (e.g. `createTypeBlock` waiting for `UserTypesService`
+     *  to publish a freshly-committed type-definition block) recheck
+     *  `repo.types` inside the listener; spurious firings are tolerated. */
+    onTypesChange(listener: () => void): () => void;
+    /** Subscribe to changes on the merged `propertyEditorOverrides` map
+     *  (currently driven exclusively by `propertyEditorOverridesFacet`,
+     *  but exposed as a Repo-level event so future runtime-contribution
+     *  paths layer on without changing the consumer surface). */
+    onPropertyEditorOverridesChange(listener: () => void): () => void;
+    /** Subscribe to changes on the value-preset map. */
+    onValuePresetsChange(listener: () => void): () => void;
+    /** Subscribe to user-surfaceable errors thrown from `repo.tx`
+     *  (currently `ProcessorRejection` from same-tx processors). The
+     *  data layer fires; the UI layer (e.g. toast) listens. Returns an
+     *  unsubscribe fn. Listener exception isolation is handled by
+     *  `CallbackSet.notify` — one bad listener can't poison the others
+     *  or break the underlying `repo.tx` error propagation. */
+    onUserError(listener: (error: ProcessorRejection) => void): () => void;
+    /** Translate a parsed alias-collision RAISE into a fully-populated
+     *  `ProcessorRejection`. Runs after the user tx has already rolled
+     *  back, so `block_aliases` is back to the pre-tx state — the
+     *  conflicting claimant is still indexed and one PK lookup away. */
+    private buildAliasCollisionRejection;
+    snapshotTypeRegistries(): TypeRegistrySnapshot;
+    private reprojectRefTypedProperties;
+    /** Defer reprojection off the cold-start critical path. The first
+     *  cold start on a fresh device (or one whose `client_schema_state`
+     *  was wiped) has no markers in place yet, so reprojection scans
+     *  every block whose properties_json mentions any ref-typed name —
+     *  ~1.4 s on a real graph, holding the SQLite connection and
+     *  blocking every read issued during page render. The references
+     *  processor handles every write that lands during the deferral
+     *  window, so projection correctness is preserved.
+     *
+     *  Browser path: `requestIdleCallback` with a 2 s safety timeout —
+     *  we want to wait until the main thread is idle, but never longer
+     *  than that (so a busy session still gets its catch-up scan).
+     *  Test / Node path: `setTimeout(0)` so vitest fake timers can
+     *  advance the call deterministically; `requestIdleCallback` is not
+     *  defined under jsdom / Node. */
+    private scheduleReprojection;
+    /** Lazy load the per-name marker set on first call, then keep it
+     *  in-memory. One SQL round-trip per Repo lifetime. */
+    private loadReprojectionMarkers;
+    private setReprojectionMarker;
+    private clearReprojectionMarker;
+    /** Test escape hatch — drop the in-memory marker mirror so the next
+     *  reprojection re-reads from `client_schema_state`. Used by tests
+     *  that mutate the table out-of-band to simulate cross-session state. */
+    __resetReprojectionMarkerCache(): void;
+    private _addTypeInTx;
+    private _removeTypeInTx;
+    /** Strict: throws `BlockNotFoundForTypeError` if `blockId` is missing
+     *  or tombstoned at write time. Use when the caller's correctness
+     *  depends on the tag actually landing (orchestration / fan-out
+     *  paths). For the lenient variant that silently no-ops on a missing
+     *  block, see `addTypeInTxLenient` and (in-tx) the dedicated lenient
+     *  entry points. */
+    addType(blockId: string, typeId: string, initialValues?: Readonly<Record<string, unknown>>): Promise<void>;
+    /** Strict in-tx variant. Throws `BlockNotFoundForTypeError` if the
+     *  target block is missing or tombstoned. The default for orchestration
+     *  code; pair with the lenient variant only when racing a concurrent
+     *  delete is legitimate (sync-apply / processor paths). */
+    addTypeInTx(tx: Tx, blockId: string, typeId: string, initialValues?: Readonly<Record<string, unknown>>, snapshot?: TypeRegistrySnapshot): Promise<void>;
+    /** Lenient in-tx variant — silently no-ops if the target block is
+     *  missing or tombstoned. Reserved for sync-apply / processor paths
+     *  that may legitimately observe a concurrent delete between
+     *  pre-tx state and tx-start. New orchestration code should prefer
+     *  `addTypeInTx` (strict) so a footgun like the Roam-isa adoption
+     *  bug (PR #47) can't be expressed. */
+    addTypeInTxLenient(tx: Tx, blockId: string, typeId: string, initialValues?: Readonly<Record<string, unknown>>, snapshot?: TypeRegistrySnapshot): Promise<void>;
+    removeType(blockId: string, typeId: string): Promise<void>;
+    removeTypeInTx(tx: Tx, blockId: string, typeId: string): Promise<void>;
+    toggleType(blockId: string, typeId: string): Promise<void>;
+    setBlockTypes(blockId: string, typeIds: readonly string[]): Promise<void>;
+    /** Constructor-time rebuild step factory. Each step closes over
+     *  `this`; runs at full setFacetRuntime AND when its inputs' runtime
+     *  contributions change. Order matters: types runs before
+     *  propertySchemas (the merge folds in type-lifted schemas);
+     *  propertySchemas runs before query swap if a future step ever
+     *  needs it. */
+    private _makeRebuildSteps;
+    /** Replace the query registry, bumping the per-name generation
+     *  counter for every name whose registered Query instance changed
+     *  (including newly-added and removed names). This invalidates the
+     *  handle-store keys for those queries so subsequent dispatch
+     *  produces fresh `LoaderHandle`s bound to the new resolvers. */
+    private swapQueries;
+    /** Wait until the post-commit processor framework has nothing
+     *  pending — useful in tests + scripted scenarios that need
+     *  deterministic ordering after a `repo.tx` resolves. Does NOT
+     *  advance timers; jobs scheduled with `delayMs` only enter the
+     *  pending set when the timer fires. */
+    awaitProcessors(): Promise<void>;
+    /** Test-only escape hatch retained for stage-level tests that wire
+     *  specific processor sets without a FacetRuntime. */
+    __setProcessorsForTesting(processors: ReadonlyArray<AnyPostCommitProcessor>): void;
+    /** Test-only mirror of `__setProcessorsForTesting` for same-tx
+     *  processors. Used by stage-level tests that need to exercise
+     *  the in-tx runner without going through the facet runtime. */
+    __setSameTxProcessorsForTesting(processors: ReadonlyArray<AnySameTxProcessor>): void;
+    /** Build the dispatcher closure for a mutator name. Resolution order:
+     *    1. literal `name` (kernel full-name like `'core.indent'`,
+     *       plugin full-name like `'tasks:setDueDate'`)
+     *    2. `'core.${name}'` (so `repo.mutate.indent` resolves to
+     *       `'core.indent'` even though the registry key is full-prefixed)
+     *  Throws `MutatorNotRegisteredError` if neither matches. */
+    private dispatchMutator;
+    /** Internal: register an array of mutators into the registry by name.
+     *  Used by the constructor's `registerKernel: true` path. */
+    private registerMutators;
+    /** Test-only escape hatch retained for stage 1.3 carryover tests
+     *  that wired specific mutator sets without a FacetRuntime. New
+     *  tests should prefer `setFacetRuntime` or the
+     *  `registerKernel: false` constructor flag plus `setFacetRuntime`. */
+    __setMutatorsForTesting(mutators: ReadonlyArray<AnyMutator>): void;
+    /** Build the dispatcher closure for a query name. Same resolution
+     *  order as `dispatchMutator`: literal name first, then
+     *  `'core.${name}'`. The returned closure validates args via the
+     *  query's `argsSchema`, then `getOrCreate`s an identity-stable
+     *  `LoaderHandle` keyed by `(queryName, args)`. The loader wraps the
+     *  query's `resolve` with a `QueryCtx` that forwards `depend` to the
+     *  handle's `ResolveContext` and exposes `db` / `repo` /
+     *  `hydrateBlocks`. */
+    private dispatchQuery;
+    /** Test-only escape hatch parallel to `__setMutatorsForTesting`.
+     *  Bypasses the FacetRuntime so unit tests can register a single
+     *  query without standing up a full kernel runtime. Routes through
+     *  `swapQueries` so generation bookkeeping stays consistent with
+     *  the production `setFacetRuntime` path. */
+    __setQueriesForTesting(queries: ReadonlyArray<AnyQuery>): void;
+}
+export {};
+//# sourceMappingURL=repo.d.ts.map