@pikku/skills 0.12.26 → 0.12.28

package/skills/pikku-blueprint-to-fabric/scripts/inventory.mjs

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+// Emit the Pikku implementation inventory for a .knowledge/ blueprint.
+//
+//   node inventory.mjs <path-to-.knowledge> [--json] [--domain <Name>]
+//
+// Answers "what will actually be built?" BEFORE any code exists: every pikkuFunc,
+// permission, scheduler, queue worker, workflow, HTTP wiring, event channel,
+// table and scenario — plus, crucially, what is BLOCKED by an unresolved decision
+// and what is deliberately NOT built.
+//
+// This is a projection of the blueprint, not a plan you write by hand. It is
+// derived, so it stays honest: if it says 187 functions, the blueprint says 187.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const dir = process.argv[2]
+const asJson = process.argv.includes('--json')
+const domainArg = process.argv.includes('--domain')
+  ? process.argv[process.argv.indexOf('--domain') + 1]
+  : null
+
+if (!dir) {
+  console.error('usage: inventory.mjs <path-to-.knowledge> [--json] [--domain <Name>]')
+  process.exit(2)
+}
+
+// The four files pikku-software-archaeology's schema marks `x-optional` — an
+// API-only app really has no frontend. Every other file is REQUIRED, and a
+// missing or unparseable one is fatal rather than an empty list: this script's
+// whole claim is that its counts come from the blueprint, so silently reporting
+// "0 commands" for a directory that isn't a blueprint tells the exact lie the
+// inventory exists to prevent.
+const OPTIONAL = new Set([
+  'interfaces.json',
+  'frontend.json',
+  'frontend-routes.json',
+  'frontend-components.json',
+])
+
+const fatal = (msg) => {
+  console.error(`inventory: ${msg}`)
+  process.exit(1)
+}
+
+if (!existsSync(dir)) fatal(`no such directory: ${dir}`)
+
+const read = (f) => {
+  const p = join(dir, f)
+  if (!existsSync(p)) {
+    if (OPTIONAL.has(f)) return null
+    fatal(
+      `${dir} is missing ${f}. Run the archaeology validator first — ` +
+        `an incomplete blueprint gives a count that reads as complete.`
+    )
+  }
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'))
+  } catch (e) {
+    fatal(`${f} is not valid JSON: ${e.message}`)
+  }
+}
+
+/** A required file that parsed but carries the wrong shape is the same lie. */
+const list = (f, key) => {
+  const doc = read(f)
+  if (doc === null) return []
+  const rows = doc[key]
+  if (rows === undefined) fatal(`${f} has no "${key}" array — blueprint shape changed?`)
+  if (!Array.isArray(rows)) fatal(`${f}: "${key}" is ${typeof rows}, expected an array`)
+  return rows
+}
+
+const domains = list('domains.json', 'domains')
+const entities = list('entities.json', 'entities')
+const commands = list('commands.json', 'commands')
+const queries = list('queries.json', 'queries')
+const events = list('events.json', 'events')
+const policies = list('policies.json', 'policies')
+const workflows = list('workflows.json', 'workflows')
+const apiDoc = read('api.json')
+const api = apiDoc.surfaces ?? apiDoc.api ?? fatal('api.json has neither "surfaces" nor "api"')
+const integrations = list('integrations.json', 'integrations')
+const migration = read('migration.json')
+const interfaces = read('interfaces.json')?.interfaces ?? []
+const feComponents = read('frontend-components.json')?.components ?? []
+const feRoutes = read('frontend-routes.json')?.routes ?? []
+
+// ---- the decisions gate -----------------------------------------------------
+// A concept named in an unresolved decision's blockedConcepts cannot be built.
+//
+// Answers are recorded OUTSIDE the blueprint — in the rebuild's own knowledge
+// base — because the blueprint is a record of the LEGACY app and must not be
+// rewritten as the rebuild proceeds. So pass the ones already answered:
+//
+//   --resolved 1,2,3        (1-based index into migration.json.decisionsNeeded)
+//
+// Anything not listed is still blocking.
+const allDecisions = migration.decisionsNeeded ?? []
+const resolvedArg = process.argv.includes('--resolved')
+  ? process.argv[process.argv.indexOf('--resolved') + 1]
+  : ''
+const resolvedIdx = new Set(
+  resolvedArg.split(',').map((s) => parseInt(s.trim(), 10)).filter(Boolean)
+)
+const decisions = allDecisions.filter((_, i) => !resolvedIdx.has(i + 1))
+const resolved = allDecisions.filter((_, i) => resolvedIdx.has(i + 1))
+const blocked = new Map() // concept -> question
+for (const d of decisions) {
+  for (const c of d.blockedConcepts ?? []) {
+    if (!blocked.has(c)) blocked.set(c, d.question)
+  }
+}
+const dropped = migration.dropped ?? []
+const droppedNames = new Set(
+  dropped.map((d) => (d.path ?? d.file ?? '').split('/').pop())
+)
+
+const isBlocked = (name, domain) => blocked.has(name) || blocked.has(domain)
+
+// ---- classification ---------------------------------------------------------
+// Cron-ish triggers. The blueprint records schedules in prose ("daily at 05:00",
+// "every minute"), because that is how the legacy code expressed them.
+const CRON = /(cron|daily|nightly|hourly|every minute|every \d|schedule|at \d{2}:\d{2})/i
+const QUEUE = /(queue|consumer|perform_later|sidekiq|worker|async)/i
+const WEBHOOK = /(webhook|POST \/webhooks)/i
+// A trigger that fires off a row write is the legacy shape of an EVENT, not of a
+// workflow — a handler doing five unrelated things because there was no bus.
+// These become an event + its consumers, which is the structural upgrade.
+const EVENT = /(after_commit|after_save|on create\/update\/destroy|observer|callback|mirror)/i
+
+const classifyWorkflow = (w) => {
+  const t = `${w.name} ${w.trigger ?? ''}`
+  if (w.kind === 'system') {
+    if (WEBHOOK.test(t)) return 'wireHTTP + command (webhook ingress)'
+    if (CRON.test(t)) return 'wireScheduler'
+    if (EVENT.test(t)) return 'event consumer (realtime/queue)'
+    if (QUEUE.test(t)) return 'wireQueueWorker'
+    return 'pikkuWorkflowFunc'
+  }
+  // User and admin journeys are NOT pikku workflows — they are sequences of
+  // commands a person drives through the UI. They become scenarios.
+  return 'scenario (user journey)'
+}
+
+// HTTP is warranted ONLY where the caller is a system we do not control and
+// cannot ask to speak RPC — i.e. it POSTs to a URL we publish, on its schedule.
+// In practice that means inbound webhooks.
+//
+// Everything else is RPC, including surfaces that look like they need HTTP:
+//   - `auth: none` means anonymous, not external. Our own sign-up page calls it.
+//   - a tokened/capability URL (a check-in link, a public share link) is a
+//     first-party page reading a token; the page can call RPC like any other.
+// The caller being ours is what decides this, not the URL's shape or its auth.
+const needsHttp = (s) => /webhook/i.test(s.path ?? '')
+
+const byDomain = (arr) => {
+  const m = new Map()
+  for (const x of arr) {
+    const d = x.domain ?? 'unassigned'
+    if (!m.has(d)) m.set(d, [])
+    m.get(d).push(x)
+  }
+  return m
+}
+
+const cmdByDomain = byDomain(commands)
+const qryByDomain = byDomain(queries)
+const polByDomain = byDomain(policies)
+const evtByDomain = byDomain(events)
+const entByDomain = byDomain(entities)
+
+const schedulers = workflows.filter((w) => classifyWorkflow(w) === 'wireScheduler')
+const queueWorkers = workflows.filter((w) => classifyWorkflow(w) === 'wireQueueWorker')
+const ingress = workflows.filter((w) => classifyWorkflow(w).startsWith('wireHTTP'))
+const eventConsumers = workflows.filter((w) => classifyWorkflow(w) === 'event consumer (realtime/queue)')
+const pikkuWorkflows = workflows.filter((w) => classifyWorkflow(w) === 'pikkuWorkflowFunc')
+const journeys = workflows.filter((w) => classifyWorkflow(w) === 'scenario (user journey)')
+const httpSurfaces = api.filter(needsHttp)
+const scenarioCount = workflows.reduce((n, w) => n + (w.scenarios ?? []).length, 0)
+
+const blockedCommands = commands.filter((c) => isBlocked(c.name, c.domain))
+const blockedQueries = queries.filter((q) => isBlocked(q.name, q.domain))
+const customLogic = feComponents.filter((c) => c.rebuild === 'custom-logic')
+const cheapComponents = feComponents.filter((c) => c.rebuild !== 'custom-logic')
+
+// ---- addons -----------------------------------------------------------------
+// An addon is warranted where a capability is self-contained, reused across
+// domains, and has a clear service seam — which is what a `hard`/`critical`
+// integration is. Advisory: the call is the operator's.
+const addonCandidates = integrations.filter(
+  (i) => i.importance === 'critical' || i.replacementDifficulty === 'hard'
+)
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      {
+        totals: {
+          pikkuFunc: commands.length,
+          pikkuSessionlessFuncReadonly: queries.length,
+          pikkuPermission: policies.length,
+          wireScheduler: schedulers.length,
+          wireQueueWorker: queueWorkers.length,
+          webhookIngress: ingress.length,
+          pikkuWorkflowFunc: pikkuWorkflows.length,
+          wireHTTP: httpSurfaces.length,
+          eventChannels: events.length,
+          tables: entities.length,
+          scenarios: scenarioCount,
+          blockedCommands: blockedCommands.length,
+          blockedQueries: blockedQueries.length,
+          droppedArtifacts: dropped.length,
+          customLogicComponents: customLogic.length,
+        },
+        blocked: [...blocked.entries()].map(([concept, question]) => ({ concept, question })),
+      },
+      null,
+      2
+    )
+  )
+  process.exit(0)
+}
+
+// ---- report -----------------------------------------------------------------
+const out = []
+const p = (s = '') => out.push(s)
+
+p('# Pikku implementation inventory')
+p('')
+p(`Derived from \`${dir}\`. Every number below is a projection of the blueprint —`)
+p('nothing here is estimated or invented.')
+p('')
+
+p('## Totals')
+p('')
+p('| Pikku artifact | Count | From |')
+p('|---|---:|---|')
+p(`| \`pikkuFunc\` (state-changing) | ${commands.length} | \`commands.json\` |`)
+p(`| \`pikkuSessionlessFunc\` + \`readonly: true\` | ${queries.length} | \`queries.json\` |`)
+p(`| \`pikkuPermission\` | ${policies.length} | \`policies.json\` |`)
+p(`| \`wireScheduler\` | ${schedulers.length} | \`workflows.json\` (system + cron) |`)
+p(`| \`wireQueueWorker\` | ${queueWorkers.length} | \`workflows.json\` (system + queue) |`)
+p(`| webhook ingress (\`wireHTTP\` + command) | ${ingress.length} | \`workflows.json\` (system + webhook) |`)
+p(`| \`pikkuWorkflowFunc\` | ${pikkuWorkflows.length} | \`workflows.json\` (system, multi-step) |`)
+p(`| \`wireHTTP\` (fixed external URLs only) | ${httpSurfaces.length} of ${api.length} surfaces | \`api.json\` |`)
+p(`| event channels (realtime/queue) | ${events.length} | \`events.json\` |`)
+p(`| tables | ${entities.length} | \`entities.json\` |`)
+p(`| scenarios | ${scenarioCount} | \`workflows.json[].scenarios\` |`)
+p('')
+p(`**Not built:** ${dropped.length} dropped artifacts · **Blocked:** ${blockedCommands.length + blockedQueries.length} concepts behind ${decisions.length} open decisions.`)
+p('')
+
+if (resolved.length) {
+  p('## Decisions already taken')
+  p('')
+  p('Answered at the gate and recorded in the rebuild\'s knowledge base. Each is a')
+  p('**deliberate behaviour change** and belongs in the parity report.')
+  p('')
+  for (const d of resolved) p(`- ${(d.blockedConcepts ?? []).join(', ')} — _${d.question.split('.')[0]}._`)
+  p('')
+}
+
+p('## Blocked by an open decision')
+p('')
+if (decisions.length === 0) {
+  p('_None — the gate is clear._')
+} else {
+  p('These cannot be built until the question is answered. They block **their own')
+  p('domains only** — every other slice proceeds.')
+  p('')
+  for (const d of decisions) {
+    p(`- **${(d.blockedConcepts ?? []).join(', ') || '(unscoped)'}**`)
+    p(`  <br>${d.question}`)
+    if (d.options) p(`  <br>_Options:_ ${d.options.join(' · ')}`)
+  }
+}
+p('')
+
+p('## Scheduled tasks (`wireScheduler`)')
+p('')
+p('| Workflow | Trigger |')
+p('|---|---|')
+for (const w of schedulers) p(`| ${w.name} | ${(w.trigger ?? '').replace(/\|/g, '\\|')} |`)
+p('')
+
+if (queueWorkers.length || ingress.length || pikkuWorkflows.length || eventConsumers.length) {
+  p('## Other system wiring')
+  p('')
+  p('| Workflow | Becomes |')
+  p('|---|---|')
+  for (const w of [...ingress, ...queueWorkers, ...eventConsumers, ...pikkuWorkflows])
+    p(`| ${w.name} | \`${classifyWorkflow(w)}\` |`)
+  p('')
+}
+
+p('## Journeys → scenarios')
+p('')
+p(`${journeys.length} user/admin journeys carrying ${scenarioCount} scenarios excavated from the`)
+p('legacy test suite. These are **not** `pikkuWorkflowFunc`s — they are sequences a')
+p('person drives through the UI, and they become scenario tests.')
+p('')
+p('| Journey | Kind | Scenarios |')
+p('|---|---|---:|')
+for (const w of journeys) p(`| ${w.name} | ${w.kind} | ${(w.scenarios ?? []).length} |`)
+p('')
+
+p('## Per domain')
+p('')
+p('| Domain | Tables | `pikkuFunc` | readonly | permissions | events | blocked |')
+p('|---|---:|---:|---:|---:|---:|---:|')
+for (const d of domains) {
+  const n = d.name
+  const b = (cmdByDomain.get(n) ?? []).filter((c) => isBlocked(c.name, n)).length +
+            (qryByDomain.get(n) ?? []).filter((q) => isBlocked(q.name, n)).length
+  p(
+    `| ${n} | ${(entByDomain.get(n) ?? []).length} | ${(cmdByDomain.get(n) ?? []).length} | ${(qryByDomain.get(n) ?? []).length} | ${(polByDomain.get(n) ?? []).length} | ${(evtByDomain.get(n) ?? []).length} | ${b || ''} |`
+  )
+}
+p('')
+
+p('## Addon candidates')
+p('')
+p('Advisory. A capability earns an addon when it is self-contained, reused across')
+p('domains, and has a clear service seam — which is what a critical/hard-to-replace')
+p('integration usually is. The call is yours.')
+p('')
+p('| Integration | Importance | Replace |')
+p('|---|---|---|')
+for (const i of addonCandidates)
+  p(`| ${i.name} | ${i.importance ?? ''} | ${i.replacementDifficulty ?? ''} |`)
+p('')
+
+if (feComponents.length) {
+  p('## Frontend')
+  p('')
+  p(`- **${cheapComponents.length}** components are a cheap re-expression in Mantine (standard / composition / restyle).`)
+  p(`- **${customLogic.length}** carry \`custom-logic\` and must be **ported**. This is the real frontend project.`)
+  p(`- **${feRoutes.length}** routes → TanStack routes; their \`dataFrom\` names are already the function names above.`)
+  p('')
+  if (customLogic.length) {
+    p('| custom-logic component | What must survive |')
+    p('|---|---|')
+    for (const c of customLogic)
+      p(`| ${c.name} | ${(c.customLogic ?? '').replace(/\|/g, '\\|').slice(0, 110)} |`)
+    p('')
+  }
+}
+
+if (interfaces.length) {
+  p('## Interfaces')
+  p('')
+  p('| Channel | Audience | Status |')
+  p('|---|---|---|')
+  for (const i of interfaces) p(`| ${i.kind} | ${i.audience ?? ''} | ${i.status ?? ''} |`)
+  p('')
+}
+
+p('## Deliberately not built')
+p('')
+p('| Artifact | Why |')
+p('|---|---|')
+for (const d of dropped)
+  p(`| \`${d.path ?? d.file}\` | ${(d.reason ?? '').replace(/\|/g, '\\|').slice(0, 120)} |`)
+p('')
+
+console.log(out.join('\n'))

package/skills/pikku-knowledge/SKILL.md

@@ -141,7 +141,8 @@ And writing again replaces it rather than adding a second
 ```
 ````
 
-- **`status`** is `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally.
+- **`status`** is `designing` → `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally. `designing` sits BEFORE `proposed`: the slice is written down but must not be built yet, because whoever is being shown its looks has not picked one. Only `proposed` is dispatchable, so the two cannot be one status without a slice being built out from under the person still choosing.
+- **`statusAt:` and `attempts:` are bookkeeping, not content — never hand-edit them.** A loop driving this base writes both. `statusAt:` is stamped by whatever moved the status, and is what makes "how long has this been building?" answerable; the file's mtime is not the transition time, because a note is edited after dispatch for all sorts of reasons. `attempts:` is `seat@hash` entries recording which seat has already tried to move this note forward, against the content it was trying to move — it is the loop's only brake, and clearing it by hand hands back a budget that exists to stop a note nothing can satisfy being rewritten forever. Rewriting the note's real content refunds that budget on its own, which is the point: an answer that changes the note is what unsticks it.
 - **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
 - **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
 
@@ -243,6 +244,32 @@ pikku knowledge index --check   # report stale indexes without writing (CI gate)
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
+### What to do next
+
+```bash
+pikku knowledge next            # the one thing to do next, derived from what is on disk
+```
+
+`next` is a pure read: it looks at the notes and answers with exactly one action —
+`repair-note`, `write-plan`, `ask-user`, `dispatch`, `hold`, or `idle`. Nothing has to
+be armed by whoever noticed a transition, so calling it twice is free and a state
+nobody anticipated is a missing answer rather than a run that quietly stops.
+
+Two things about the output matter if you are driving it:
+
+- **`reason` is machine wording.** It names the note, the frontmatter key and what the
+  gate wanted. Never repeat it to a person — they have not seen a note and it will read
+  as gibberish about files.
+- **`ask-user` carries a `question` as well.** That IS the version for a person: a
+  `header`, the question in the language of their app, and `options` when the answer
+  comes from a closed vocabulary (which `status:` it is, which `surface:` it is).
+  `options` is empty when the answer is free text, and an empty list means offer free
+  text — never invent choices to fill it.
+
+`hold` means a profile's own gate is holding the milestone and no seat this loop knows
+about can clear it. It names the hold and the notes it is about; what to do then
+belongs to that profile, not here.
+
 ### The milestone plan
 
 A milestone note says what the app must DO. Its **plan** — JSON beside the note, not prose — says what has to exist for it, and is what a finished build is measured against:

package/skills/pikku-kysely/SKILL.md

@@ -4,12 +4,13 @@ description: >-
   Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
   function body, or when setting up SQL database services with Kysely. Covers the query builder
   API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores,
+  transactions, jsonArrayFrom relation helpers), HOW MANY ROUND TRIPS a function body costs and how to
+  collapse sequential awaits into one statement, AND @pikku/kysely service setup (channel stores,
   workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
   non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
   conditional query), the injected `kysely` service is used in a function body, or code uses
-  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
-  about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
+  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, a function body
+  awaits more than one query, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
   services (use pikku-service-backends).
 installGroups: [core]
 ---
@@ -119,6 +120,109 @@ await kysely.transaction().execute(async (trx) => {
 })
 ```
 
+## One statement, not five
+
+**Count the `await`s in the function body before you finish it.** In a deployed
+stage the database is not in the process — every terminal (`.execute()`,
+`.executeTakeFirst()`) is a network hop, and five in a row is five latencies the
+caller waits through in series. This is the single most common thing wrong with a
+generated function body, and it never shows up locally against a socket on the
+same machine.
+
+**Sequential is only correct when the second query needs the first one's
+VALUES.** Everything else is one of these four:
+
+**1. Independent reads → `Promise.all`.** Nothing about the SQL changes; they
+just stop queuing behind each other.
+
+```typescript
+// Three hops, in series
+const item = await kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst()
+const bins = await kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute()
+const moves = await kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute()
+
+// One hop's worth of latency
+const [item, bins, moves] = await Promise.all([
+  kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst(),
+  kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute(),
+  kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute(),
+])
+```
+
+**2. Parent, then its children → `jsonArrayFrom` / `jsonObjectFrom`.** A loop
+containing an `await` is an N+1: one query per row, so the cost is the size of the
+result set rather than the size of the code. **Never `await` inside a `for`/`map`
+over rows you just fetched.** The relation helpers in the cookbook above collapse
+it into one statement that returns the nested shape your output schema already
+wants.
+
+```typescript
+// N+1 — one extra hop per warehouse
+const warehouses = await kysely.selectFrom('warehouse').selectAll().execute()
+for (const w of warehouses) {
+  w.bins = await kysely.selectFrom('bin').where('warehouseId','=',w.id).selectAll().execute()
+}
+// One hop — see NESTED DATA above
+```
+
+If the shape genuinely cannot be nested, fetch the children in **one** query with
+`where('warehouseId', 'in', warehouses.map((w) => w.id))` and group them in JS.
+Two hops beats N.
+
+**3. Read, decide, write → one write that returns.** A `select` to check
+existence followed by an `insert` is both two hops and a race — another request
+can insert between them. `returning()` and `onConflict` do it in one statement,
+and what comes back tells you which branch happened.
+
+```typescript
+// Two hops and a race
+const existing = await kysely.selectFrom('item').where('sku','=',sku).select('id').executeTakeFirst()
+if (existing) throw new ConflictError()
+await kysely.insertInto('item').values({ sku, name }).execute()
+
+// One hop, and the database arbitrates
+const created = await kysely
+  .insertInto('item')
+  .values({ sku, name })
+  .onConflict((oc) => oc.column('sku').doNothing())
+  .returning(['id', 'sku'])
+  .executeTakeFirst()
+if (!created) throw new ConflictError()
+```
+
+The same applies to fetch-then-update: `updateTable(...).where(...).returning(...)`
+in one call, and `undefined` back means the row was not there — that is your
+`NotFoundError`, not a reason for a preceding `select`. Many single-row inserts
+are one `.values([...])` with an array.
+
+**4. A read that only feeds the next query's `where` → a subquery or a CTE.**
+If the first result never reaches the response and never reaches JS, it should
+never have crossed the wire.
+
+```typescript
+// Two hops — the ids are only ever used as a filter
+const ids = await kysely.selectFrom('bin').where('warehouseId','=',wid).select('id').execute()
+const stock = await kysely.selectFrom('stock').where('binId','in', ids.map((b) => b.id)).selectAll().execute()
+
+// One hop
+const stock = await kysely
+  .selectFrom('stock')
+  .where('binId', 'in', (eb) =>
+    eb.selectFrom('bin').select('bin.id').where('bin.warehouseId', '=', wid)
+  )
+  .selectAll()
+  .execute()
+```
+
+`.with('name', (db) => ...)` builds a CTE when the same intermediate is needed
+twice inside one statement. A total alongside a page is a window function —
+`eb.fn.countAll<number>().over().as('total')` — not a second `count` query.
+
+**A transaction does NOT reduce round trips.** It adds `BEGIN` and `COMMIT` around
+whatever is inside it. Reach for it when several writes must land together or not
+at all; never as a way to make sequential queries cheaper, and never wrapped round
+reads that only needed `Promise.all`.
+
 Pikku provides SQL database services through six packages:
 
 - `@pikku/kysely` — Base service implementations (database-agnostic), the serialize plugins, `createAuditedKysely` and the `pikkuSchemas` helpers