vouchington-tooling 0.85.3 → 0.86.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,7 +6,7 @@ export declare class DetailsScope {
6
6
  private readonly markdown;
7
7
  constructor(markdown: string);
8
8
  get visible(): boolean;
9
- acceptHtml(html: string, startOffset: number): void;
9
+ acceptHtml(html: string, startOffset: number, onVisibleFragment?: (value: string, offset: number) => void): void;
10
10
  finish(): void;
11
11
  private acceptTag;
12
12
  private problem;
@@ -9,15 +9,24 @@ export class DetailsScope {
9
9
  get visible() {
10
10
  return this.frames.length === 0;
11
11
  }
12
- acceptHtml(html, startOffset) {
12
+ acceptHtml(html, startOffset, onVisibleFragment) {
13
13
  const tokens = /<!--[\s\S]*?(?:-->|$)|<\/?[a-z][a-z\d:-]*(?:[^"'<>]|"[^"]*"|'[^']*')*>/giu;
14
+ let end = 0;
15
+ const emit = (value, offset) => {
16
+ if (this.visible && value.trim())
17
+ onVisibleFragment?.(value, offset);
18
+ };
14
19
  for (const token of html.matchAll(tokens)) {
20
+ emit(html.slice(end, token.index), startOffset + end);
21
+ end = token.index + token[0].length;
15
22
  if (token[0].startsWith('<!--'))
16
23
  continue;
17
24
  const tag = /^<(\/?)([a-z][a-z\d:-]*)/iu.exec(token[0]);
18
25
  const name = tag[2].toLowerCase();
19
- if (name !== 'details' && name !== 'summary')
26
+ if (name !== 'details' && name !== 'summary') {
27
+ emit(token[0], startOffset + token.index);
20
28
  continue;
29
+ }
21
30
  const line = this.markdown.slice(0, startOffset + token.index).split('\n').length;
22
31
  if (/\/\s*>$/u.test(token[0])) {
23
32
  this.problem(line, `${tag[2]} cannot be self-closing`);
@@ -25,6 +34,7 @@ export class DetailsScope {
25
34
  }
26
35
  this.acceptTag(name, tag[1] === '/', line);
27
36
  }
37
+ emit(html.slice(end), startOffset + end);
28
38
  }
29
39
  finish() {
30
40
  for (const frame of this.frames)
@@ -8,5 +8,7 @@ export type { MarkdownVisibleSection, MarkdownSectionsDiagnostic, MarkdownSectio
8
8
  export { markdownSectionBetweenHeadings } from './sections.mts';
9
9
  export { extractMarkdownTables, parseMarkdownTables } from './tables.mts';
10
10
  export { markdownNodeText } from './text.mts';
11
+ export { parseVisibleMarkdownContent } from './visible-content.mts';
12
+ export type { MarkdownVisibleBlock, MarkdownVisibleContent } from './visible-content-types.mts';
11
13
  export { hasUncheckedMarkdownTask } from './tasks.mts';
12
14
  export type { LooseMarkdownTableRow, LooseMarkdownTableRowsOptions, MarkdownNode, MarkdownHtmlBlockType, MarkdownHtmlFact, MarkdownSourcePosition, MarkdownSourceSpan, MarkdownSection, MarkdownSectionOptions, MarkdownTableRow, MarkdownTextOptions, ParseMarkdownTablesOptions, PositionedMarkdownTable, } from './types.mts';
@@ -7,4 +7,5 @@ export { validateMarkdownSections } from "./validate-sections.mjs";
7
7
  export { markdownSectionBetweenHeadings } from "./sections.mjs";
8
8
  export { extractMarkdownTables, parseMarkdownTables } from "./tables.mjs";
9
9
  export { markdownNodeText } from "./text.mjs";
10
+ export { parseVisibleMarkdownContent } from "./visible-content.mjs";
10
11
  export { hasUncheckedMarkdownTask } from "./tasks.mjs";
@@ -0,0 +1,40 @@
1
+ import type { MarkdownSectionsDiagnostic } from './document-types.mts';
2
+ import type { MarkdownSourcePosition } from './types.mts';
3
+ type PositionedBlock = {
4
+ position: MarkdownSourcePosition;
5
+ };
6
+ /** Source-backed facts from content outside every details disclosure. */
7
+ export type MarkdownVisibleBlock = (PositionedBlock & {
8
+ kind: 'heading';
9
+ depth: number;
10
+ text: string;
11
+ }) | (PositionedBlock & {
12
+ kind: 'paragraph';
13
+ text: string;
14
+ }) | (PositionedBlock & {
15
+ kind: 'list-item';
16
+ ordered: boolean;
17
+ text: string;
18
+ }) | (PositionedBlock & {
19
+ kind: 'table';
20
+ headers: string[];
21
+ rows: Array<{
22
+ cells: string[];
23
+ position: MarkdownSourcePosition;
24
+ }>;
25
+ }) | (PositionedBlock & {
26
+ kind: 'fenced-code';
27
+ language: string | null;
28
+ value: string;
29
+ }) | (PositionedBlock & {
30
+ kind: 'raw-html';
31
+ block: boolean;
32
+ value: string;
33
+ });
34
+ export type MarkdownVisibleContent = {
35
+ /** Visible prose in source order, counted once; code, images, comments, and HTML are excluded. */
36
+ text: string;
37
+ blocks: MarkdownVisibleBlock[];
38
+ diagnostics: MarkdownSectionsDiagnostic[];
39
+ };
40
+ export {};
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ import type { MarkdownVisibleContent } from './visible-content-types.mts';
2
+ /** Parses source-positioned, visible Markdown facts without interpreting prose semantics. */
3
+ export declare function parseVisibleMarkdownContent(markdown: string): MarkdownVisibleContent;
@@ -0,0 +1,114 @@
1
+ import { parseGfmMarkdown } from "./ast.mjs";
2
+ import { DetailsScope } from "./details-scope.mjs";
3
+ const normalized = (value) => value.replace(/\s+/gu, ' ').trim();
4
+ const positionOf = (node) => node.position;
5
+ /** Parses source-positioned, visible Markdown facts without interpreting prose semantics. */
6
+ export function parseVisibleMarkdownContent(markdown) {
7
+ const blocks = [];
8
+ const scope = new DetailsScope(markdown);
9
+ const acceptHtml = (node, block) => {
10
+ const fragments = [];
11
+ scope.acceptHtml(node.value, node.position.start.offset, (value) => fragments.push(value));
12
+ // Raw HTML may render text that the Markdown AST cannot measure. Surface it for callers to
13
+ // reject in governed sections; inline tags retain their adjacent AST text nodes instead.
14
+ if (fragments.length)
15
+ blocks.push({
16
+ kind: 'raw-html',
17
+ block,
18
+ value: fragments.join(''),
19
+ position: positionOf(node),
20
+ });
21
+ };
22
+ const inlineText = (node) => {
23
+ if (node.type === 'html') {
24
+ acceptHtml(node, false);
25
+ return '';
26
+ }
27
+ if (node.type === 'image' || node.type === 'imageReference' || node.type === 'inlineCode')
28
+ return '';
29
+ if (node.type === 'text')
30
+ return scope.visible ? node.value : '';
31
+ if (node.type === 'break')
32
+ return scope.visible ? ' ' : '';
33
+ if (!('children' in node))
34
+ return '';
35
+ return node.children.map(inlineText).join('');
36
+ };
37
+ const visit = (node, ordered = false) => {
38
+ if (node.type === 'html') {
39
+ acceptHtml(node, true);
40
+ return;
41
+ }
42
+ if (node.type === 'code') {
43
+ const offset = positionOf(node).start.offset;
44
+ if (scope.visible && /^(?:`{3,}|~{3,})/u.test(markdown.slice(offset))) {
45
+ blocks.push({
46
+ kind: 'fenced-code',
47
+ language: node.lang ?? null,
48
+ value: node.value,
49
+ position: positionOf(node),
50
+ });
51
+ }
52
+ return;
53
+ }
54
+ if (node.type === 'heading' || node.type === 'paragraph') {
55
+ const text = normalized(node.children.map(inlineText).join(''));
56
+ if (text) {
57
+ if (node.type === 'heading')
58
+ blocks.push({ kind: 'heading', depth: node.depth, text, position: positionOf(node) });
59
+ else
60
+ blocks.push({ kind: 'paragraph', text, position: positionOf(node) });
61
+ }
62
+ return;
63
+ }
64
+ if (node.type === 'listItem') {
65
+ const pieces = [];
66
+ for (const child of node.children) {
67
+ if (child.type === 'paragraph')
68
+ pieces.push(inlineText(child));
69
+ else
70
+ visit(child);
71
+ }
72
+ const text = normalized(pieces.join(' '));
73
+ if (text)
74
+ blocks.push({ kind: 'list-item', ordered, text, position: positionOf(node) });
75
+ return;
76
+ }
77
+ if (node.type === 'list') {
78
+ for (const child of node.children)
79
+ visit(child, node.ordered === true);
80
+ return;
81
+ }
82
+ if (node.type === 'table') {
83
+ const rows = node.children.map((row) => ({
84
+ cells: row.children.map((cell) => normalized(inlineText(cell))),
85
+ position: positionOf(row),
86
+ }));
87
+ if (rows.some((row) => row.cells.some(Boolean))) {
88
+ blocks.push({
89
+ kind: 'table',
90
+ headers: rows[0].cells,
91
+ rows: rows.slice(1),
92
+ position: positionOf(node),
93
+ });
94
+ }
95
+ return;
96
+ }
97
+ if (!('children' in node))
98
+ return;
99
+ for (const child of node.children)
100
+ visit(child);
101
+ };
102
+ visit(parseGfmMarkdown(markdown));
103
+ scope.finish();
104
+ blocks.sort((a, b) => a.position.start.offset - b.position.start.offset);
105
+ const text = blocks
106
+ .flatMap((block) => {
107
+ if (block.kind === 'table')
108
+ return [...block.headers, ...block.rows.flatMap((row) => row.cells)];
109
+ return 'text' in block ? [block.text] : [];
110
+ })
111
+ .filter(Boolean)
112
+ .join('\n');
113
+ return { text, blocks, diagnostics: scope.diagnostics };
114
+ }
@@ -12,9 +12,10 @@ export type PullRequestProvenance = {
12
12
  };
13
13
  /**
14
14
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
15
- * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
16
- * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
17
- * the caller supplies the device and worktree facts.
15
+ * provenance lines, collapsed in a Provenance disclosure because they serve audits, not reviewers.
16
+ * With `noSourceIssue` the Related issues section ends with `noSourceStatement` (default
17
+ * {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure; the caller
18
+ * supplies the device and worktree facts. Throws when the fields leave a code fence open.
18
19
  */
19
20
  export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
20
21
  /**
@@ -1,5 +1,6 @@
1
1
  import { basename } from 'node:path';
2
2
  import { formatReferenceKey } from "../gh-cli/closing-refs.mjs";
3
+ import { assertNoOpenFence } from "./pr-journal.mjs";
3
4
  function relatedLine(issue) {
4
5
  const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
5
6
  const [owner, repo] = issue.repository?.split('/') ?? [];
@@ -11,9 +12,10 @@ function defaultNoSourceStatement(reason) {
11
12
  }
12
13
  /**
13
14
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
14
- * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
15
- * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
16
- * the caller supplies the device and worktree facts.
15
+ * provenance lines, collapsed in a Provenance disclosure because they serve audits, not reviewers.
16
+ * With `noSourceIssue` the Related issues section ends with `noSourceStatement` (default
17
+ * {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure; the caller
18
+ * supplies the device and worktree facts. Throws when the fields leave a code fence open.
17
19
  */
18
20
  export function renderPullRequestBody(input, provenance, noSourceStatement) {
19
21
  const related = input.relatedIssues.map(relatedLine);
@@ -21,7 +23,7 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
21
23
  related.push(noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason));
22
24
  if (!related.length)
23
25
  related.push('- None');
24
- return [
26
+ const fields = [
25
27
  '## Summary',
26
28
  '',
27
29
  input.summary,
@@ -37,12 +39,22 @@ export function renderPullRequestBody(input, provenance, noSourceStatement) {
37
39
  '## Details',
38
40
  '',
39
41
  input.details.join('\n\n'),
42
+ ].join('\n');
43
+ // An unclosed fence would turn the Provenance disclosure and its lines into visible code.
44
+ assertNoOpenFence(fields);
45
+ return [
46
+ fields,
47
+ '',
48
+ '<details>',
49
+ '<summary>Provenance</summary>',
40
50
  '',
41
51
  `Workspace setup: ${input.workspaceSetup}`,
42
52
  `Agent: ${provenance.agent} session ${provenance.sessionId}`,
43
53
  `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
44
54
  `Worktree: ${provenance.worktree}`,
45
55
  '',
56
+ '</details>',
57
+ '',
46
58
  ].join('\n');
47
59
  }
48
60
  const MARKER = '/worktrees/';
@@ -10,3 +10,5 @@ export declare function findShepherdJournal(body: string): string | undefined;
10
10
  * their own, and must not leave a code fence open: the journal would be hidden inside it.
11
11
  */
12
12
  export declare function preserveShepherdJournal(rendered: string, live: string): string;
13
+ /** Rejects text that ends inside an unclosed code fence: whatever follows would render as code. */
14
+ export declare function assertNoOpenFence(text: string): void;
@@ -80,7 +80,11 @@ export function preserveShepherdJournal(rendered, live) {
80
80
  const journal = findShepherdJournal(live);
81
81
  if (journal === undefined)
82
82
  return rendered;
83
- if (outsideFences(rendered.replaceAll('\r\n', '\n').split('\n')).open)
84
- throw new Error('the pull request fields leave a code fence open; close it');
83
+ assertNoOpenFence(rendered);
85
84
  return `${rendered.trimEnd()}\n\n${journal}\n`;
86
85
  }
86
+ /** Rejects text that ends inside an unclosed code fence: whatever follows would render as code. */
87
+ export function assertNoOpenFence(text) {
88
+ if (outsideFences(text.replaceAll('\r\n', '\n').split('\n')).open)
89
+ throw new Error('the pull request fields leave a code fence open; close it');
90
+ }
@@ -64,7 +64,8 @@ const FIELDS = {
64
64
  };
65
65
  const REQUIRED = ['title', 'summary', 'impact', 'relatedIssues', 'details', 'workspaceSetup'];
66
66
  const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
67
- 'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
67
+ 'Details, then Workspace setup, Agent, Device and Worktree lines in a collapsed Provenance ' +
68
+ 'disclosure) and runs the checkout ' +
68
69
  'policy validatePullRequest export in a child process; the head branch is the ' +
69
70
  "worktree's current branch. Policy tools need a server launched inside a repository worktree. ";
70
71
  export const PR_TOOLS = [
@@ -88,4 +88,5 @@ export declare function loadPostgresParser(caller: string): Promise<{
88
88
  }>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").PostgresCompleteCatalog>>;
89
89
  generatePostgresCatalog(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").PostgresCatalogOptions>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").PostgresCatalog>>;
90
90
  analyzeTypeScriptModules(options: import("no-mistakes").WithInvocationOptions<import("no-mistakes").TypeScriptModulesOptions>): Promise<import("no-mistakes").WithInvocationResult<import("no-mistakes").TypeScriptModulesReport>>;
91
+ lockStatus(): Promise<import("no-mistakes").LockStatus>;
91
92
  }>;
@@ -362,12 +362,20 @@ rule) and `pullRequestDefaults`.
362
362
 
363
363
  <details joined by blank lines>
364
364
 
365
+ <details>
366
+ <summary>Provenance</summary>
367
+
365
368
  Workspace setup: <workspaceSetup>
366
369
  Agent: <derived agent | unknown>[ (caller-claimed ...)] session <sessionId>
367
370
  Device: <os user>@<lowercased hostname>
368
371
  Worktree: <path after "/worktrees/", "main" for the main worktree, else the directory name>
372
+
373
+ </details>
369
374
  ```
370
375
 
376
+ The provenance lines are collapsed because they serve audits, not reviewers; each still starts its
377
+ own line, so a policy can match them with line-anchored patterns.
378
+
371
379
  The head branch is the worktree's current branch (for `pr_validate` with `pr`, the live pull
372
380
  request's head, which may equal `base` for a fork); otherwise a detached HEAD, or a head equal to `base`, is rejected. The body must stay within GitHub's 65536 characters. `pr_create` sees no stack membership,
373
381
  so a consumer policy may reject any `base` other than the default branch; create stacked layers
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vouchington-tooling",
3
- "version": "0.85.3",
3
+ "version": "0.86.1",
4
4
  "description": "Vouchington CLI and extractable tooling libraries.",
5
5
  "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
6
6
  "bugs": {
@@ -536,11 +536,11 @@
536
536
  "@types/react": "19.3.0",
537
537
  "@types/react-dom": "19.3.0",
538
538
  "@types/spdx-expression-parse": "4.0.0",
539
- "@vouchington/postgres": "0.1.2",
540
- "@vouchington/worker-runtime": "0.2.1",
539
+ "@vouchington/postgres": "0.4.0",
540
+ "@vouchington/worker-runtime": "0.3.1",
541
541
  "glide-mq": "^0.20.0",
542
542
  "next": "16.4.3",
543
- "no-mistakes": "0.101.0",
543
+ "no-mistakes": "0.108.0",
544
544
  "pg": "8.23.1",
545
545
  "react": "19.3.1",
546
546
  "react-dom": "19.3.1",
@@ -44,11 +44,13 @@ A run's cost is the rows it reads and the work it starts, not the memory it hold
44
44
  continue with a plain keyset cursor, `(key, id) < ($1, $2)`. The page `LIMIT` plus a time window
45
45
  or the keyset bound the read. A keyset alone does not bound rows scanned. When a filter can
46
46
  reject long runs, such as a viewer's blocks or mutes, the time window is the scan bound where the
47
- sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. No
48
- candidate pools: no capped or `MATERIALIZED` CTE over the listed entity that is filtered or
49
- limited afterward, no window loops or resume probes, no proof state in the cursor, and no
50
- runtime-config fields that exist only to cap a read. A page is never short or empty while
51
- `has_next_page` is true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
47
+ sort has one, and EXPLAIN at representative cardinality compares rows read with rows returned. The
48
+ simplest query comes first; anything more complex needs `EXPLAIN ANALYZE` plans beating it. For a
49
+ ranked list that is a join and `ORDER BY` on the stored score. No candidate pools: no capped or
50
+ `MATERIALIZED` CTE over the listed entity that is filtered or limited afterward, no window loops
51
+ or resume probes, no proof state in the cursor, and no runtime-config fields that exist only to
52
+ cap a read. A single walk with an inspected-row cap is fine, and may return a short or empty page
53
+ with a continuation cursor and `has_next_page` true. Small viewer-scoped sets (the viewer's follows, mutes, blocks and
52
54
  memberships) may be subqueries or semi-joins, because write limits bound them. Measure a
53
55
  list-read change against the plain single walk, not only against the base branch. See
54
56
  [`MATERIALIZED` CTEs](../postgres-node-performance-tuning/references/performance-patterns.md).
@@ -342,6 +342,9 @@ CROSS JOIN LATERAL (
342
342
  ) due;
343
343
  ```
344
344
 
345
+ This is a complex shape: keep it only with `EXPLAIN ANALYZE` plans showing it beats the plain
346
+ query.
347
+
345
348
  The loose scan beats a small thresholds table here because the intervals are chosen per row and
346
349
  there is no second source of truth to drift. If the intervals are a fixed, reviewed set, a
347
350
  thresholds table is just as bounded. Either way the bucket count must itself be bounded, for
@@ -44,7 +44,8 @@ option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
44
44
 
45
45
  Dispatchers, paged fan-out, and job-id deduplication follow
46
46
  [bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
47
- replaces holding a PostgreSQL transaction or advisory lock open across it; see
47
+ replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
48
+ used; see
48
49
  [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
49
50
 
50
51
  Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
@@ -30,7 +30,7 @@
30
30
  {
31
31
  "name": "bounded-iteration",
32
32
  "plugin": "vouchington-database",
33
- "pluginVersion": "0.10.0",
33
+ "pluginVersion": "0.11.0",
34
34
  "path": "bounded-iteration/SKILL.md"
35
35
  },
36
36
  {
@@ -81,7 +81,7 @@
81
81
  {
82
82
  "name": "glide-mq",
83
83
  "plugin": "vouchington-database",
84
- "pluginVersion": "0.10.0",
84
+ "pluginVersion": "0.11.0",
85
85
  "path": "glide-mq/SKILL.md"
86
86
  },
87
87
  {
@@ -127,19 +127,19 @@
127
127
  {
128
128
  "name": "postgres-node-performance-tuning",
129
129
  "plugin": "vouchington-database",
130
- "pluginVersion": "0.10.0",
130
+ "pluginVersion": "0.11.0",
131
131
  "path": "postgres-node-performance-tuning/SKILL.md"
132
132
  },
133
133
  {
134
134
  "name": "postgres-partitioning-uuid-v7",
135
135
  "plugin": "vouchington-database",
136
- "pluginVersion": "0.10.0",
136
+ "pluginVersion": "0.11.0",
137
137
  "path": "postgres-partitioning-uuid-v7/SKILL.md"
138
138
  },
139
139
  {
140
140
  "name": "postgres-schema-design",
141
141
  "plugin": "vouchington-database",
142
- "pluginVersion": "0.10.0",
142
+ "pluginVersion": "0.11.0",
143
143
  "path": "postgres-schema-design/SKILL.md"
144
144
  },
145
145
  {
@@ -11,6 +11,12 @@ Local policy overrides these defaults; do not reload an already-read adapter or
11
11
 
12
12
  Measure the query plan and the workload shape before changing code.
13
13
 
14
+ Owner's principle: "the basic premise is to use the simplest query, and making it more complex
15
+ requires explain analyze plans". Start with filters in `WHERE`, keyed `EXISTS`, joins or
16
+ subqueries, `ORDER BY`, and `LIMIT`. A complex shape stays only with `EXPLAIN ANALYZE` plans showing
17
+ it beats that simple query, not merely the previous version; see
18
+ [simplest query first](references/performance-patterns.md#simplest-query-first).
19
+
14
20
  - Select only the required columns.
15
21
  - Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
16
22
  the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
@@ -3,8 +3,8 @@
3
3
  Use pools and release checked-out clients in `finally`, especially for cursors, streams, and COPY.
4
4
  Route ordinary reads to a replica when its lag is acceptable; route read-after-write, locking, and
5
5
  transaction-consistent reads to the writer. Do not hold a client across unrelated application work.
6
- Never hold a transaction, connection, or advisory lock across an external call; take a token lease
7
- in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
6
+ Never use advisory locks, and never hold a transaction or connection across an external call; take
7
+ a token lease in a shared store instead, with a TTL, renewal, and compare-and-delete release. Stop work when
8
8
  renewal fails, and guard any write a stale owner could make with the token.
9
9
 
10
10
  For large reads, use keyset pagination, cursors, or streams with cancellation and bounded batches.
@@ -21,6 +21,19 @@ data, but it does not replace suitable local indexes or predicates that permit p
21
21
 
22
22
  ## Query shapes
23
23
 
24
+ ### Simplest query first
25
+
26
+ Owner's principle: "hot/best should just be a JOIN and an ORDER BY". A ranked sort joins the
27
+ entity to its stored score and orders by it. Filters go in `WHERE`; membership is a keyed `EXISTS`,
28
+ join, or subquery; then `ORDER BY` and `LIMIT`.
29
+
30
+ These need `EXPLAIN ANALYZE` plans, at representative cardinality, showing they beat the simple
31
+ query for the same result, not merely the previous version on the base branch: `MATERIALIZED` or
32
+ capped candidate CTEs, `UNION`, `GROUP BY` or `DISTINCT` dedupe, `LATERAL` joins and planner
33
+ fences, cohort or window ranking, and multi-stage cap-filter-rank pipelines. Never build a
34
+ candidate pool. A walk that stops at an inspected-row cap and returns a short or empty page with a
35
+ continuation cursor is fine.
36
+
24
37
  Test existence with `EXISTS`, not `COUNT(*) > 0`. Use correlated `NOT EXISTS` rather than
25
38
  `NOT IN (SELECT ...)`, whose NULL behavior can silently exclude expected rows. Filter and order
26
39
  UUIDv7 rows by `id`, not generated `created_at`, so the key's index supports the query.
@@ -32,7 +45,8 @@ Use keyset pagination, never `OFFSET`. An optimizer fence is a `MATERIALIZED` CT
32
45
  The outer query still reads CTE rows on demand and can stop at its `LIMIT`, but when its filters
33
46
  reject most CTE rows, or it sorts, aggregates or hash-joins them, it reads every row up to the CTE's own
34
47
  `LIMIT`. Use a `MATERIALIZED` CTE only when it holds the final `LIMIT`, or for a small
35
- viewer-scoped set. Never use it as a candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
48
+ viewer-scoped set, and only with plans showing it beats the plain query. Never use it as a
49
+ candidate pool before the page `LIMIT`. Constrain a partitioned table's partition key, or document the reason for a
36
50
  cross-partition query. Choose the partition key from dominant access patterns; a hot reader
37
51
  of `RANGE (id)` needs an id or time bound.
38
52
 
@@ -98,7 +112,8 @@ count over its output. A restriction on a grouping column can still be pushed be
98
112
  so let the plan decide. Confirm from the
99
113
  plan (large `Actual Rows` and `Actual Loops` inside the view's nodes), then choose the ids from the
100
114
  base tables first and read the view by its key, as a correlated `LATERAL` lookup so the page
101
- restriction can reach inside the view. This works for an aggregate or `GROUP BY` view whose key is
115
+ restriction can reach inside the view. Reach for this only after the plan shows the simple
116
+ query builds the whole view, and keep it only if its plan beats the simple query. This works for an aggregate or `GROUP BY` view whose key is
102
117
  a grouping column; a `LIMIT` in the view blocks pushdown of any qual, so rewrite that view's query
103
118
  against the base tables instead. A plain join to the page is a join clause, not a restriction
104
119
  inside the view, so the planner can still build the whole aggregate first.
@@ -148,7 +163,9 @@ Overlap independent cache and PostgreSQL reads with `Promise.all`, such as a rat
148
163
  alongside the user fetch. Serialize only true dependencies, where one result feeds the next call. Suppress the
149
164
  sequential-await lint only when each step consumes the previous step's result; a shared
150
165
  transaction client or lock ordering is not a data dependency. A lock that must be taken first
151
- stays a separate, earlier statement; never reorder or parallelize it. Audit every added suppression.
166
+ stays a separate, earlier statement; never reorder or parallelize it. Do not keep a lock only
167
+ because it exists: one that fails the lock rule in
168
+ [schema design](../../postgres-schema-design/SKILL.md) is deleted. Audit every added suppression.
152
169
 
153
170
  Correctness comes before round trips. Before folding a statement away, state the guarantee it
154
171
  gave (what it locked, which snapshot it read) and reject the fold if that weakens. An `EXISTS`
@@ -14,6 +14,13 @@ Local policy overrides these portable conventions.
14
14
  - Split differing shapes, share identical values, and keep history documents as JSON.
15
15
  - Use canonical [table shapes](references/table-shapes.md) for revisions, changes, work, and cursors.
16
16
  - Default to finite retention for everything except user content; see [table shapes](references/table-shapes.md#retention).
17
+ - No unnecessary locks. Owner's words: "do we have a rule? no unnecessary locks", "seems like we
18
+ have way too many locks for no reason", "keep things simple". Lock (`FOR UPDATE`) only when a
19
+ concurrent write would corrupt the rows this transaction writes. Never lock a read set or a
20
+ parent row, and never use advisory locks. Caps and "don't remove the last X" guards are best
21
+ effort: count up to the cap (`LIMIT cap+1`), then write. Never add counter or projection tables,
22
+ slot tables, claim tables, or constraints that exist only to make a cap exact. Remove a lock by
23
+ deleting it, not by swapping in another serializer.
17
24
  - Reuse parameterized trigger functions instead of copying bodies.
18
25
  - Comment every table, column, and view; document reviewed exceptions explicitly.
19
26
 
@@ -29,7 +29,9 @@ Default to a queue job whose job id is the durable row id, enqueued after commit
29
29
  sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
30
30
  backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
31
31
  reason: legal or payment records, old values that vanish at commit, or an outcome that must
32
- commit with domain rows.
32
+ commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
33
+ for a cap; count up to the cap and write, as in the lock rule in
34
+ [schema design](../SKILL.md).
33
35
 
34
36
  When a table is justified, fence with one compare-and-set on the outcome or a generation
35
37
  (`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.