@bitcobblers/wod-wiki-wql 0.44.2159 → 0.45.2166

package/dist/index.d.ts

@@ -2,8 +2,10 @@ import { LRParser } from '@lezer/lr';
 import { LanguageSupport, HighlightStyle, LRLanguage } from '@codemirror/language';
 import { Completion, CompletionContext, CompletionResult } from '@codemirror/autocomplete';
 import { Extension } from '@codemirror/state';
-import { SummaryCoverage, BlockIndexRow, Note, EventRecord, PageNote, Page, AnalyticsDataPoint, NotebookId, ResultOrigin, StoredOutputStatement, NoteBlockChange } from '@bitcobblers/wod-wiki-core';
-export { DEFAULT_NOTEBOOK_SLUGS, DefaultNotebookSlug, NotebookId, SYSTEM_DEFAULT_OUTPUT_UNIT, UnitConversionError, convertViaCatalog, dimensionKeyOf, isNoteEditable, lookupUnit, notebookSlugFromId, systemDefaultUnit, toNotebookId } from '@bitcobblers/wod-wiki-core';
+import { SummaryCoverage, BlockIndexRow, Note, EventRecord, PageNote, Page, NotePlacement, AnalyticsDataPoint, FeedId, NotebookId, NotebookOrigin, ResultOrigin, StoredOutputStatement, NoteBlockChange } from '@bitcobblers/wod-wiki-core';
+export { DEFAULT_NOTEBOOK_SLUGS, DefaultNotebookSlug, FeedId, NotebookId, NotebookOrigin, SYSTEM_DEFAULT_OUTPUT_UNIT, UnitConversionError, convertViaCatalog, dimensionKeyOf, isNoteEditable, lookupUnit, notebookSlugFromId, systemDefaultUnit, toNotebookId } from '@bitcobblers/wod-wiki-core';
+import { IEffort } from '@bitcobblers/wod-wiki-lang';
+export { IEffort } from '@bitcobblers/wod-wiki-lang';
 
 /**
  * WQL vocabulary — the single owner of the WQL dictionary: aggregators,
@@ -38,8 +40,11 @@ declare const WQL_TAG_KEYS: readonly ["domain", "format", "equipment", "quality"
 type WqlTagKey = (typeof WQL_TAG_KEYS)[number];
 /** Content-plane keys — meaningful only on find:/rows:. On an aggregate
  *  they are a category error (a fact row has no note text or source);
- *  every other non-structural key is a candidate custom dimension. */
-declare const WQL_CONTENT_ONLY_KEYS: readonly ["type", "text", "has", "source", "catalog", "notebook"];
+ *  every other non-structural key is a candidate custom dimension.
+ *  `catalog:` is retired (ticket 08 — the notebook plane and the
+ *  `notebook:` filter replace it) and `has:` was removed from the
+ *  declared vocabulary: it had no executor and the composer withheld it. */
+declare const WQL_CONTENT_ONLY_KEYS: readonly ["type", "text", "source", "notebook", "contributes"];
 /** Filter keys the effort registry can resolve (runFindEffort) — anything
  *  else on find:effort is ignored and reported as an advisory. */
 declare const WQL_EFFORT_FILTER_KEYS: readonly ["effort", "discipline", "intensity", "origin", "text"];
@@ -67,24 +72,32 @@ type WqlIntensityTier = (typeof WQL_INTENSITY_TIERS)[number];
  *  rollups are computed at read time via the .rollup suffix, never stored. */
 declare const WQL_GRAINS: readonly ["summary", "event"];
 type WqlGrain = (typeof WQL_GRAINS)[number];
-/** Content-discovery query targets (find:<target>). */
-declare const WQL_FIND_TARGETS: readonly ["note", "block", "effort", "session", "segment", "event"];
+/** Content-discovery query targets (find:<target>). The four container
+ *  planes (ticket 08) are first-class targets: `:notebook{}` lists the
+ *  notes across every notebook, `:page{}` the page placements, `:tag{}` the tags,
+ *  `:equipment{}` the equipment notes — the latter two resolve to notes. */
+declare const WQL_FIND_TARGETS: readonly ["note", "block", "effort", "session", "segment", "event", "notebook", "page", "tag", "equipment"];
 type WqlFindTarget = (typeof WQL_FIND_TARGETS)[number];
-/** Canonical source filter values: the allowed storage locations (the
- *  former `collections` spelling is retired — renamed to feeds; storage
- *  identities keep their `collection:` prefixes). Seed corpus locations
- *  joined the note plane: prebuilt dashboards, the effort library and the
- *  equipment library. */
-declare const WQL_SOURCE_VALUES: readonly ["journal", "feeds", "guides", "playground", "dashboards", "efforts", "equipment"];
+/** Canonical source filter values: the allowed storage locations. Corpus-
+ *  delivered notes carry `notebook:<slug>` source ids, so `notebooks` spans
+ *  the seeded notebooks. Seed corpus locations joined the note
+ *  plane: prebuilt dashboards, the effort library and the equipment library. */
+declare const WQL_SOURCE_VALUES: readonly ["journal", "notebooks", "guides", "playground", "dashboards", "efforts", "equipment"];
 type WqlSourceValue = (typeof WQL_SOURCE_VALUES)[number];
 /** Colon source heads — the unprefixed `:<head>` names. Find targets map
- *  1:1 to the content planes; journal/feed(s)/catalog(s)/playground are
- *  source-scoped note heads (they parse to target 'note' plus an injected
- *  `source:` filter). */
-declare const WQL_SOURCE_HEADS: readonly ["note", "notes", "block", "effort", "session", "segment", "event", "journal", "notebook", "notebooks", "feed", "feeds", "catalog", "catalogs", "playground", "dashboard"];
+ *  1:1 to the content planes; journal/notebooks/playground are source-scoped
+ *  note heads (they parse to target 'note' plus an injected `source:`
+ *  filter). `:notebook{}` / `:page{}` / `:tag{}` / `:equipment{}` are the
+ *  container planes (targets of their own name). `:notebook{}` stays a NOTE
+ *  plane (ticket 05): it returns every notebook's notes, delegating to the
+ *  note executor. */
+declare const WQL_SOURCE_HEADS: readonly ["note", "notes", "block", "effort", "session", "segment", "event", "journal", "notebook", "notebooks", "playground", "page", "tag", "equipment", "dashboard"];
 type WqlSourceHead = (typeof WQL_SOURCE_HEADS)[number];
 /** Storage scope a source-scoped note head binds (undefined = plain target). */
 declare const WQL_SOURCE_HEAD_SCOPES: Readonly<Record<string, WqlSourceValue>>;
+/** Note-head aliases — `:<head>` parses to target 'note' with NO injected
+ *  scope (the note plane is inclusive; authored filters narrow it). */
+declare const WQL_NOTE_HEAD_ALIASES: readonly ["notes"];
 /** Type-alias note heads — `:<head>` parses to target 'note' plus an injected
  *  `type:` filter (no storage scope, so the head never narrows by source).
  *  `:dashboard` is the canonical member: dashboards are notes typed
@@ -113,8 +126,11 @@ type WqlStandardDataset = (typeof WQL_STANDARD_DATASETS)[number];
  *  stay addressable programmatically via hand-built ASTs. */
 declare const WQL_RESULT_PLANES: readonly ["segment", "system", "load", "event", "compiler", "completion", "analytics", "wellness"];
 type WqlResultPlane = (typeof WQL_RESULT_PLANES)[number];
-/** Content-specific filter keys (beyond the analytics tag keys). */
-declare const WQL_CONTENT_FILTER_KEYS: readonly ["type", "text", "has", "source", "catalog", "notebook", "domain", "format", "equipment", "quality", "intent", "effort", "discipline", "intensity", "grade", "note", "page", "origin", "grain", "metric", "block", "result", "tags"];
+/** Content-specific filter keys (beyond the analytics tag keys). `catalog:`
+ *  and `has:` are gone (ticket 08): `catalog:` → `notebook:`, `has:` had no
+ *  executor. `contributes:` is the tag plane's contribution filter — a
+ *  contribution is never a `tags:` label filter. */
+declare const WQL_CONTENT_FILTER_KEYS: readonly ["type", "text", "source", "notebook", "page", "contributes", "domain", "format", "equipment", "quality", "intent", "effort", "discipline", "intensity", "grade", "note", "page", "origin", "grain", "metric", "block", "result", "tags"];
 type WqlContentFilterKey = (typeof WQL_CONTENT_FILTER_KEYS)[number];
 /**
  * Composer source planes (issue #838, decision #836): the single `source`
@@ -125,8 +141,8 @@ type WqlContentFilterKey = (typeof WQL_CONTENT_FILTER_KEYS)[number];
  * deliberately absent — it needs new grammar/engine semantics and is
  * deferred to its own ticket.
  */
-declare const WQL_SOURCES: readonly ["note", "block", "effort", "session", "segment", "event"];
-type WqlSource = (typeof WQL_SOURCES)[number];
+declare const WQL_SOURCES: readonly ["note", "block", "effort", "session", "segment", "event", "notebook", "page", "tag", "equipment"];
+type WqlSource = WqlFindTarget;
 /** Rollup periods the aggregate grammar accepts (wql.ts: N > 1, unit d|w). */
 declare const WQL_ROLLUP_PERIODS: readonly ["2w", "4w"];
 type WqlRollupPeriod = (typeof WQL_ROLLUP_PERIODS)[number];
@@ -1008,7 +1024,16 @@ interface NoteQueryStore {
  * ORs; `negate` excludes any row matching any value.
  */
 type WqlDomainPredicate = {
-    field: 'id' | 'noteId' | 'type' | 'catalog' | 'source' | 'tags' | 'effort';
+    field: 'id' | 'noteId' | 'type' | 'source' | 'tags' | 'effort';
+    values: string[];
+    negate?: boolean;
+}
+/** Typed-tag narrow — notes carrying a tag of this type and one of these
+ *  labels (pushes down through the tags by-type index). Mirror of the
+ *  storage wire's typedTag predicate (ticket 08). */
+ | {
+    field: 'typedTag';
+    tagType: string;
     values: string[];
     negate?: boolean;
 } | {
@@ -1023,13 +1048,13 @@ type WqlDomainPredicate = {
     field: 'page';
     value: boolean;
 }
-/** The :note default page-exclusion stage (notes plan only). `feeds`
- *  = an authored feed source clause rides along: true drops literal
+/** The :note default page-exclusion stage (notes plan only). `nonPages`
+ *  = an authored notebook source clause rides along: true drops literal
  *  type 'page' rows; false drops isPage rows (page-like kinds or page:/
  *  guides: source prefixes on non-note kinds). */
  | {
     field: 'defaultNotes';
-    feeds: boolean;
+    nonPages: boolean;
 } | {
     field: 'sourceFence';
 };
@@ -1072,21 +1097,8 @@ interface BlockQueryStore {
         limit?: number;
     }): Promise<WqlDomainReadResult | undefined>;
 }
-/** Pure effort model interface for `:effort` queries. */
-interface IEffort {
-    id: string;
-    slug: string;
-    label: string;
-    aliases: string[];
-    baseAttributes: {
-        met?: number;
-        discipline?: string;
-        intensityTier?: string;
-        [key: string]: unknown;
-    };
-    registrySource?: 'bundled' | 'user' | string;
-    [key: string]: unknown;
-}
+/** Effort definition records for `:effort` queries — the language package's
+ *  IEffort (single authoritative definition; re-exported above). */
 interface EffortQueryStore {
     getAllEfforts(): Promise<IEffort[]>;
 }
@@ -1120,19 +1132,25 @@ interface QueryServiceStores {
     blockEffortsStore?: {
         getAllFromIndex(index: string, key: string): Promise<any[]>;
     };
-    /** Serves tag records (`tags` store). */
+    /** Serves tag records (`tags` store). `getAll` backs the `:tag{}` plane;
+     *  absent → the plane resolves to no rows. */
     tagsStore?: {
         getAllFromIndex(index: string, key: string): Promise<any[]>;
+        getAll?(): Promise<any[]>;
     };
     /** Serves note-tag junction rows (`note_tags` store). */
     noteTagsStore?: {
         getAllFromIndex(index: string, key: string): Promise<any[]>;
     };
     /** Canonical page_notes junction reads for container resolution — a
-     *  note's parent Page wins over a standalone Note container. */
+     *  note's parent Page wins over a standalone Note container. The two
+     *  getAll* seams back the `:page{}` placement plane; absent → the plane
+     *  resolves to no rows. */
     pageStore?: {
         getNotePages(noteId: string): Promise<PageNote[]>;
         getPage(pageId: string): Promise<Page | undefined>;
+        getAllPages?(): Promise<Page[]>;
+        getAllLinks?(): Promise<PageNote[]>;
     };
     /** Batched relation reads for the hydration paths (containers, run
      *  tags) — one bundle per distinct note id instead of a page/tag read
@@ -1173,22 +1191,37 @@ interface QueryServiceStores {
  * Fully inverted dependencies: zero IndexedDB/storage module-level imports.
  */
 
-/** Extract the catalog directory id from a Note or BlockIndexRow.
- *  Uses explicit `catalog` when present; falls back to parsing `sourceId`
- *  (stripping `collection:`/`feed:` prefixes and `feeds/` path components) or `noteId`.
- *  Exported so host mappers (Entry derivation) carry the exact field the
- *  `catalog:` filter matches — presentation catalogs must not diverge. */
-declare function catalogOfItem(item: {
-    id?: string;
-    noteId?: string;
-    sourceId?: string;
-    catalog?: string;
-}): string | undefined;
-
+/** The notebook slug a `notebook:<slug>[/<item>]` source id names — the
+ *  first path segment; README/root landings (`notebook:<slug>` bare or
+ *  `notebook:_root`) name no item. UUID and non-notebook source ids name
+ *  no notebook. */
+declare function notebookSlugOfSourceId(sourceId: string | undefined): string | undefined;
+/**
+ * The feed that delivered a note — the resolver's feed answer.
+ *
+ * Read from the note's OWN feed stamp (`feedSourceId`), never from the seed
+ * stamps (`seedOrigin`, `seedVersion`, `seedChunkId`): a note that no feed
+ * delivered has no feed, whatever its seed stamps say. A feed id and the
+ * source id of the same registered source agree, so the answer names the
+ * registered feed the note arrived from.
+ */
+declare function feedOfItem(item: {
+    feedSourceId?: string | null;
+}): FeedId | undefined;
 /**
  * Resolve the canonical `notebook/{slug}` container for any Note or BlockIndexRow.
- * Unifies explicit `notebookId`, default notebooks (`notebook/journal`, `notebook/playground`,
- * `notebook/guides`), `notebook:{slug}` tags, and seed catalogs (`notebook/{catalog}`).
+ *
+ * Fallback precedence (first match wins), shared by every consumer — the WQL
+ * query layer, the host entry mapper, and the storage projections:
+ *   1. explicit `notebookId` (user-created notebooks),
+ *   2. the `notebook:{slug}` tag convention (user notebook membership),
+ *   3. the corpus path (`markdown/<family>/…` sourcePath),
+ *   4. the source-id prefix (`notebook:`, `guides:`, `playground`,
+ *      and the `efforts`/`equipment`/`dashboards` corpus literals),
+ *   5. the journal fallback.
+ * Tiers 3 and 4 agree for every corpus note: the seed writer
+ * (`seedNoteSourceId`/`chunkIdFor`) derives the sourceId from the same path
+ * the importer stamps as `sourcePath`.
  */
 declare function notebookOfItem(item: {
     id?: string;
@@ -1197,27 +1230,62 @@ declare function notebookOfItem(item: {
     type?: string;
     seedOrigin?: string;
     seedChunkId?: string;
+    feedOrigin?: string;
+    feedSourceId?: string;
     sourcePath?: string;
-    catalog?: string;
     notebookId?: string;
     tags?: readonly string[];
 }): NotebookId | undefined;
-/** Match a single row against one source filter value. The `journal` kind matches
- *  rows with no sourceId, the literal 'journal', or UUID / journal/date lineage
- *  pointing to the original note. Lineage also passes corpus exclusions below.
- *  The feed / guide kinds match
- *  rows whose sourceId starts with the kind (storage identities keep their
- *  `collection:`/`page:collection:` prefixes — only the query vocabulary
- *  was renamed). A `kind:id` literal matches the
- *  exact id. `playground` matches the playground intake's sourceId convention
+/**
+ * Who owns the notebook a row resolves to — the editability key (ticket 05).
+ * Pure over the row's own fields, and exact for every reachable state:
+ *   - explicit `notebookId` / `notebook:` tag membership → `'user'` (moves
+ *     into feed-delivered notebooks are forbidden and the importer never
+ *     stamps either field, so this tier is always user-managed),
+ *   - corpus path or feed/corpus sourceId shapes → `'feed'`
+ *     (the delivering feed wrote these rows; guides included — the core
+ *     feed delivers the canvas),
+ *   - the playground and journal fallbacks → `'default'`.
+ * A user-owned copy (clone) keeps its provenance stamps but resolves through
+ * tier 1, so it is editable while its origin stays visible.
+ */
+declare function notebookOriginOfItem(item: Parameters<typeof notebookOfItem>[0]): NotebookOrigin | undefined;
+/**
+ * Storage-identity shape per WQL source kind — THE one table of `sourceId`
+ * prefixes and exact literals. The JS residual filter (`sourceMatches`) and
+ * the storage wire's SQL projection (`sourceKindSql` in
+ * @bitcobblers/wod-wiki-storage) both derive from this table, so the two
+ * planes cannot disagree, and the source-id tier of {@link notebookOfItem}
+ * agrees with both by construction. `journal` is absent on purpose: it is
+ * the resolver's fallback decision, materialized as the computed `journal`
+ * column, not a sourceId shape.
+ */
+declare const SOURCE_ID_SHAPES: Readonly<Record<string, {
+    /** sourceIds exactly equal to one of these match the kind. */
+    exact?: readonly string[];
+    /** sourceIds starting with one of these match the kind. */
+    prefixes?: readonly string[];
+    /** Legacy rows that predate the sourceId convention match via note `type`. */
+    legacyType?: string;
+}>>;
+/** The storage-identity shape for a WQL source kind (aliases resolved), or
+ *  undefined for kinds that are not pure sourceId shapes (`journal`, `all`,
+ *  plain sourceId literals). The storage wire's SQL
+ *  projection reads the same accessor. */
+declare function sourceShape(kind: string): (typeof SOURCE_ID_SHAPES)[string] | undefined;
+/** Match a single row against one source filter value. The `journal` kind is
+ *  the resolver's own answer: a row journals exactly when
+ *  {@link notebookOfItem} places it in `notebook/journal` — no sourceId
+ *  identity, no corpus path, no notebookId, no `notebook:` tag (see
+ *  {@link isJournalRow} for the fallback's shape exclusions).
+ *  The feed / guide / page / playground / corpus kinds read the shared
+ *  {@link SOURCE_ID_SHAPES} table — the same sourceId prefixes/exact literals
+ *  the storage wire's SQL projection is built from. A `kind:id` literal matches
+ *  the exact id. `playground` matches the playground intake's sourceId convention
  *  and, on the note plane, legacy rows typed 'playground' (playground pages
  *  saved before the sourceId convention existed — their sourceId is absent).
  *  `all` spans exactly the WQL source domain plus sourceless rows — identical
- *  to the source fence. `journal` rejects the rest of the seed corpus: rows
- *  with seed provenance (importer stamps, or surviving seedChunkId /
- *  markdown/ sourcePath / catalog on legacy user-edited rows whose
- *  seedOrigin flipped to 'user') and typed dashboards never journal — a user
- *  journal note carries none of those markers. Exported so host mappers
+ *  to the source fence. Exported so host mappers
  *  classify result rows with the exact predicate the `source:` filter
  *  applies. */
 declare function sourceMatches(item: {
@@ -1227,9 +1295,11 @@ declare function sourceMatches(item: {
     type?: string;
     seedOrigin?: string;
     seedChunkId?: string;
+    feedOrigin?: string;
+    feedSourceId?: string;
     sourcePath?: string;
-    catalog?: string;
     notebookId?: string;
+    tags?: readonly string[];
 }, kind: string): boolean;
 interface FindQueryResult {
     parsed: ParsedFindQuery;
@@ -1248,13 +1318,18 @@ interface FindQueryResult {
      *  page_notes junction links one, else the standalone Note. Present only
      *  when a pageStore is injected and notes were matched. */
     containers?: Record<string, NoteContainer>;
+    /** Every page a matched note is placed on, keyed by note id — the
+     *  many-to-many membership itself. `containers` is the deterministic
+     *  primary projection of this map. Present only when a pageStore or
+     *  relationStore is injected and notes were matched. */
+    placements?: Record<string, NotePlacement[]>;
     stages: {
         selected: number;
         matched: number;
     };
 }
 /** Highest-container link for a matched note (parent Page wins). `slug` and
- *  `date` route app URLs (/p/:slug, /journal/:date). Core Page has no type —
+ *  `date` route app URLs (/page/:slug, /day/:date). Core Page has no type —
  *  the parent is never classified by the note's kind. */
 type NoteContainer = {
     kind: 'page';
@@ -1287,6 +1362,8 @@ interface PipelineResult {
     runs?: RowsRun[];
     /** Highest container per note id (see FindQueryResult.containers). */
     containers?: Record<string, NoteContainer>;
+    /** Every page a matched note is placed on (see FindQueryResult.placements). */
+    placements?: Record<string, NotePlacement[]>;
     unit?: string;
     chart?: PipelineSink;
     error?: string;
@@ -1414,19 +1491,26 @@ declare class QueryService {
      * time filters.
      */
     runFind(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
-    /** Highest container per note id: the parent Page from the canonical
-     *  page_notes junction (first link by position) wins; a note with no page
-     *  link stays a standalone Note container. Batched when a relationStore
-     *  is injected — one bundle read per run instead of a link/page read per
-     *  matched note. */
-    private containersForNotes;
+    /** The container projection and the full placement set per note id.
+     *
+     *  The container is the parent Page from the canonical page_notes junction
+     *  (the primary placement wins); a note with no page link stays a
+     *  standalone Note container. Batched when a relationStore is injected —
+     *  one bundle read per run instead of a link/page read per matched note.
+     *
+     *  The same read resolves EVERY page the note is placed on: the junction
+     *  is many-to-many, so the container is a projection of that set, not the
+     *  set itself. */
+    private containersAndPlacements;
     private hydrateBlocks;
     /**
      * Execute a :block query against the derived block_index store.
      */
     runFindBlock(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
     /**
-     * Execute a :effort query against the effort registry.
+     * Execute a :effort query: the registry is the filter plane (discipline,
+     * intensity, origin, text), the note plane is the result plane — matched
+     * projections resolve to their owning definition notes.
      */
     runFindEffort(parsed: ParsedFindQuery): Promise<FindQueryResult>;
     run(parsed: AnyParsedQuery, options?: QueryOptions): Promise<QueryResult>;
@@ -1491,10 +1575,43 @@ declare class QueryService {
     /** Resolve matching note IDs for a canonical typed tag (e.g. equipment:kettlebell). */
     private getNoteIdsForTypedTag;
     /**
-     * Find catalogs: identifies catalogs whose member notes (or catalog landing
-     * notes) match the authored criteria (effort, tags, text, typed tags, etc.).
+     * Execute a :notebook query (ticket 08) — the notebook plane is a NOTE
+     * plane (ticket 05 semantics preserved): bare `:notebook{}` returns the
+     * notes of every notebook — journal, playground, defaults, user-created,
+     * feed-delivered. `notebook:{slug}` narrows to members of those
+     * notebooks and `!notebook:` excludes them; the result shape never
+     * changes with polarity, and container criteria (tags:, effort:, typed
+     * tags, text:) narrow the members exactly like the note plane — this
+     * delegates to it. The notebook CONTAINER listing (the /notebooks
+     * management surface) is the app's NotebookService model, not WQL rows.
+     */
+    runFindNotebook(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    /**
+     * Execute a :page query (ticket 08) — the placement plane. Results are
+     * the placed notes; `placements` carries every page each note sits on
+     * (many-to-many) and `containers` the primary projection. `page:{slug}`
+     * (or a `YYYY-MM-DD` date, or a page id) narrows the placements.
+     */
+    runFindPage(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    /**
+     * Execute a :tag query (ticket 08) — the tag plane. Every tag record
+     * surfaces as one synthetic note row, so results are notes end to end.
+     * `tag:{label}` narrows; `type:` narrows by the tag's configured type;
+     * `contributes:` narrows by what a tag contributes (`metric`,
+     * `metric:<type>`, `tag:<slug>`, `function:<name>`) — a contribution is
+     * exposed here, never as a `tags:` label filter. The synthetic row's body
+     * summarizes the contributions so `text:` reaches them too.
+     */
+    runFindTag(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
+    /**
+     * Execute an :equipment query (ticket 08) — the equipment plane. Results
+     * are the equipment notes (the equipment notebook's members, typed
+     * 'equipment' rows included). `equipment:{label}` narrows by the
+     * equipment typed tag ("every equipment note tagged kettlebell" is
+     * `:equipment{equipment:kettlebell}`); `tags:` and `text:` narrow like
+     * the note plane.
      */
-    private runFindCatalog;
+    runFindEquipment(parsed: ParsedFindQuery, options?: FindOptions): Promise<FindQueryResult>;
 }
 
 /**
@@ -1569,6 +1686,8 @@ interface DocumentOutput {
     efforts?: unknown[];
     /** Highest-container page/note links keyed by note id. */
     containers?: Record<string, NoteContainer>;
+    /** Every page a matched note is placed on, keyed by note id. */
+    placements?: Record<string, NotePlacement[]>;
     /** Session run cards (find:session / session-source pipelines). */
     runs?: RowsRun[];
     /** Terminal chart sink of a pipeline output (renderer dispatch). */
@@ -1587,6 +1706,7 @@ interface FamilyRunPayload {
     blocks?: BlockIndexRow[];
     efforts?: unknown[];
     containers?: Record<string, NoteContainer>;
+    placements?: Record<string, NotePlacement[]>;
     runs?: RowsRun[];
     unit?: string;
     chart?: PipelineSink;
@@ -1816,6 +1936,38 @@ declare function projectEventToFacts(record: EventRecord): AnalyticsDataPoint[];
  */
 declare function eventsToStoredLogs(events: readonly EventRecord[]): StoredOutputStatement[];
 
+/**
+ * Notebook vocabulary migration (ticket 12) — the pure rewrite from the
+ * retired collection/feed wire identities to the notebook vocabulary.
+ *
+ * The retired spellings persist in older IndexedDB/SQL rows and checkpoints:
+ *   - chunk ids `collection.<slug>` / `feed.<slug>` → `notebook.<slug>`
+ *   - sourcePaths `markdown/collections/…` / `markdown/feeds/…` → `markdown/notebooks/…`
+ *   - sourceIds `collection:<slug>[/<item>]`, `feed:feeds/<slug>/<rest>`,
+ *     `page:collection:<slug>` → `notebook:<slug>[/<item>]`, `page:<slug>`
+ *   - the retired `catalog` note field is dropped; note `type: 'feed'` folds
+ *     into `'note'` (a note in a notebook is one kind).
+ *
+ * Pure and idempotent: already-migrated values pass through unchanged, so
+ * callers may run the migration on every boot and persist only what changed.
+ */
+/** Rewrite a retired chunk id; anything else passes through. */
+declare function migrateLegacyChunkId(chunkId: string): string;
+/** Rewrite a retired corpus path; anything else passes through. */
+declare function migrateLegacySourcePath(path: string): string;
+/** Rewrite a retired sourceId; anything else passes through. */
+declare function migrateLegacySourceId(sourceId: string): string;
+/** Rewrite a retired block routeId (`feeds/<slug>/<date>/<item>` or
+ *  `<catalog>/<item>`) to the notebook form `<slug>[/<date>]/<item>`;
+ *  anything else passes through. */
+declare function migrateLegacyRouteId(routeId: string): string;
+/** A note/block-index row (or any record carrying the retired fields) with
+ *  the notebook vocabulary applied. Idempotent; returns the input record
+ *  unchanged (same reference) when nothing migrates. */
+declare function migrateLegacyRow<T extends Record<string, unknown>>(row: T): T;
+/** True when a row still carries a retired identity worth persisting over. */
+declare function hasLegacyIdentity(row: Record<string, unknown>): boolean;
+
 /**
  * Dashboard Note model (#898 map, format locked in #899).
  *
@@ -2136,13 +2288,13 @@ declare function migrateLegacyDashboardBodies(raw: string): string;
  * Auto-generated build version metadata.
  * Do not edit directly; updated by scripts/stamp-version.ts
  */
-declare const VERSION = "0.44.2159";
-declare const GIT_SHA = "30e43c7";
-declare const BUILD_TIME = "2026-10-24T23:07:22.311Z";
+declare const VERSION = "0.45.2166";
+declare const GIT_SHA = "32bda10";
+declare const BUILD_TIME = "2026-10-26T20:01:09.868Z";
 declare const SEMVER: {
-    readonly version: "0.44.2159";
-    readonly gitSha: "30e43c7";
-    readonly buildTime: "2026-10-24T23:07:22.311Z";
+    readonly version: "0.45.2166";
+    readonly gitSha: "32bda10";
+    readonly buildTime: "2026-10-26T20:01:09.868Z";
 };
 
-export { type Aggregator, type AnyParsedQuery, BUILD_TIME, type BlockQueryStore, CONTENT_GROUPING_DIMENSIONS, type CatalogFieldSuggestion, type CatalogValueSuggestion, type ComparisonOp, DASHBOARD_GRID_MAX_COLS, DASHBOARD_WIDGET_TYPES, DEFAULT_DASHBOARD_TITLE, DISCIPLINE_FACTORS, type DashboardDocument, type DashboardMeta, type DashboardParsedSection, type DashboardSectionInput, type DashboardToken, type DashboardWidget, type DashboardWidgetType, type DocumentAssignment, type DocumentDefaults, type DocumentFormula, type DocumentOutput, type DocumentResult, EFFORT_DISCIPLINES, type EffortDiscipline, type EffortQueryStore, type EventRowIdentity, type EventStore, type ExecutionContext, type FamilyRunPayload, type FindOptions, type FindPredicate, type FindQueryResult, type FormulaEvaluation, type FormulaEvaluator, GIT_SHA, type IEffort, type IFieldCatalog, type LinkWidget, type MetricPredicate, type NoteContainer, type NoteQueryStore, type NoteRelationBundle, type OperandValue, type OutputUnitResolution, PLANNED_WIDGET_TYPES, type PageSourceEntry, PageSourceRegistry, type ParsedAggregateQuery, type ParsedDocument, type ParsedFindQuery, type ParsedFrontmatter, type ParsedPipelineQuery, type ParsedRowsQuery, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type ParsedWqlWindowSuffix, type PipelineOptions, type PipelineResult, type PipelineSink, type PipelineSource, type PointwiseInputs, type QueryDocument, QueryDocumentRunner$1 as QueryDocumentRunner, type QueryDocumentRunnerHost, type QueryDocumentRunnerOptions, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type QueryWindow, type ResolvedRange, type RowsPipes, type RowsQueryResult, type RowsRun, SEMVER, type Series, type SeriesPoint, QueryDocumentRunner as SharedQueryDocumentRunner, type SharedRunnerOptions, type SummaryFactIdentity, type SummaryFactSourceOutput, type TabularColumn, type TabularGroup, type TabularResult, type TagFilter, type TagValue, UNASSIGNED, type UnitBearingFact, type UnitFamily, VERSION, WQL_AGGREGATORS, WQL_CALC_TARGETS, WQL_CHART_HEADS, WQL_COMPARISON_OPS, WQL_CONTENT_FILTER_KEYS, WQL_CONTENT_ONLY_KEYS, WQL_DISPLAY_UNITS, WQL_EFFORT_FILTER_KEYS, WQL_FIND_TARGETS, WQL_FUNCTION_HEADS, WQL_GRAINS, WQL_INTENSITY_TIERS, WQL_KEYWORDS, WQL_METRIC_AGGREGATES, WQL_METRIC_FAMILIES, WQL_NOTE_DEFAULT_SOURCES, WQL_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_SOURCES, WQL_SOURCE_HEADS, WQL_SOURCE_HEAD_SCOPES, WQL_SOURCE_VALUES, WQL_STANDARD_DATASETS, WQL_TAG_KEYS, WQL_TYPED_TAG_KEYS, WQL_TYPE_HEADS, WQL_VIRTUAL_DIMS, type WidgetOpResult, type WidgetSpan, type WidgetSpec, type WqlAggregator, type WqlCalcTarget, type WqlChartHead, type WqlComparisonOp, type WqlCompletionOptions, type WqlContentFilterKey, type WqlDisplayUnit, type WqlDomainOrder, type WqlDomainPredicate, type WqlDomainReadResult, type WqlFindTarget, type WqlFunctionHead, type WqlGrain, type WqlIntensityTier, type WqlKeyword, type WqlMetricAggregate, type WqlMetricFamily, type WqlResultPlane, type WqlRollupPeriod, type WqlSource, type WqlSourceHead, type WqlSourceValue, type WqlStandardDataset, type WqlTagKey, type WqlTypedTagKey, type WqlVirtualDim, allowedFilterTypesForTarget, appendSuffixes, appendWidget, buildDashboardDocument, buildDashboardScaffold, buildDrillDownQuery, captureContext, catalogOfItem, civilDateAdd, civilDateDiff, civilDateOf, civilDatesCoveredByRange, civilMonday, consumesRollupFacts, convertDisplay, createBuiltinFormulaEvaluator, dashboardSlug, defaultTokenValues, disciplineFactorFor, duplicateWidget, eventsToStoredLogs, extractDashboardTokens, extractFrontmatterTags, findTargetAdvisories, getList, getScalar, getUnitFamily, inRange, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isPipelineQuery, isProposedMetric, migrateLegacyDashboardBodies, moveWidget, normalizeSummaryFacts, normalizeWql, notebookOfItem, parseDashboardNote, parseDocument, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, removeWidget, renderWidgetGroup, resizeWidget, resolveCanonicalMetricKey, resolveOutputUnit, resolveWidgetType, resolveWindowRange, rowsParseError, serialize, serializeDocument, serializeFrontmatter, setDashboardTokenValue, sourceMatches, splitAtWhere, stripFrontmatter, substituteTokens, substituteTokens$1 as substituteTokensRaw, supportsWqlFilterKey, systemTimeZone, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, updateWidget, widgetBodyLine, widgetFenceTag, wql, wqlCompletion, wqlCompletionSource, wqlFilterKeys, wqlGroupingDimensions, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms, zonedNoon, zonedStartOfDay };
+export { type Aggregator, type AnyParsedQuery, BUILD_TIME, type BlockQueryStore, CONTENT_GROUPING_DIMENSIONS, type CatalogFieldSuggestion, type CatalogValueSuggestion, type ComparisonOp, DASHBOARD_GRID_MAX_COLS, DASHBOARD_WIDGET_TYPES, DEFAULT_DASHBOARD_TITLE, DISCIPLINE_FACTORS, type DashboardDocument, type DashboardMeta, type DashboardParsedSection, type DashboardSectionInput, type DashboardToken, type DashboardWidget, type DashboardWidgetType, type DocumentAssignment, type DocumentDefaults, type DocumentFormula, type DocumentOutput, type DocumentResult, EFFORT_DISCIPLINES, type EffortDiscipline, type EffortQueryStore, type EventRowIdentity, type EventStore, type ExecutionContext, type FamilyRunPayload, type FindOptions, type FindPredicate, type FindQueryResult, type FormulaEvaluation, type FormulaEvaluator, GIT_SHA, type IFieldCatalog, type LinkWidget, type MetricPredicate, type NoteContainer, type NoteQueryStore, type NoteRelationBundle, type OperandValue, type OutputUnitResolution, PLANNED_WIDGET_TYPES, type PageSourceEntry, PageSourceRegistry, type ParsedAggregateQuery, type ParsedDocument, type ParsedFindQuery, type ParsedFrontmatter, type ParsedPipelineQuery, type ParsedRowsQuery, type ParsedWqlRollupSuffix, type ParsedWqlSuffixes, type ParsedWqlWindowSuffix, type PipelineOptions, type PipelineResult, type PipelineSink, type PipelineSource, type PointwiseInputs, type QueryDocument, QueryDocumentRunner$1 as QueryDocumentRunner, type QueryDocumentRunnerHost, type QueryDocumentRunnerOptions, type QueryOptions, type QueryResult, QueryService, type QueryServiceStores, type QueryWidgetSuffix, type QueryWindow, type ResolvedRange, type RowsPipes, type RowsQueryResult, type RowsRun, SEMVER, SOURCE_ID_SHAPES, type Series, type SeriesPoint, QueryDocumentRunner as SharedQueryDocumentRunner, type SharedRunnerOptions, type SummaryFactIdentity, type SummaryFactSourceOutput, type TabularColumn, type TabularGroup, type TabularResult, type TagFilter, type TagValue, UNASSIGNED, type UnitBearingFact, type UnitFamily, VERSION, WQL_AGGREGATORS, WQL_CALC_TARGETS, WQL_CHART_HEADS, WQL_COMPARISON_OPS, WQL_CONTENT_FILTER_KEYS, WQL_CONTENT_ONLY_KEYS, WQL_DISPLAY_UNITS, WQL_EFFORT_FILTER_KEYS, WQL_FIND_TARGETS, WQL_FUNCTION_HEADS, WQL_GRAINS, WQL_INTENSITY_TIERS, WQL_KEYWORDS, WQL_METRIC_AGGREGATES, WQL_METRIC_FAMILIES, WQL_NOTE_DEFAULT_SOURCES, WQL_NOTE_HEAD_ALIASES, WQL_RESULT_PLANES, WQL_ROLLUP_PERIODS, WQL_SOURCES, WQL_SOURCE_HEADS, WQL_SOURCE_HEAD_SCOPES, WQL_SOURCE_VALUES, WQL_STANDARD_DATASETS, WQL_TAG_KEYS, WQL_TYPED_TAG_KEYS, WQL_TYPE_HEADS, WQL_VIRTUAL_DIMS, type WidgetOpResult, type WidgetSpan, type WidgetSpec, type WqlAggregator, type WqlCalcTarget, type WqlChartHead, type WqlComparisonOp, type WqlCompletionOptions, type WqlContentFilterKey, type WqlDisplayUnit, type WqlDomainOrder, type WqlDomainPredicate, type WqlDomainReadResult, type WqlFindTarget, type WqlFunctionHead, type WqlGrain, type WqlIntensityTier, type WqlKeyword, type WqlMetricAggregate, type WqlMetricFamily, type WqlResultPlane, type WqlRollupPeriod, type WqlSource, type WqlSourceHead, type WqlSourceValue, type WqlStandardDataset, type WqlTagKey, type WqlTypedTagKey, type WqlVirtualDim, allowedFilterTypesForTarget, appendSuffixes, appendWidget, buildDashboardDocument, buildDashboardScaffold, buildDrillDownQuery, captureContext, civilDateAdd, civilDateDiff, civilDateOf, civilDatesCoveredByRange, civilMonday, consumesRollupFacts, convertDisplay, createBuiltinFormulaEvaluator, dashboardSlug, defaultTokenValues, disciplineFactorFor, duplicateWidget, eventsToStoredLogs, extractDashboardTokens, extractFrontmatterTags, feedOfItem, findTargetAdvisories, getList, getScalar, getUnitFamily, hasLegacyIdentity, inRange, isAggregateQuery, isDashboardMeta, isDashboardWidgetType, isEffortDiscipline, isFindQuery, isPipelineQuery, isProposedMetric, migrateLegacyChunkId, migrateLegacyDashboardBodies, migrateLegacyRouteId, migrateLegacyRow, migrateLegacySourceId, migrateLegacySourcePath, moveWidget, normalizeSummaryFacts, normalizeWql, notebookOfItem, notebookOriginOfItem, notebookSlugOfSourceId, parseDashboardNote, parseDocument, parseFlatProperties, parseFrontmatter, parseFrontmatterBody, parseFrontmatterCategories, parseFrontmatterProps, parseQuery, parseQueryWidgetSuffix, parseWqlSuffixes, projectEventToFacts, referencedTokens, removeWidget, renderWidgetGroup, resizeWidget, resolveCanonicalMetricKey, resolveOutputUnit, resolveWidgetType, resolveWindowRange, rowsParseError, serialize, serializeDocument, serializeFrontmatter, setDashboardTokenValue, sourceMatches, sourceShape, splitAtWhere, stripFrontmatter, substituteTokens, substituteTokens$1 as substituteTokensRaw, supportsWqlFilterKey, systemTimeZone, toEventRows, toSummaryEventRows, unknownTokensMessage, unknownWidgetTypeMessage, updateWidget, widgetBodyLine, widgetFenceTag, wql, wqlCompletion, wqlCompletionSource, wqlFilterKeys, wqlGroupingDimensions, wqlHighlightStyle, wqlLanguage, parser as wqlParser, wql_parser_terms as wqlTerms, zonedNoon, zonedStartOfDay };