vouchington-tooling 0.38.0 → 0.38.1

package/dist/index.d.mts

@@ -12,8 +12,8 @@ export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_M
 export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoader, JournalLoadResult, PermissionRequestObservation, SessionFrictionReport, SessionFrictionReportOptions, ToolResultObservation, } from './session-friction/index.mts';
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from './runner-port-policy/index.mts';
 export type { EphemeralListenerOptions, RunnerPortPolicy } from './runner-port-policy/index.mts';
-export { extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
-export type { ForeignKey, SqlCreateIndexMetadata, SqlCreateTableColumn, SqlCreateTableMetadata, SqlIndexParam, SqlMigrationConstraintMetadata, } from './sql-ast/index.mts';
+export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from './sql-ast/index.mts';
+export type { SqlCreateTableColumn, SqlCreateTableMetadata } from './sql-ast/index.mts';
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mts';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mts';
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';

package/dist/index.mjs

@@ -6,7 +6,7 @@ export { runRetrospectiveFacts } from "./retrospective-facts/index.mjs";
 export { appendJournal, assertSessionId, cleanupSnapshotPartitions, partitionSnapshot, probeBlackboard, readJournal, resolveBlackboardConnection, } from "./agent-blackboard/index.mjs";
 export { buildSessionFrictionReport, classifyFrictionObservation, FRICTION_LOG_MAX_EVENTS, isConformingCiFailureBlock, normalizeCommandPrefix, readFrictionLog, recordFriction, } from "./session-friction/index.mjs";
 export { EphemeralListenerAttemptsExhaustedError, isRunnerReservedPort, listenOnRunnerUnreservedEphemeralPort, loadRunnerPortPolicy, runnerPortPolicy, validateRunnerPortPolicy, } from "./runner-port-policy/index.mjs";
-export { extractCreateIndexMetadata, extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, extractMigrationConstraintMetadata, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
+export { extractCreateTableMetadata, extractDefaultFunction, extractFuncCallArgColumnNames, initSqlAst, lineOfUtf8ByteOffset, MissingSqlAstParserError, parseSql, } from "./sql-ast/index.mjs";
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from "./sql-scanner/index.mjs";
 export { auditCiJobRuntime, parseWorkflowNameMatch } from "./gha-runtime-audit/index.mjs";
 export { checkGhaWorkspacePolicy } from "./gha-workspace-policy/index.mjs";

package/dist/sql-ast/index.d.mts

@@ -1,11 +1,7 @@
-export { extractMigrationConstraintMetadata } from './constraint.mts';
-export type { ForeignKey, SqlMigrationConstraintMetadata } from './constraint-shared.mts';
 export { extractCreateTableMetadata } from './create-table.mts';
 export type { SqlCreateTableColumn, SqlCreateTableColumnConstraint, SqlCreateTableMetadata, } from './create-table.mts';
 export { extractDefaultFunction, extractFuncCallArgColumnNames } from './default-function.mts';
-export { extractCreateIndexMetadata } from './index-metadata.mts';
 export { extractIndexShapes } from './index-shapes.mts';
-export type { SqlCreateIndexMetadata, SqlIndexParam } from './index-metadata.mts';
 export { lineOfUtf8ByteOffset } from './line-of-offset.mts';
 export { initSqlAst, MissingSqlAstParserError, parseSql } from './parser.mts';
 export { extractViewDeclarations } from './view-declarations.mts';

package/dist/sql-ast/index.mjs

@@ -1,7 +1,5 @@
-export { extractMigrationConstraintMetadata } from "./constraint.mjs";
 export { extractCreateTableMetadata } from "./create-table.mjs";
 export { extractDefaultFunction, extractFuncCallArgColumnNames } from "./default-function.mjs";
-export { extractCreateIndexMetadata } from "./index-metadata.mjs";
 export { extractIndexShapes } from "./index-shapes.mjs";
 export { lineOfUtf8ByteOffset } from "./line-of-offset.mjs";
 export { initSqlAst, MissingSqlAstParserError, parseSql } from "./parser.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/bounded-iteration/SKILL.md

@@ -15,6 +15,10 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
    serves: a work-item or dirty-marker row, a parent id, a due timestamp with a partial index, or
    a time or UUIDv7 window past a high-water mark. Column-to-column comparisons, `OR` of unrelated
    conditions, and `EXISTS` as the only condition are not filters. (`postgres-required-predicates`)
+   A per-row threshold becomes one bucket per distinct value, comparing the stored fact with a
+   bound, never with another column; `timestamptz + interval` is not immutable, so it cannot be
+   indexed. See [per-row interval](references/sweep-patterns.md#per-row-interval-one-bucket-per-threshold)
+   and [age milestones](references/sweep-patterns.md#age-milestones-from-the-uuidv7-key).
 2. **Cap every run.** Every loop has a per-run cap (batches, rows, or a deadline), reports whether
    work remains, and resumes from a persisted position. Never loop until empty, and never default
    a cap to infinity.
@@ -36,12 +40,31 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
 8. **Tunables are runtime configuration.** Batch sizes, page sizes, caps, and windows come from
    the consumer's runtime configuration with a validated default and a hard maximum, and are bound
    as SQL parameters. `LIMIT 1` and an external API's page maximum are contracts, not tunables.
-9. **Work that needs every key** (rebuilding a membership filter, a reindex) keeps derived state
-   current on write. A full pass is an explicit, capped, resumable backfill, not a scheduled pass
-   over everything.
-10. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
+9. **One dispatcher per signal.** Split an `OR` of unrelated reasons into one dispatcher per
+   reason, each with its own index-served predicate, position, and schedule, all enqueuing the same
+   idempotent job. Writes that cause a signal enqueue directly; the sweep is the backstop. See
+   [one dispatcher per signal](references/sweep-patterns.md#one-dispatcher-per-signal).
+10. **Deduplicate jobs by entity and triggering event.** A job id keyed only by the entity drops a
+    new trigger while the last job runs or is retained. Key it by entity and event; dedup lasts
+    only while the record is retained, and a failed retained job still claims its id. See
+    [queue job ids](references/sweep-patterns.md#queue-job-ids-for-deduplication).
+11. **Repair through an existing reconciler.** Repeat a fire-and-forget side effect (cache fill,
+    filter add, enqueue) idempotently from the reconciler that already sweeps recently changed
+    rows. Do not add a sweeper. See
+    [repair](references/sweep-patterns.md#repair-through-an-existing-reconciler).
+12. **Membership filters are never rebuilt on a schedule.** Add on write, rebuild in full only on
+    an operator action or a detected failure, and stop trusting the filter after a failed add.
+    Deleted keys and growth only cost false positives. See
+    [membership filters](references/sweep-patterns.md#membership-filters).
+13. **Global rankings stay one periodic aggregate.** A result over every row needs every score;
+    incremental per-row inputs move the cost to every write without freshening the ranking. Give
+    the pass an EXPLAIN budget. See [global ranking](references/sweep-patterns.md#global-ranking).
+14. **External listings carry the provider's continuation token.** Cap pages per run and enqueue a
+    continuation with the token; restarting at page one lets failing front items starve the rest.
+    See [external listing](references/sweep-patterns.md#external-listing-with-a-continuation-token).
+15. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
     unbounded table, and an index that supplies the `ORDER BY`, so the scan stops at the
-    `LIMIT` instead of reading and sorting every match.
+    `LIMIT` instead of reading and sorting every match. Compare rows read with rows returned.
 
 For work-item, lease, and cursor tables, read [postgres-schema-design](../postgres-schema-design/SKILL.md).
 For query shape and streaming, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).

package/skills/bounded-iteration/references/sweep-patterns.md

@@ -293,12 +293,376 @@ const fresh = candidates.filter((ref) => !known.has(ref))
 When the goal is only to insert the new rows, `INSERT ... ON CONFLICT DO NOTHING RETURNING` skips
 the lookup.
 
-## Work that needs every key
+## Per-row interval: one bucket per threshold
+
+When the rule lives on the row, such as a per-site refresh interval, compare the stored fact with
+a bound per distinct threshold value, never with another column. `swept_at` stores when the last
+_completed_ sweep started; set it from the sweep's own start time when the sweep reports no more
+work. Each interval value is a bucket the index can seek into. A recursive CTE walks the leading
+column of the index one distinct value at a time (a loose index scan, or skip scan), so finding
+the buckets reads one index entry per bucket, not every enabled site. Each bucket is capped on its
+own, so one busy bucket cannot starve the others. Each branch inside a bucket has its own cap too,
+so a steady stream of never-swept sites cannot starve overdue rows. A run returns at most
+2 times `$1` rows per bucket:
 
-A membership filter or a reindex needs every key, but not on every run. Keep the derived state
-current on write: the insert or a dirty marker updates it. A full rebuild is a backfill started on
-purpose, with a row cap per run and a keyset cursor to resume from, as in the high-water-mark
-window. A scheduler never starts it as a pass over everything.
+```sql
+CREATE INDEX idx_sites__refresh_due
+  ON sites (refresh_interval_days, swept_at NULLS FIRST, id)
+  WHERE is_enabled;
+
+WITH RECURSIVE bucket AS (
+  (SELECT refresh_interval_days FROM sites
+   WHERE is_enabled
+   ORDER BY refresh_interval_days LIMIT 1)
+  UNION ALL
+  SELECT next_bucket.refresh_interval_days
+  FROM bucket
+  CROSS JOIN LATERAL (
+    SELECT refresh_interval_days FROM sites
+    WHERE is_enabled AND refresh_interval_days > bucket.refresh_interval_days
+    ORDER BY refresh_interval_days LIMIT 1
+  ) next_bucket
+)
+SELECT due.id, bucket.refresh_interval_days
+FROM bucket
+CROSS JOIN LATERAL (
+  (SELECT id FROM sites
+   WHERE is_enabled AND refresh_interval_days = bucket.refresh_interval_days
+     AND swept_at IS NULL
+   ORDER BY id LIMIT $1)
+  UNION ALL
+  (SELECT id FROM sites
+   WHERE is_enabled AND refresh_interval_days = bucket.refresh_interval_days
+     AND swept_at < now() - bucket.refresh_interval_days * interval '1 day'
+   ORDER BY swept_at, id LIMIT $1)
+) due;
+```
+
+The loose scan beats a small thresholds table here because the intervals are chosen per row and
+there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
+thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
+example by a `CHECK` that restricts `refresh_interval_days` to the allowed values. Declare the
+column `NOT NULL` with a default as well: a NULL interval is never enumerated by the loose scan
+(`>` skips NULL) and never compares as due, so that site would never be swept.
+
+Comparing `swept_at < now() - refresh_interval_days * interval '1 day'` alone cannot use an index:
+the right side depends on the row's own column, and `timestamptz + interval` is not immutable, so
+the sum cannot be indexed or stored as a generated column. Inside a bucket the interval is a
+constant, so the bound is a plain range on `swept_at`.
+
+Each condition is its own branch. `swept_at IS NULL OR swept_at < $bound` is not one index range:
+the planner makes `refresh_interval_days = k` the index condition and applies the `OR` as a filter.
+When fewer rows are due than the cap, that scan reads every row in the bucket. Verify by rows, not
+scan type: the plan's actual rows read stay close to the rows returned, and `Rows Removed by
+Filter` is near zero.
+
+## Age milestones from the UUIDv7 key
+
+An account crosses age `M` when `now - M` passes its creation time, which the key encodes. So
+"crossed `M` since the last run" is a primary-key range with no stored column. `$1` is the previous
+run's time minus an overlap (the window start), `$2` the window end, fixed when the window opens,
+`$3` the milestone interval, `$4` the last `id` already read (the nil UUID at the start of a
+window), and `$5` the cap. This holds only when ids are minted at creation and never for imports
+or backfills; where that is not guaranteed, drive milestones from an indexed immutable `created_at`
+range instead (see the [parent lower bound](../../postgres-partitioning-uuid-v7/references/partition-lifecycle.md#parent-lower-bound)
+conditions on historical ids):
+
+```sql
+CREATE INDEX idx_accounts__open ON accounts (id) WHERE closed_at IS NULL;
+
+SELECT id FROM accounts
+WHERE id >= min_uuidv7($1::timestamptz - $3::interval)
+  AND id <  min_uuidv7($2::timestamptz - $3::interval)
+  AND id >  $4
+  AND closed_at IS NULL
+ORDER BY id
+LIMIT $5;
+```
+
+Without the partial index, `closed_at IS NULL` is a filter on the primary-key range, and a window
+where most accounts are closed reads every one of them. Verify by rows: the plan's rows read stay
+close to the rows returned.
+
+A window can hold more accounts than the cap, so persist the last `id` returned after each batch
+and page inside the fixed window with `id > $4`. Advance the window only after a short batch: the
+next window starts an overlap before this one's end (`$2`), with the nil UUID as `$4`. Moving the
+start to the window's end after a capped batch would skip the accounts not yet read. This is the
+`age_milestone` signal's `last_id` in the dispatcher cursor table below.
+
+## One dispatcher per signal
+
+The anti-pattern is one keyset walk over every account with an `OR` of unrelated reasons. No index
+serves the `OR`, so every account is read to find the few that need work:
+
+```sql
+SELECT a.id
+FROM accounts a
+WHERE a.id > $1
+  AND (a.id < min_uuidv7(now() - $2::interval)
+       OR EXISTS (SELECT 1 FROM subscriptions s
+                  WHERE s.account_id = a.id AND s.expires_at < now())
+       OR EXISTS (SELECT 1 FROM plan_changes c
+                  WHERE c.account_id = a.id AND c.id > $3))
+ORDER BY a.id
+LIMIT $4;
+```
+
+Replace it with one dispatcher per signal, each with its own index-served predicate, position, and
+schedule. A signal backed by several timestamp columns reads one indexed range per column, joined
+with `UNION ALL`, not an `OR` across columns. A window can hold more rows than the cap, so each
+dispatcher pages inside it with a composite keyset position, as in the high-water-mark window.
+`$1` is the window end, `$2` and `$3` the position (`last_at`, `last_id`), and `$4` the cap:
+
+```sql
+-- age milestones: the accounts range above, with `id > $3` as the position and
+-- `id < min_uuidv7($1 - milestone)` as the window end
+
+-- subscription expirations: one indexed range per timestamp column, merged by (at, id)
+-- (catches only expiries that pass in real time; see the note below)
+SELECT at, id, account_id FROM (
+  (SELECT expires_at AS at, id, account_id FROM subscriptions
+   WHERE (expires_at, id) > ($2, $3) AND expires_at < $1
+   ORDER BY expires_at, id LIMIT $4)
+  UNION ALL
+  (SELECT grace_ends_at AS at, id, account_id FROM subscriptions
+   WHERE (grace_ends_at, id) > ($2, $3) AND grace_ends_at < $1
+   ORDER BY grace_ends_at, id LIMIT $4)
+) either_column
+ORDER BY at, id
+LIMIT $4;
+
+-- plan changes: a UUIDv7 window, with `last_id` (seeded at the overlap boundary) as the position
+SELECT id, account_id FROM plan_changes
+WHERE id > $3 AND id < min_uuidv7($1)
+ORDER BY id
+LIMIT $4;
+```
+
+Each dispatcher keeps its window end and position in one cursor table keyed by an enum:
+
+```sql
+CREATE TYPE account_recalc_signals AS ENUM ('age_milestone', 'subscription_expiry', 'plan_change');
+
+CREATE TABLE account_recalc_cursors (
+  signal account_recalc_signals PRIMARY KEY,
+  changes_through_at timestamptz NOT NULL,
+  last_at timestamptz NOT NULL,
+  last_id uuid NOT NULL DEFAULT '00000000-0000-0000-0000-000000000000'
+);
+```
+
+`changes_through_at` is the window end, fixed when the window opens. Advance `(last_at, last_id)`
+after each batch with a compare-and-set. When a batch is short, the window is drained: the next
+window opens with a new `changes_through_at`, and its position restarts an overlap before the
+previous end. A UUIDv7-keyed signal (`plan_change`) seeds `last_id` with
+`min_uuidv7(previous end - overlap)`, never the nil UUID, which would rescan from the start of
+the table; a timestamp-keyed signal sets `last_at` to the same boundary with the nil `last_id`.
+
+`expires_at` and `grace_ends_at` are mutable business timestamps, the same trap as using
+`occurred_at` as a high-water mark in the
+[high-water-mark window](#high-water-mark-window-with-an-overlap). A row updated or imported with
+an expiry older than the cursor position is never selected, so the dispatcher catches only
+expiries that pass in real time. Any write that sets an expiry at or before now, or before the
+cursor, enqueues the job directly in the write path or records an immutable change event
+(`plan_changes` is one) that a UUIDv7-keyed dispatcher reads.
+
+All of them enqueue the same `recalculateAccount` job with the per-event ids below, so a repeat
+read is harmless. Writes that cause a signal, such as recording a plan change, enqueue the job in
+the write path. The dispatchers are the backstop for a missed enqueue.
+
+## Queue job ids for deduplication
+
+A queue that deduplicates by job id ignores an add whose id already exists, including a job that is
+running or retained after completion. An id keyed only by the entity drops a new trigger:
+
+```ts
+// Account A's job is running when A's subscription expires: this second add is ignored.
+await queue.add('recalculateAccount', { accountId }, { jobId: `recalc__${accountId}` })
+```
+
+Key the id by the entity and the event instead. Re-reading the same event in an overlap gives the
+same id, and a new event gets a new id:
+
+```ts
+await queue.add(
+  'recalculateAccount',
+  { accountId, changeId },
+  { jobId: `recalc__${accountId}__planChanged__${changeId}` },
+)
+```
+
+While the job record is retained, each trigger is enqueued at most once; that does not mean it
+runs. Deduplication lasts only as long as the record: retention must cover the longest overlap or
+replay interval, or a re-read event enqueues again after the record is removed. A requirement that
+a trigger take effect exactly once needs a durable event ledger, not job ids. If a job fails for
+good and its record is retained, the same id is still claimed, so retrying it needs an explicit
+reactivate-or-remove step before the next add.
+
+## Repair through an existing reconciler
+
+When a side effect after commit is fire-and-forget (a cache fill, a filter add, an enqueue), repair
+it in the reconciler that already reads a `changed_through_at` window of recently changed rows. Do
+not create a new sweeper. `$1` and `$2` are the position (`changed_at`, `id`), seeded an overlap
+before the previous window's end, `$3` the window end fixed when the window opens, and `$4` the cap:
+
+```sql
+SELECT id, handle, version
+FROM accounts
+WHERE (changed_at, id) > ($1, $2) AND changed_at <= $3
+ORDER BY changed_at, id
+LIMIT $4;
+```
+
+Advance the position after each batch with a compare-and-set, and open the next window only after a
+short batch, as in the dispatcher cursor table.
+
+```ts
+for (const account of await db.query(recentlyChangedAccountsSql, [
+  ...position,
+  to,
+  config.batchSize,
+])) {
+  // Monotonic: the write compares `version`, so a delayed repair never overwrites a newer value.
+  await accountCache.fillIfNotOlder(account.id, account, account.version)
+  await addHandle(account.handle) // idempotent; the invalidating helper from membership filters
+}
+```
+
+Idempotence alone is not enough, because the overlap reads rows twice and a delayed repair can land
+after a newer write. Make each repair monotonic: compare an integer `version` that every update
+increments (`version = version + 1`) on write, or invalidate the cache entry and let the next read
+load the current row. Do not compare `changed_at = now()`: it is the transaction's start time and
+is not monotonic across concurrent transactions.
+
+## Membership filters
+
+A membership filter needs every key, but never on a schedule. The write path adds immediately after
+commit. A failed add stops trusting the filter, by clearing its ready marker so reads fall back to
+the source of truth, and enqueues a rebuild. The job id includes the filter generation: a fixed id
+would stay claimed once its record is retained, so a later failure could never enqueue. Each
+invalidation bumps the generation, so concurrent enqueues for one failure share an id and a new
+failure gets a new one. The reconciler repairs missed adds from its window, and a read that finds
+the filter missing enqueues the same rebuild:
+
+```ts
+async function enqueueRebuild(generation: number, afterId = 'start'): Promise<void> {
+  try {
+    const jobId = `rebuildFilter__handles__${generation}__${afterId}`
+    await queue.add('rebuildFilter', { generation, afterId }, { jobId })
+  } catch (error) {
+    logger.warn({ error }, 'could not enqueue the filter rebuild') // best effort
+  }
+}
+
+export async function addHandle(handle: string): Promise<void> {
+  try {
+    await handleFilter.add(handle)
+  } catch {
+    await enqueueRebuild(await handleFilter.invalidate()) // clears ready, bumps the generation
+  }
+}
+
+export async function hasHandle(handle: string): Promise<boolean> {
+  if (!(await handleFilter.isReady())) {
+    await enqueueRebuild(await handleFilter.generation())
+    return handleExistsInDatabase(handle) // the read falls back even if the enqueue failed
+  }
+  // Hint only: a negative means "definitely absent" for keys committed before the last
+  // successful add or rebuild. A positive may be a false positive, so verify it at the source.
+  try {
+    if (!(await handleFilter.has(handle))) return false
+  } catch {
+    await enqueueRebuild(await handleFilter.invalidate()) // a failing filter is not trusted
+  }
+  return handleExistsInDatabase(handle)
+}
+```
+
+The add happens after commit, so while it is in flight a committed handle can be missing from a
+ready filter. The filter is therefore only a hint for callers that tolerate a just-committed miss,
+such as an availability pre-check. Correctness-critical paths, such as a uniqueness check or a
+read-your-writes lookup, use the database or its unique constraint and never trust a negative.
+
+The rebuild is an explicit, capped, resumable backfill with a keyset cursor, as in the
+high-water-mark window. Each capped page enqueues its continuation with the cursor in the job id
+(`rebuildFilter__handles__${generation}__${afterId}`), because a generation-only id would block the
+next page of the same generation. Each page checks that its generation is still current before
+scanning and again before enqueueing a continuation, and a stale page exits without doing
+anything. The rebuild captures its generation when it starts and sets the
+ready marker last, by a compare-and-set that succeeds only while that generation is still current
+(`markReady(generation)`), so a stale rebuild never overwrites a newer invalidation. Deleted keys and growth past
+capacity only cost false positives, so they are an operator's rebuild, not a schedule.
+
+## Global ranking
+
+A result that depends on every row, such as a percentile tier, needs every row's score whatever the
+design. Keep one periodic aggregate. `$1` and `$2` are the tier cutoffs:
+
+```sql
+WITH per_plan AS (
+  SELECT s.channel_id, s.plan_id, count(*) AS subscribers
+  FROM subscriptions s
+  WHERE s.canceled_at IS NULL
+  GROUP BY s.channel_id, s.plan_id
+), weighted AS (
+  SELECT p.channel_id, sum(p.subscribers * plan.subscriber_weight) AS score
+  FROM per_plan p
+  JOIN plans plan ON plan.id = p.plan_id
+  GROUP BY p.channel_id
+), scores AS (
+  -- Start from channels so one with no active subscribers scores 0 instead of dropping out.
+  SELECT c.id AS channel_id, coalesce(w.score, 0) AS score
+  FROM channels c
+  LEFT JOIN weighted w ON w.channel_id = c.id
+), ranked AS (
+  SELECT channel_id, PERCENT_RANK() OVER (ORDER BY score) AS percentile, score
+  FROM scores
+)
+SELECT channel_id,
+       CASE WHEN score = 0 THEN 'low'
+            WHEN percentile >= $1 THEN 'top'
+            WHEN percentile >= $2 THEN 'mid'
+            ELSE 'low' END AS tier
+FROM ranked;
+```
+
+`PERCENT_RANK()` gives tied scores the lowest rank, so a large tie at score 0 stays at percentile 0
+instead of reading as a high cumulative fraction, and score 0 is forced into the low tier. Write
+back only the changed tiers, in capped keyset batches over the result. Keeping a subscriber
+count current on every subscribe and unsubscribe is more total work: it makes one hot `channels`
+row take every write, and a plan change fans out to every channel the account follows. It does not
+make tiers fresher either, because the percentile still needs every channel's score. Give the one
+aggregate pass an EXPLAIN budget at representative size.
+
+## External listing with a continuation token
+
+An object-storage or API listing loop caps the pages per run. When more remain, it enqueues a
+continuation job carrying the provider's continuation token. Restarting from page one each run is
+not a bound: items that keep failing at the front starve the rest.
+
+```ts
+export async function listingJob(
+  { token, traversalId = randomUUID() }: { token?: string; traversalId?: string },
+  config: ListingConfig,
+): Promise<void> {
+  let next = token // traversalId is minted when a traversal starts at page one
+  for (let page = 0; page < config.maxPagesPerRun; page += 1) {
+    const result = await provider.list({ continuationToken: next, maxKeys: config.pageSize })
+    await enqueueItems(result.items)
+    if (result.nextToken !== undefined && result.nextToken === next) {
+      throw new Error('Provider repeated its continuation token') // never loop or re-enqueue it
+    }
+    next = result.nextToken
+    if (!next) return
+  }
+  // The traversal id keeps a provider that reuses a token across traversals from colliding.
+  await queue.add(
+    'listing',
+    { token: next, traversalId },
+    { jobId: `listing__${traversalId}__${next}` },
+  )
+}
+```
 
 ## Verify with a plan
 
@@ -338,5 +702,11 @@ claim statement, and check the index scan's actual rows while several workers cl
 | A key-only walk: select every account id, then check each   | Touches every entity to find the few with work                           | Read work items, dirty markers, or a due timestamp           |
 | A literal `LIMIT 500` in SQL text                           | Cannot be tuned per environment or during an incident                    | A validated tunable with a hard maximum, bound as `LIMIT $1` |
 | `Promise.all(accounts.map(sync))` over a result of any size | One task per row exhausts the pool or the upstream API                   | A bounded batch with bounded concurrency                     |
+| An `OR` across unrelated signals in one walk                | No index serves the `OR`, so every account is read                       | One dispatcher per signal, each with its own range           |
+| Comparing a fact column with a per-row interval column      | The sum is not indexable, so every row is read                           | One bucket per interval value, bounded by a plain range      |
+| Job ids keyed only by entity                                | A running or retained job silently drops a new trigger                   | An id keyed by entity and triggering event                   |
+| A new sweeper beside an existing reconciler                 | A second pass over rows the reconciler already reads                     | Add the idempotent repair to the existing reconciler         |
+| A scheduled membership filter rebuild                       | Reads every key on every run                                             | Rebuild on operator action or detected failure only          |
+| Restarting an external listing at page one                  | Failing items at the front starve the rest                               | A continuation job carrying the provider's token             |
 | `OFFSET` pagination                                         | Every page rescans and discards the rows before it                       | Keyset on the indexed key                                    |
 | `UPDATE` or `DELETE` with a predicate but no `LIMIT`        | One statement locks and rewrites an unbounded row set in one transaction | A CTE that selects a capped, `SKIP LOCKED` id set            |

package/skills/manifest.json

@@ -24,7 +24,7 @@
     {
       "name": "bounded-iteration",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.0",
       "path": "bounded-iteration/SKILL.md"
     },
     {
@@ -109,19 +109,19 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
     {
       "name": "postgres-schema-design",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.4.0",
+      "pluginVersion": "0.5.0",
       "path": "postgres-schema-design/SKILL.md"
     },
     {

package/skills/postgres-node-performance-tuning/references/performance-patterns.md

@@ -26,10 +26,13 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
 cross-partition query. Choose the partition key from dominant access patterns; a hot reader
 of `RANGE (id)` needs an id or time bound.
 
-A UUIDv7 child cannot predate its parent. For a `RANGE (id)` child read by parent id, use a
-shared lower-bound helper equivalent to
-`id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` to prune earlier
-partitions; the overlap allows clock skew. Rate limits query an actor-keyed table rather than
+For a `RANGE (id)` child read by parent id, a shared lower-bound helper equivalent to
+`id >= min_uuidv7(uuid_extract_timestamp(parent_id) - interval '1 hour')` prunes earlier
+partitions; the overlap allows clock skew. It is safe only when every writer sets the parent at
+insert to an existing parent, never re-points it to a newer parent, and nothing mints child ids
+from a historical time; see
+[parent lower bound](../../postgres-partitioning-uuid-v7/references/partition-lifecycle.md#parent-lower-bound).
+Rate limits query an actor-keyed table rather than
 recipient-keyed fan-out rows. Verify actual pruning with EXPLAIN.
 
 Generic `jonathanong/no-mistakes` checks include `postgres-no-offset`; inspect available rules

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -17,6 +17,15 @@ Partition only after lifecycle, retention, and query predicates show that it hel
 - Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.
 - Align the partition key, primary key, indexes, constraints, and query predicates so partition
   pruning is observable.
+- Add a parent lower bound to a read of a `RANGE (id)` child table by its parent's UUIDv7 id
+  (`id >= min_uuidv7(parent time - skew)`) only when both hold: every writer sets the parent column
+  at insert, to a parent that already exists, and never re-points it to a newer parent; and nothing
+  mints child ids from a historical time (imports, backfills, seeds). Counterexample: articles
+  clustered into a story created later are older than their parent, and the bound silently drops
+  them. See [parent lower bound](references/partition-lifecycle.md#parent-lower-bound).
+- A statement that must read every partition declares that, with a reason, on the statement. Do not
+  use a table-wide exemption: it also silences every future query on that table. See
+  [cross-partition reads](references/partition-lifecycle.md#declaring-cross-partition-reads).
 - Plan creation, retention, migration, and verification as one deployable lifecycle. Include
   rollback and independent-reader compatibility.
 - Read [partition lifecycle](references/partition-lifecycle.md) before a schema or retention

package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md

@@ -12,3 +12,39 @@ Every primary or unique constraint on a partitioned table must include its parti
 pruning with predicates on that key, including joins whose other side needs an equivalent range
 condition. UUIDv7 values are time ordered, not a promise that independently generated identifiers
 have a strict ordering relationship.
+
+## Parent lower bound
+
+A child table partitioned `RANGE (id)` prunes when a reader bounds the child id. A reader that
+starts from the parent can derive that bound from the parent's UUIDv7 id, assuming a child is never
+older than its parent:
+
+```sql
+SELECT item.id, item.body
+FROM order_items AS item
+WHERE item.order_id = $1
+  AND item.id >= min_uuidv7($2::timestamptz - $3::interval);
+```
+
+`$2` is the parent's creation time and `$3` the clock skew allowance. The bound is safe only when
+both hold:
+
+- Every writer sets `order_id` at insert, to an order that already exists, and never re-points the
+  row to a newer order.
+- Nothing mints child ids from a historical time: imports, backfills, and seeds.
+
+Counterexample: `articles` clustered into a `stories` row created later. Each article id is older
+than its story id, so `article.id >= min_uuidv7(story time - skew)` silently drops the older
+articles. Bound such a read by the child's own window instead.
+
+## Declaring cross-partition reads
+
+A statement that must read every partition says so, with a reason, on the statement itself:
+
+```sql
+-- cross-partition: nightly integrity check compares order_items totals with orders
+SELECT order_id, sum(quantity) FROM order_items GROUP BY order_id;
+```
+
+Do not exempt the whole table. A table-wide exemption also silences the check for every future
+query on that table, including one that forgot its partition key predicate.

package/dist/sql-ast/constraint-do-block.d.mts

@@ -1,11 +0,0 @@
-import type { AlterTableStmt, DoStmt } from '@libpg-query/parser';
-import { type SqlMigrationConstraintMetadata } from './constraint-shared.mts';
-/**
- * Applies AT_AddConstraint / AT_ValidateConstraint commands from one ALTER TABLE to `result`.
- *
- * `trackConstraintValidation` gates NOT VALID/VALIDATE pairing bookkeeping. Callers that
- * parse ALTER TABLE text out of a DO body should pass false so only `foreignKeys` is filled.
- */
-export declare function processAlterTableStmt(statement: AlterTableStmt, baseOffset: number, result: SqlMigrationConstraintMetadata, trackConstraintValidation?: boolean): void;
-/** Idempotent migrations wrap `ALTER TABLE ... ADD CONSTRAINT` in `DO $$ ... $$` catalog checks. */
-export declare function collectDoStmtConstraints(content: string, statement: DoStmt, stmtLocation: number, result: SqlMigrationConstraintMetadata): void;

package/dist/sql-ast/constraint-do-block.mjs

@@ -1,84 +0,0 @@
-import { fkAttrNames, foreignKeyFromConstraint, } from "./constraint-shared.mjs";
-import { parseSql } from "./parser.mjs";
-/**
- * Applies AT_AddConstraint / AT_ValidateConstraint commands from one ALTER TABLE to `result`.
- *
- * `trackConstraintValidation` gates NOT VALID/VALIDATE pairing bookkeeping. Callers that
- * parse ALTER TABLE text out of a DO body should pass false so only `foreignKeys` is filled.
- */
-export function processAlterTableStmt(statement, baseOffset, result, trackConstraintValidation = true) {
-    const tableName = statement.relation?.relname;
-    /* v8 ignore next */
-    if (!tableName)
-        return;
-    for (const rawCommand of statement.cmds ?? []) {
-        /* v8 ignore next */
-        if (!rawCommand || !('AlterTableCmd' in rawCommand))
-            continue;
-        const command = rawCommand.AlterTableCmd;
-        if (command.subtype === 'AT_ValidateConstraint' && command.name) {
-            if (trackConstraintValidation)
-                result.validatedConstraints.add(`${tableName}.${command.name}`);
-            continue;
-        }
-        /* v8 ignore next */
-        if (command.subtype !== 'AT_AddConstraint')
-            continue;
-        const definition = command.def;
-        /* v8 ignore next */
-        if (!definition || !('Constraint' in definition))
-            continue;
-        const constraint = definition.Constraint;
-        /* v8 ignore next */
-        if (!constraint)
-            continue;
-        if (constraint.contype === 'CONSTR_FOREIGN') {
-            // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- isolate the generated AST type escape at the foreign-key adapter boundary
-            const constraintRecord = constraint;
-            result.foreignKeys.push(foreignKeyFromConstraint(constraintRecord, tableName, fkAttrNames(constraintRecord), baseOffset));
-        }
-        if (!trackConstraintValidation)
-            continue;
-        /* v8 ignore next */
-        if (constraint.contype !== 'CONSTR_CHECK' && constraint.contype !== 'CONSTR_FOREIGN')
-            continue;
-        result.addedConstraints.push({
-            /* v8 ignore next 3 */
-            constraintType: constraint.contype ?? null,
-            location: baseOffset + (constraint.location ?? 0),
-            name: constraint.conname ?? null,
-            tableName,
-        });
-    }
-}
-const ALTER_TABLE_STATEMENT_RE = /ALTER\s+TABLE\b[^;]*;/gi;
-/** Idempotent migrations wrap `ALTER TABLE ... ADD CONSTRAINT` in `DO $$ ... $$` catalog checks. */
-/* v8 ignore start -- DO-body regex/parse fallbacks */
-export function collectDoStmtConstraints(content, statement, stmtLocation, result) {
-    for (const arg of statement.args ?? []) {
-        const defElem = arg && 'DefElem' in arg ? arg.DefElem : undefined;
-        const stringArg = defElem?.arg && 'String' in defElem.arg ? defElem.arg.String : undefined;
-        const body = typeof stringArg?.sval === 'string' ? stringArg.sval : '';
-        for (const match of body.matchAll(ALTER_TABLE_STATEMENT_RE)) {
-            const baseOffset = content.indexOf(match[0], stmtLocation);
-            /* v8 ignore next */
-            if (baseOffset === -1)
-                continue;
-            let nested;
-            try {
-                nested = parseSql(match[0]);
-            }
-            catch {
-                /* v8 ignore next */
-                continue;
-            }
-            for (const nestedStmt of nested.stmts ?? []) {
-                const node = nestedStmt.stmt;
-                if (node && 'AlterTableStmt' in node) {
-                    processAlterTableStmt(node.AlterTableStmt, baseOffset, result, false);
-                }
-            }
-        }
-    }
-}
-/* v8 ignore stop */

package/dist/sql-ast/constraint-shared.d.mts

@@ -1,19 +0,0 @@
-export type SqlMigrationConstraintMetadata = {
-    addedConstraints: Array<{
-        constraintType: string | null;
-        location: number;
-        name: string | null;
-        tableName: string;
-    }>;
-    foreignKeys: Array<{
-        columnNames: string[];
-        deleteAction: string | null;
-        location: number;
-        referencedTableName: string | null;
-        tableName: string | null;
-    }>;
-    validatedConstraints: Set<string>;
-};
-export type ForeignKey = SqlMigrationConstraintMetadata['foreignKeys'][number];
-export declare function fkAttrNames(constraint: Record<string, unknown>): string[];
-export declare function foreignKeyFromConstraint(constraint: Record<string, unknown>, tableName: string | null, columnNames: string[], baseOffset?: number): ForeignKey;

package/dist/sql-ast/constraint-shared.mjs

@@ -1,20 +0,0 @@
-import { isRecord } from "./unknown-record.mjs";
-export function fkAttrNames(constraint) {
-    const attrs = constraint.fk_attrs;
-    if (!Array.isArray(attrs))
-        return [];
-    return attrs.flatMap((attr) => {
-        const sval = isRecord(attr) && isRecord(attr.String) ? attr.String.sval : undefined;
-        return typeof sval === 'string' ? [sval] : [];
-    });
-}
-export function foreignKeyFromConstraint(constraint, tableName, columnNames, baseOffset = 0) {
-    const pktable = constraint.pktable;
-    return {
-        columnNames,
-        deleteAction: typeof constraint.fk_del_action === 'string' ? constraint.fk_del_action : null,
-        location: baseOffset + (typeof constraint.location === 'number' ? constraint.location : 0),
-        referencedTableName: isRecord(pktable) && typeof pktable.relname === 'string' ? pktable.relname : null,
-        tableName,
-    };
-}

package/dist/sql-ast/constraint.d.mts

@@ -1,2 +0,0 @@
-import { type SqlMigrationConstraintMetadata } from './constraint-shared.mts';
-export declare function extractMigrationConstraintMetadata(content: string): SqlMigrationConstraintMetadata;

package/dist/sql-ast/constraint.mjs

@@ -1,63 +0,0 @@
-import { collectDoStmtConstraints, processAlterTableStmt } from "./constraint-do-block.mjs";
-import { fkAttrNames, foreignKeyFromConstraint, } from "./constraint-shared.mjs";
-import { parseSql } from "./parser.mjs";
-import { isRecord } from "./unknown-record.mjs";
-/** Inline `col UUID REFERENCES ...` and table-level `FOREIGN KEY (...) REFERENCES ...` forms. */
-/* v8 ignore start -- defensive parse-tree walks */
-function collectCreateStmtForeignKeys(statement, foreignKeys) {
-    const relation = statement.relation;
-    const tableName = isRecord(relation) && typeof relation.relname === 'string' ? relation.relname : null;
-    const tableElts = statement.tableElts;
-    if (!Array.isArray(tableElts))
-        return;
-    for (const element of tableElts) {
-        if (!isRecord(element))
-            continue;
-        if (isRecord(element.ColumnDef)) {
-            const column = element.ColumnDef;
-            const colname = typeof column.colname === 'string' ? column.colname : null;
-            for (const constraintNode of column.constraints ?? []) {
-                /* v8 ignore next 3 */
-                if (!isRecord(constraintNode) || !isRecord(constraintNode.Constraint))
-                    continue;
-                const constraint = constraintNode.Constraint;
-                if (constraint.contype !== 'CONSTR_FOREIGN')
-                    continue;
-                foreignKeys.push(foreignKeyFromConstraint(constraint, tableName, colname ? [colname] : []));
-            }
-            continue;
-        }
-        if (isRecord(element.Constraint) && element.Constraint.contype === 'CONSTR_FOREIGN') {
-            foreignKeys.push(foreignKeyFromConstraint(element.Constraint, tableName, fkAttrNames(element.Constraint)));
-        }
-    }
-}
-/* v8 ignore stop */
-export function extractMigrationConstraintMetadata(content) {
-    const result = {
-        addedConstraints: [],
-        foreignKeys: [],
-        validatedConstraints: new Set(),
-    };
-    const parseResult = parseSql(content);
-    for (const rawStmt of parseResult.stmts ?? []) {
-        const node = rawStmt.stmt;
-        /* v8 ignore next */
-        if (!node)
-            continue;
-        const stmtLocation = rawStmt.stmt_location ?? 0;
-        if ('CreateStmt' in node) {
-            collectCreateStmtForeignKeys(node.CreateStmt, result.foreignKeys);
-            continue;
-        }
-        if ('DoStmt' in node) {
-            collectDoStmtConstraints(content, node.DoStmt, stmtLocation, result);
-            continue;
-        }
-        /* v8 ignore next */
-        if (!('AlterTableStmt' in node))
-            continue;
-        processAlterTableStmt(node.AlterTableStmt, 0, result);
-    }
-    return result;
-}

package/dist/sql-ast/implicit-indexes.d.mts

@@ -1,3 +0,0 @@
-import type { SqlCreateIndexMetadata } from './index-metadata.mts';
-/** UNIQUE/PRIMARY KEY create implicit unique indexes that never appear as CREATE INDEX. */
-export declare function collectCreateStmtImplicitIndexes(statement: Record<string, unknown>, location: number, indexes: SqlCreateIndexMetadata[]): void;

package/dist/sql-ast/implicit-indexes.mjs

@@ -1,66 +0,0 @@
-import { isRecord } from "./unknown-record.mjs";
-function implicitIndexParam(name) {
-    return { name, opclass: null, ordering: null, nullsOrdering: null };
-}
-function pushImplicitIndex(indexes, relname, location, columnNames) {
-    indexes.push({
-        relname,
-        idxname: null,
-        unique: true,
-        indexParams: columnNames,
-        indexParamDetails: columnNames.map(implicitIndexParam),
-        includeParams: [],
-        whereClause: null,
-        whereClauseKey: null,
-        accessMethod: 'btree',
-        location,
-    });
-}
-function constraintKeyNames(constraint) {
-    const keys = constraint.keys;
-    if (!Array.isArray(keys))
-        return [];
-    return keys.flatMap((key) => {
-        const sval = isRecord(key) && isRecord(key.String) ? key.String.sval : undefined;
-        /* v8 ignore next */
-        return typeof sval === 'string' ? [sval] : [];
-    });
-}
-/** UNIQUE/PRIMARY KEY create implicit unique indexes that never appear as CREATE INDEX. */
-export function collectCreateStmtImplicitIndexes(statement, location, indexes) {
-    const relation = statement.relation;
-    const relname = isRecord(relation) && typeof relation.relname === 'string' ? relation.relname : null;
-    const tableElts = statement.tableElts;
-    if (!relname || !Array.isArray(tableElts))
-        return;
-    for (const element of tableElts) {
-        if (!isRecord(element))
-            continue;
-        if (isRecord(element.ColumnDef)) {
-            const column = element.ColumnDef;
-            const colname = typeof column.colname === 'string' ? column.colname : null;
-            if (!colname)
-                continue;
-            for (const constraintNode of column.constraints ?? []) {
-                /* v8 ignore next */
-                if (!isRecord(constraintNode) || !isRecord(constraintNode.Constraint))
-                    continue;
-                const contype = constraintNode.Constraint.contype;
-                if (contype !== 'CONSTR_UNIQUE' && contype !== 'CONSTR_PRIMARY')
-                    continue;
-                pushImplicitIndex(indexes, relname, location, [colname]);
-            }
-            continue;
-        }
-        /* v8 ignore next */
-        if (!isRecord(element.Constraint))
-            continue;
-        const contype = element.Constraint.contype;
-        if (contype !== 'CONSTR_UNIQUE' && contype !== 'CONSTR_PRIMARY')
-            continue;
-        const columnNames = constraintKeyNames(element.Constraint);
-        if (columnNames.length === 0)
-            continue;
-        pushImplicitIndex(indexes, relname, location, columnNames);
-    }
-}

package/dist/sql-ast/index-metadata.d.mts

@@ -1,19 +0,0 @@
-export type SqlIndexParam = {
-    name: string | null;
-    opclass: string | null;
-    ordering: string | null;
-    nullsOrdering: string | null;
-};
-export type SqlCreateIndexMetadata = {
-    relname: string;
-    idxname: string | null;
-    unique: boolean;
-    indexParams: Array<string | null>;
-    indexParamDetails: SqlIndexParam[];
-    includeParams: string[];
-    whereClause: unknown;
-    whereClauseKey: string | null;
-    accessMethod: string;
-    location: number;
-};
-export declare function extractCreateIndexMetadata(content: string): SqlCreateIndexMetadata[];

package/dist/sql-ast/index-metadata.mjs

@@ -1,100 +0,0 @@
-import { collectCreateStmtImplicitIndexes } from "./implicit-indexes.mjs";
-import { parseSql } from "./parser.mjs";
-import { isRecord } from "./unknown-record.mjs";
-function indexElemName(param) {
-    if (!isRecord(param) || !isRecord(param.IndexElem))
-        return null;
-    const name = param.IndexElem.name;
-    return typeof name === 'string' ? name : null;
-}
-function indexElemOpclass(param) {
-    if (!isRecord(param) || !isRecord(param.IndexElem))
-        return null;
-    const opclass = param.IndexElem.opclass;
-    if (!Array.isArray(opclass))
-        return null;
-    const names = opclass.flatMap((node) => {
-        const sval = isRecord(node) && isRecord(node.String) ? node.String.sval : undefined;
-        /* v8 ignore next */
-        return typeof sval === 'string' ? [sval] : [];
-    });
-    return names.length > 0 ? names.join('.') : null;
-}
-/** Sort direction and NULLS placement together — PostgreSQL resolves both from the same `IndexElem`. */
-function indexElemSortSpec(param) {
-    if (!isRecord(param) || !isRecord(param.IndexElem))
-        return { ordering: null, nullsOrdering: null };
-    const { ordering, nulls_ordering: nullsOrdering } = param.IndexElem;
-    return {
-        ordering: typeof ordering === 'string' ? ordering : null,
-        nullsOrdering: typeof nullsOrdering === 'string' ? nullsOrdering : null,
-    };
-}
-function indexParamDetail(param) {
-    return {
-        name: indexElemName(param),
-        opclass: indexElemOpclass(param),
-        ...indexElemSortSpec(param),
-    };
-}
-/**
- * Deep-clones a parser AST node with `location` fields stripped, so two
- * predicates that are byte-identical apart from source position compare
- * equal via JSON.stringify.
- */
-function stripLocations(value) {
-    if (Array.isArray(value))
-        return value.map(stripLocations);
-    if (!isRecord(value))
-        return value;
-    const result = {};
-    for (const [key, child] of Object.entries(value)) {
-        if (key === 'location')
-            continue;
-        result[key] = stripLocations(child);
-    }
-    return result;
-}
-function whereClauseKey(whereClause) {
-    if (whereClause === undefined || whereClause === null)
-        return null;
-    return JSON.stringify(stripLocations(whereClause));
-}
-export function extractCreateIndexMetadata(content) {
-    const indexes = [];
-    const parseResult = parseSql(content);
-    for (const rawStmt of parseResult.stmts ?? []) {
-        const node = rawStmt.stmt;
-        /* v8 ignore next */
-        if (!node)
-            continue;
-        if ('CreateStmt' in node) {
-            collectCreateStmtImplicitIndexes(node.CreateStmt, rawStmt.stmt_location ?? 0, indexes);
-            continue;
-        }
-        /* v8 ignore next */
-        if (!('IndexStmt' in node))
-            continue;
-        const indexStmt = node.IndexStmt;
-        const relname = indexStmt.relation?.relname;
-        /* v8 ignore next */
-        if (!relname)
-            continue;
-        const indexParams = indexStmt.indexParams ?? [];
-        indexes.push({
-            relname,
-            idxname: indexStmt.idxname ?? null,
-            unique: indexStmt.unique === true,
-            indexParams: indexParams.map(indexElemName),
-            indexParamDetails: indexParams.map(indexParamDetail),
-            includeParams: (indexStmt.indexIncludingParams ?? [])
-                .map(indexElemName)
-                .filter((name) => name !== null),
-            whereClause: indexStmt.whereClause ?? null,
-            whereClauseKey: whereClauseKey(indexStmt.whereClause),
-            accessMethod: indexStmt.accessMethod ?? 'btree',
-            location: rawStmt.stmt_location ?? 0,
-        });
-    }
-    return indexes;
-}