@pikku/kysely 0.13.37 → 0.13.39

package/knowledge/decisions/a-console-role-cannot-take-a-system-roles-name.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: A console role cannot take a system role's name
-description: createRole refuses any name the store holds as a system role, and asks the pikkuRoles table rather than the declared list, so one name never answers to two roles
-tags: [roles, scopes, kysely, system-roles]
----
-
-# A console role cannot take a system role's name
-
-`KyselyScopeService.createRole` in `packages/services/kysely/src/kysely-scope-service.ts`
-throws `SystemRoleShadowedError` when `isSystemRole(role.name)` is true
-(`kysely-scope-service.ts:167-170`). `isSystemRole` reads the `system` flag from the
-`pikkuRoles` table for that name (`kysely-scope-service.ts:221-228`).
-
-The method's doc comment gives the reason for asking the store rather than the generated
-declaration list: the store is where a shadow would collide, and a role whose declaration
-was deleted stays immutable until it is pruned (`kysely-scope-service.ts:214-220`).
-
-The schema comment says the same refusal exists because "two rows answering to one name
-would make 'does Susan hold `buyer`?' depend on which one the store returned"
-(`packages/services/kysely/src/schema/scope.schema.ts:39-43`).
-
-**What this rules out:** a console role sharing a system role's name, and checking the
-name against the code's declaration list instead of the store. `deleteRole` and
-`setRoleScopes` apply the same `isSystemRole` guard (`kysely-scope-service.ts:191-201`).

package/knowledge/decisions/a-credential-with-no-user-is-one-row-per-name.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: A credential with no user is one row per name
-description: The database enforces one app-wide credential per name by indexing COALESCE(user_id, ''), and the service maps a missing user to IS NULL
-tags: [credentials, schema, kysely, uniqueness]
----
-
-# A credential with no user is one row per name
-
-`credentialSchema` in `packages/services/kysely/src/schema/credential.schema.ts` creates
-a unique index `credentials_name_user_id_unique` on `(name, COALESCE(user_id, ''))`
-(`credential.schema.ts:33-36`). Its comment says `user_id` is nullable and that two rows
-with a null user must still collide on name, which is why the rule is an expression
-index (`credential.schema.ts:7-9`).
-
-`KyselyCredentialService.whereUserId` turns a call with no user into `userId IS NULL`
-(`packages/services/kysely/src/kysely-credential-service.ts:118-122`), so `get`, `set`,
-`has` and `delete` without a user all address that single row. `getUsersWithCredential`
-and `getAllUsers` leave the null-user row out (`kysely-credential-service.ts:233-253`).
-
-**What this rules out:** two app-wide rows for the same credential name, and treating a
-null user as a distinct owner from every other null user.

package/knowledge/decisions/a-lease-is-taken-by-one-guarded-update.md

@@ -1,30 +0,0 @@
----
-type: decision
-title: A lease is taken by one guarded UPDATE
-description: Acquire inserts the key's row already lapsed, takes it with a guarded UPDATE, and reads the row back, because that is the one shape that behaves the same on SQLite, Postgres and MySQL
-tags: [leases, kysely, mysql]
----
-
-# A lease is taken by one guarded UPDATE
-
-`acquire` is three statements, in an order that looks roundabout:
-
-1. insert the key's row with `token = 0, expires_at = 0` — already lapsed —
-   ignoring a conflict;
-2. `UPDATE` it to this holder where it is this holder's or has lapsed, raising
-   `token` unless this holder is re-acquiring a live lease;
-3. read the row back and answer whether this holder now has it.
-
-The natural shape, `INSERT … ON CONFLICT DO UPDATE … WHERE`, does not exist on
-MySQL, whose `ON DUPLICATE KEY UPDATE` has no guard. Inserting the row lapsed
-means there is a single path to holding a key — the guarded update — whether the
-key is new or not.
-
-Two MySQL behaviours shape the rest. `SET` is evaluated left to right against
-values already assigned in the same statement, so `token` is assigned before
-`holder`: the re-acquire test has to see the previous holder. And MySQL reports
-rows _changed_, not rows _matched_, so a holder re-acquiring with an unchanged
-row would look like a loss; the row is read back instead of trusting the count.
-
-**What this rules out:** a dialect-specific upsert per database, and deciding
-the outcome from `numUpdatedRows`.

package/knowledge/decisions/a-virtual-users-schedule-starts-disabled.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: A virtual user's schedule starts disabled
-description: A virtual-user schedule is written with enabled off unless the caller says otherwise, and only enabled rows come due, so unattended runs need an explicit enable
-tags: [virtual-users, schedules, kysely, defaults]
----
-
-# A virtual user's schedule starts disabled
-
-The `virtualUserSchedule` table gives `enabled` a default of 0 and marks it not null
-(`packages/services/kysely/src/schema/virtual-user-schedule.schema.ts:24-27`). The
-schema comment says "Off by default, so creating the table spends nothing"
-(`virtual-user-schedule.schema.ts:24-26`).
-
-`KyselyVirtualUserScheduleStore.set` resolves the flag as
-`schedule.enabled ?? existing?.enabled ?? false`
-(`packages/services/kysely/src/kysely-virtual-user-schedule-store.ts:55`). `due()` reads
-only rows with `enabled = 1` (`kysely-virtual-user-schedule-store.ts:131`). The store
-comment says enabling a schedule "is a deliberate act" (`kysely-virtual-user-schedule-store.ts:70-71`).
-
-**What this rules out:** a virtual user that runs on its own from the moment its schedule row
-is created. Who may write the enabled flag is a separate question, recorded in the Kysely
-questions.

package/knowledge/decisions/classification-driven-encryption-happens-in-a-plugin.md

@@ -1,71 +0,0 @@
----
-type: decision
-title: Classification-driven encryption happens in a Kysely plugin
-description: The existing column classification manifest drives a transparent query plugin, rather than encrypting the whole database file or asking call sites to encrypt
-tags: [security, encryption, kysely, classification]
----
-
-# Classification-driven encryption happens in a Kysely plugin
-
-Encrypting a local database at rest has two obvious shapes and both were
-rejected. Encrypting the **whole file** on shutdown and decrypting on startup is
-the simplest to describe and the easiest to lose data with: a crash, a battery
-death, or two processes racing the same file leaves a half-written database with
-no recovery story. Encrypting **every column** keeps the file safe but destroys
-the database — you cannot `WHERE`, `ORDER BY`, or join on ciphertext, so the app
-either reads whole tables into memory or stops using SQL.
-
-The middle answer already exists in the repo. `classification.gen.ts` is a
-per-column manifest of `private` / `secret` / `public` with a `form` of `plain`,
-`hashed`, `wrapped` or `sealed`. Only `wrapped` and `sealed` columns are
-encrypted; everything else stays queryable, which is most of the schema. The
-manifest is generated from the hand-authored `db/annotations.ts` by
-`pikku db migrate`, so the decision about a column is made once, in one place,
-and the query layer follows it.
-
-Enforcement belongs in a **Kysely plugin**, not at call sites. A call site that
-forgets to encrypt writes plaintext into a column the manifest says is secret,
-and nothing catches it — the row looks fine. A plugin sits in the query path
-every write goes through, so "encrypted" becomes a property of the column rather
-than a property of the developer's memory.
-
-Transparency turned out to be **asymmetric**, and the implementation says so.
-Reads are genuinely transparent: `transformResult` is async, so ciphertext is
-decrypted on the way out and application code is unchanged. Writes are not.
-`transformQuery` is synchronous — it returns a `RootOperationNode`, not a
-promise — and WebCrypto is async, so the plugin cannot encrypt on the way in.
-What it does instead is **refuse**: plaintext heading for a `wrapped` or
-`sealed` column throws, and values are produced by
-`ClassificationCrypto.encryptColumn()`. The security property is intact — a
-forgotten call site is a loud error rather than a silent plaintext row — but
-"transparent" describes only half of it.
-
-Two alternatives were rejected to get there. Node's synchronous `crypto` would
-fork crypto away from core and break every non-Node runtime. Proxying the query
-builder is the kind of workaround the repo bans. A **`Driver` wrapper**
-encrypting compiled-query parameters *would* deliver full write transparency and
-reuses the manifest walk and resolver verbatim, so it stays open — but it needs
-a parameter-index-to-column mapping recovered after compilation, and that
-mapping goes fragile exactly where inserts get interesting (multi-row,
-`onConflict().doUpdateSet()`). A mapping that is subtly wrong encrypts the wrong
-column, which is worse than the problem it solves. Not worth it until the write
-path is the thing actually hurting.
-
-That plugin lives here, in `@pikku/kysely`, and not in a SQLite-specific
-package. Nothing about wrapping a column value is dialect-specific, and the same
-plugin is wanted against Postgres — cloud has the same classified columns and
-the same reason to protect them. Putting it beside the dialect would mean
-writing it twice.
-
-The `hashed` form must never be encrypted, and the existing `ColumnForm` JSDoc
-already says why: a token hash *is* the lookup key, so encrypting it makes the
-lookup impossible.
-
-The cost was measured on an M-series Mac rather than estimated: envelope
-encryption runs about **38µs per value** to write and **33µs** to read, which
-over 500 rows batched with `Promise.all` is roughly **9ms**. Key derivation is
-the expensive step at **~48ms**, and it happens once, at unlock.
-
-**What this rules out:** SQLCipher or whole-file encryption, encrypting every
-column, and any design where an application function calls the crypto helpers
-directly.

package/knowledge/decisions/grants-reference-declared-scopes-and-users-by-foreign-key.md

@@ -1,29 +0,0 @@
----
-type: decision
-title: Grants reference declared scopes and users by foreign key
-description: The scope tables tie role and user grants to pikkuScopes and to Better Auth's user table with foreign keys, so the database refuses a grant of an undeclared scope
-tags: [scopes, roles, schema, kysely, foreign-keys]
----
-
-# Grants reference declared scopes and users by foreign key
-
-`scopeSchema` in `packages/services/kysely/src/schema/scope.schema.ts` sets these
-references:
-
-- `pikkuRoleScopes.scope` references `pikkuScopes.name` (`scope.schema.ts:63-72`).
-- `pikkuUserScope.scope` references `pikkuScopes.name` (`scope.schema.ts:101-113`).
-- `pikkuUserRole.role` references `pikkuRoles.name` (`scope.schema.ts:80-82`).
-- `pikkuUserRole.userId` and `pikkuUserScope.userId` reference `user.id`, which Better
-  Auth owns (`scope.schema.ts:77-79`, `scope.schema.ts:98-100`). The schema declares that
-  requirement at `scope.schema.ts:23`.
-
-The file's header comment explains the choice: a grant is made to a user, so the user
-table must exist first (`scope.schema.ts:7-11`). The `KyselyScopeService` class comment
-states that `pikku_role_scopes` FKs into `pikku_scopes`, "so the database itself refuses
-to grant a scope that was never declared" (`packages/services/kysely/src/kysely-scope-service.ts:24-25`).
-
-`syncScopes` marks scopes that are no longer declared rather than deleting them
-(`kysely-scope-service.ts:41-46`), so a foreign key never loses a grant during a deploy.
-
-**What this rules out:** storing a grant for a scope name that was never declared, and
-storing a user grant that has no user row.

package/knowledge/decisions/index.md

@@ -1,21 +0,0 @@
----
-type: overview
-title: Decisions
-description: How encrypted columns are wrapped, and which key wraps them
----
-
-# Decisions
-
-<!-- pikku:knowledge-index -->
-- [A console role cannot take a system role's name](a-console-role-cannot-take-a-system-roles-name.md) — createRole refuses any name the store holds as a system role, and asks the pikkuRoles table rather than the declared list, so one name never answers to two roles
-- [A credential with no user is one row per name](a-credential-with-no-user-is-one-row-per-name.md) — The database enforces one app-wide credential per name by indexing COALESCE(user_id, ''), and the service maps a missing user to IS NULL
-- [A lease is taken by one guarded UPDATE](a-lease-is-taken-by-one-guarded-update.md) — Acquire inserts the key's row already lapsed, takes it with a guarded UPDATE, and reads the row back, because that is the one shape that behaves the same on SQLite, Postgres and MySQL
-- [A virtual user's schedule starts disabled](a-virtual-users-schedule-starts-disabled.md) — A virtual-user schedule is written with enabled off unless the caller says otherwise, and only enabled rows come due, so unattended runs need an explicit enable
-- [Classification-driven encryption happens in a Kysely plugin](classification-driven-encryption-happens-in-a-plugin.md) — The existing column classification manifest drives a transparent query plugin, rather than encrypting the whole database file or asking call sites to encrypt
-- [Grants reference declared scopes and users by foreign key](grants-reference-declared-scopes-and-users-by-foreign-key.md) — The scope tables tie role and user grants to pikkuScopes and to Better Auth's user table with foreign keys, so the database refuses a grant of an undeclared scope
-- [KEKs are scoped by purpose as well as version](keks-are-scoped-by-purpose-as-well-as-version.md) — Rows carry a keyId, and the plugin resolves KEKs through a seam rather than holding one; v1 ships a single key, but scoping never becomes a migration
-- [Leases are judged by the database's clock](leases-are-judged-by-the-database-clock.md) — A lease and a step lease are written and compared in SQL against the server's own clock, stored as epoch milliseconds, so no worker's clock decides who holds anything
-- [The plugin is given a resolver, never a key](the-plugin-is-given-a-resolver-never-a-key.md) — Assembly order for classified columns — a plain Kysely handle, then a plugin that asks a `KEKResolver` per operation rather than being handed a key it holds for the life of the process
-- [The secrets audit table is declared even when auditing is off](the-secrets-audit-table-is-declared-even-when-auditing-is-off.md) — secretsAudit is created by the secret migration unconditionally, because a migration cannot depend on runtime config and an unused table costs nothing
-- [Workflows own the lease table too](workflows-own-the-lease-table-too.md) — `leaseSchema` is owned by `workflowService` as well as `leaseService`, because the engine takes the run lease without any function ever naming leaseService
-<!-- /pikku:knowledge-index -->

package/knowledge/decisions/keks-are-scoped-by-purpose-as-well-as-version.md

@@ -1,45 +0,0 @@
----
-type: decision
-title: KEKs are scoped by purpose as well as version
-description: Rows carry a keyId, and the plugin resolves KEKs through a seam rather than holding one; v1 ships a single key, but scoping never becomes a migration
-tags: [security, encryption, kysely, keys]
----
-
-# KEKs are scoped by purpose as well as version
-
-`KyselySecretService` already versions its key-encrypting key: each row stores a
-`keyVersion` beside its `ciphertext` and `wrappedDek`, per-version salts live in
-their own table, and `rotateKEK` walks rows through `envelopeRewrap`. Version is
-the *when* of a key. It is not the *what* — one KEK per version means every
-encrypted column in the database is protected by the same secret, so unlocking
-anything unlocks everything.
-
-That is acceptable for the first release and wrong as a permanent shape. A
-desktop app has one user and one passphrase; a multi-tenant deployment does not,
-and "the passphrase that opens my notes also opens my credentials" is a
-distinction people expect to be able to draw. So the design keeps scoping
-possible without paying for it now.
-
-Two things carry that. Encrypted rows store a **`keyId`** alongside `keyVersion`,
-so a row records which key protects it rather than inheriting the answer from
-context — retrofitting that column later would mean rewriting every encrypted
-row in every deployment. And the plugin does not hold a KEK; it calls a
-**resolver** that maps a `keyId` to one. In v1 the resolver returns the same key
-for every id. Scoping by tenant, or by purpose, replaces the resolver.
-
-Separate purposes derive from the same key material rather than requiring
-separate passphrases. `expandKeyMaterial(keyMaterial, info, salt)` is the HKDF
-helper already used for `REMOTE_SESSION_INFO`, and a distinct `info` string per
-purpose yields independent keys from one unlock — which is what makes multiple
-KEKs practical for a single-user app at all.
-
-The envelope survives all of this unchanged. Core's decision that
-[secrets use a per-secret DEK wrapped by a KEK](../../../../core/knowledge/decisions/security/core-secrets-use-a-per-secret-dek-wrapped-by-a-kek.md)
-already rules out collapsing it, and scoping is the argument *for* the envelope
-rather than against it: rescoping or rotating a key rewraps DEKs, touching a
-small constant per row, while a design that encrypted values directly under the
-KEK would have to decrypt and re-encrypt every value.
-
-**What this rules out:** a single process-wide KEK with no row-level record of
-which key applies, a separate passphrase per purpose, and deferring the `keyId`
-column to a later migration.

package/knowledge/decisions/leases-are-judged-by-the-database-clock.md

@@ -1,42 +0,0 @@
----
-type: decision
-title: Leases are judged by the database's clock
-description: A lease and a step lease are written and compared in SQL against the server's own clock, stored as epoch milliseconds, so no worker's clock decides who holds anything
-tags: [leases, workflows, kysely, clocks]
----
-
-# Leases are judged by the database's clock
-
-A lease is only as good as the clock that decides it has lapsed. When each
-worker computed `new Date(Date.now() + ttl)` and compared against its own
-`Date.now()`, a worker whose clock ran an hour fast saw every live lease as
-expired and took it — a lease and a step claim both — and wrote leases that
-outlived their ttl by the same hour for everyone else.
-
-So both leases are computed in SQL: `expires_at` is set to _now + ttl_ and
-compared against _now_, where _now_ is the database's —
-`clock_timestamp()` on Postgres, `utc_timestamp(6)` on MySQL. There is one clock,
-and every worker reads it. The columns are `bigint` epoch milliseconds rather
-than `timestamp`, because the arithmetic then means the same thing in every
-dialect and no driver gets to reinterpret a time zone.
-
-On MySQL the epoch is counted from `utc_timestamp`, never
-`unix_timestamp(now())`. `now()` is local to the session's time zone, and when
-that zone falls back an hour, two real instants share one local time: the
-epoch stood still for an hour, then jumped, so a dead holder's lease lived an
-hour longer and every lease written in the repeated hour lapsed at once.
-
-`PgKyselyLeaseService`, `MySQLKyselyLeaseService` and the dialect workflow
-services override `nowMs()`; `KyselyLeaseService` and `KyselyWorkflowService`
-keep the process clock, which is only correct when every process shares a host,
-as they do on SQLite.
-
-**What this rules out:** comparing a lease in JavaScript after reading it — the
-claim used to pre-check `isStepLeaseLive` in the app, and that check is exactly
-where a skewed worker decided wrongly.
-
-**Testing it:** PGlite runs in-process and takes its clock from the JS
-`Date.now`, so skewing `Date.now` skews the database too and a skew test on
-PGlite proves nothing. The skew assertions live in
-`verifiers/workflows/src/tests/lease-db.assert.ts`, against real Postgres and
-MySQL servers.

package/knowledge/decisions/the-plugin-is-given-a-resolver-never-a-key.md

@@ -1,45 +0,0 @@
----
-type: decision
-title: The plugin is given a resolver, never a key
-description: Assembly order for classified columns — a plain Kysely handle, then a plugin that asks a `KEKResolver` per operation rather than being handed a key it holds for the life of the process
-tags: [security, encryption, kysely, classification]
----
-
-# The plugin is given a resolver, never a key
-
-The pieces look circular the first time you assemble them: the plugin needs a
-key, and whatever produces that key may itself need to read from the database.
-It resolves because the plugin is never handed a key at all.
-
-```ts
-const db = new Kysely<DB>({ dialect })
-
-const crypto = new ClassificationCrypto({ resolveKEK })
-const classified = db.withPlugin(
-  createClassificationPlugin({ manifest, crypto })
-)
-```
-
-**The plugin is given a resolver, never a key.** `resolveKEK` is asked _per
-operation_. That is the whole reason a key can arrive after everything around it
-has been constructed — neither the services, the Kysely instance nor the plugin
-are rebuilt when it does — and it is why a key source that later becomes
-unavailable makes the next classified query fail rather than use a stale key.
-
-**A resolver that reads from the database reads through the plain handle**, not
-the classified one, and whatever it reads must not itself be classified. A key
-source that needed its own key to be read could never answer.
-
-**A resolver may derive a KEK any way it likes**, as long as the same `keyId`
-resolves to the same key: from a passphrase, from a KMS, from an environment
-secret. `ClassificationCrypto` only requires the key and the version it should
-stamp into the envelope. Deriving on every call is the mistake to avoid — key
-stretching is the expensive step, so a resolver caches per `keyId`.
-
-**What this rules out:** constructing the Kysely instance with the classification
-plugin already attached before a key source exists, giving a database-backed
-resolver the classified handle, and resolving a key once to cache it inside the
-plugin.
-
-Related: [[classification-driven-encryption-happens-in-a-plugin]],
-[[keks-are-scoped-by-purpose-as-well-as-version]].

package/knowledge/decisions/the-secrets-audit-table-is-declared-even-when-auditing-is-off.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: The secrets audit table is declared even when auditing is off
-description: secretsAudit is created by the secret migration unconditionally, because a migration cannot depend on runtime config and an unused table costs nothing
-tags: [secrets, audit, migrations, kysely]
----
-
-# The secrets audit table is declared even when auditing is off
-
-`secretSchema` in `packages/services/kysely/src/schema/secret.schema.ts` creates the
-`secretsAudit` table as one of its statements (`secret.schema.ts:39-47`), with no
-condition on the audit setting. The comment gives the reason: a migration cannot depend
-on runtime configuration, and an unused table costs nothing, while turning auditing on
-against a database that never got the table fails on the first write
-(`secret.schema.ts:7-11`).
-
-Whether audit rows are written is a separate setting. `KyselySecretService` defaults
-`audit` to false (`packages/services/kysely/src/kysely-secret-service.ts:42`), and its
-`logAudit` returns early when auditing is off (`kysely-secret-service.ts:56`).
-
-**What this rules out:** generating the audit table only when the service is configured
-with auditing on, which would make the schema depend on runtime configuration.

package/knowledge/decisions/workflows-own-the-lease-table-too.md

@@ -1,22 +0,0 @@
----
-type: decision
-title: Workflows own the lease table too
-description: `leaseSchema` is owned by `workflowService` as well as `leaseService`, because the engine takes the run lease without any function ever naming leaseService
-tags: [leases, workflows, schema]
----
-
-# Workflows own the lease table too
-
-`pikku db generate` writes a schema for a project only when a service in
-`ownedBy` is one the inspector found the project's code reaching. The workflow
-engine takes `workflow-run:<id>` from `leaseService` on every orchestration pass,
-but no function destructures `leaseService` to make that happen, so a workflow
-project was never given `pikku_lease` — and registering a lease service then
-failed at boot against a table nothing had migrated.
-
-`leaseSchema` is therefore owned by `workflowService` as well. A workflow project
-gets the table whether or not it registers a lease service yet.
-
-**What this rules out:** making `leaseService` a required service of every
-workflow project. That would force the in-memory and single-process apps, which
-have nothing to serialise, to wire a lease they cannot use.

package/knowledge/index.md

@@ -1,19 +0,0 @@
----
-type: overview
-title: Knowledge
-description: Why encryption in this package is a query-layer concern rather than a call-site one
----
-
-# Knowledge
-
-Encrypting data at rest inside a database that still has to answer SQL queries
-is a set of trade-offs, not a feature toggle. What gets encrypted, who does the
-encrypting, and which key protects which rows are three separate questions, and
-answering them independently is what keeps the result usable.
-
-These notes record how this package answers them.
-
-<!-- pikku:knowledge-index -->
-- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
-- [questions](questions/index.md) — something asked and not yet answered
-<!-- /pikku:knowledge-index -->

package/knowledge/questions/do-the-kysely-stores-check-who-calls-them.md

@@ -1,27 +0,0 @@
----
-type: question
-title: Do the Kysely stores check who calls them?
-description: The virtual-user run, schedule and audit stores take no identity or scope argument, so their authorisation rests on callers, and the run store's comment says reads are scope-gated somewhere else
-tags: [authorization, virtual-users, audit, kysely]
----
-
-# Do the Kysely stores check who calls them?
-
-Three Kysely stores take no identity or scope argument, and the files do not check one.
-
-- **Virtual-user run store.** `get(runId)` and `list({ virtualUserId, limit, offset })` run
-  queries with no caller check (`packages/services/kysely/src/kysely-virtual-user-run-store.ts:125-151`).
-  The class comment says the store is privileged because an adversarial run's findings
-  are "working exploits carrying live ids", and that "the scaffolded reads are
-  scope-gated" (`kysely-virtual-user-run-store.ts:37-39`). The gate is not in this file.
-- **Virtual-user schedule store.** `set(schedule)` takes no identity, and an enabled
-  flag written through it makes a virtual user due (`packages/services/kysely/src/kysely-virtual-user-schedule-store.ts:45-48`,
-  `:55`, `:131`). `remove(virtualUserId)` takes none either (`:161-167`).
-- **Audit service.** `query` applies the `userIds`, `types` and `orgId` filters the
-  caller passes and runs them (`packages/services/kysely/src/kysely-audit-service.ts:161-182`,
-  `:211-236`). Nothing in those lines checks who is asking.
-
-Current behaviour: authorisation for these stores is entirely in the callers.
-
-Open: which layer is meant to check identity and scope for each store, and is the
-run-store scope gate the comment describes implemented anywhere in the repository?

package/knowledge/questions/does-a-trigger-source-row-hold-only-provider-identifiers.md

@@ -1,26 +0,0 @@
----
-type: question
-title: Does a trigger-source row hold only provider identifiers?
-description: The trigger-source schema says state holds provider identifiers and that signing secrets go to the credential service, but the store writes whatever state the caller passes as JSON
-tags: [kysely, trigger-source, secrets]
----
-
-# Does a trigger-source row hold only provider identifiers?
-
-The doc comment on the table says "`state` holds provider identifiers only: a signing
-secret a provider issues goes to the credential service"
-(`packages/services/kysely/src/schema/trigger-source.schema.ts:4-7`).
-
-The table has a `state` text column and a `detail` text column
-(`trigger-source.schema.ts:26-27`). Nothing in the schema restricts what is written to
-them.
-
-The store writes the value it is given. `recordTriggerSource` sets
-`state` to `JSON.stringify(result.state)` whenever `result.state` is set
-(`packages/services/kysely/src/kysely-trigger-source-store.ts:102-107`). Its test
-writes `{ id: 'we_1' }` (`kysely-trigger-source-store.test.ts:41`), which is an
-identifier. The test does not check that a secret is refused.
-
-This note did not read the code that builds `result.state`, so it cannot say whether
-any caller puts a secret there. The question is whether the comment describes a rule
-the code enforces, or only the convention the callers are expected to follow.

package/knowledge/questions/index.md

@@ -1,17 +0,0 @@
----
-type: overview
-title: Questions
-description: Things asked of the Kysely stores and not yet answered
----
-
-# Questions
-
-Something asked and not yet answered. The code makes a choice nobody has stated, so the
-doubt is recorded with the current behaviour, not a guessed rationale.
-
-<!-- pikku:knowledge-index -->
-- [Do the Kysely stores check who calls them?](do-the-kysely-stores-check-who-calls-them.md) — The virtual-user run, schedule and audit stores take no identity or scope argument, so their authorisation rests on callers, and the run store's comment says reads are scope-gated somewhere else
-- [Does a trigger-source row hold only provider identifiers?](does-a-trigger-source-row-hold-only-provider-identifiers.md) — The trigger-source schema says state holds provider identifiers and that signing secrets go to the credential service, but the store writes whatever state the caller passes as JSON
-- [Should pikku user sessions expire on their own?](should-pikku-user-sessions-expire-on-their-own.md) — The Kysely session store writes a session with no expiry, reads it back at any age, and its table has no expiry column
-- [Should secret and credential reads be audited by default?](should-secret-and-credential-reads-be-audited-by-default.md) — The Kysely secret and credential stores leave auditing off, leave reads unaudited unless asked, and the secret store never records bulk reads; the generic query audit goes the other way
-<!-- /pikku:knowledge-index -->

package/knowledge/questions/should-pikku-user-sessions-expire-on-their-own.md

@@ -1,21 +0,0 @@
----
-type: question
-title: Should pikku user sessions expire on their own?
-description: The Kysely session store writes a session with no expiry, reads it back at any age, and its table has no expiry column
-tags: [sessions, expiry, kysely]
----
-
-# Should pikku user sessions expire on their own?
-
-`KyselySessionStore` (`packages/services/kysely/src/kysely-session-store.ts`) writes a
-session as JSON with an `updatedAt` stamp and nothing else (`kysely-session-store.ts:35-46`).
-`get` returns the stored session whatever its age, and has no expiry check
-(`kysely-session-store.ts:21-33`). `clear` deletes a user's row (`kysely-session-store.ts:48-53`).
-
-The table has `pikkuUserId`, `session`, `createdAt` and `updatedAt`, and no expiry column
-(`packages/services/kysely/src/schema/session.schema.ts:8-18`).
-
-Current behaviour: a stored session stays readable until something calls `clear`.
-
-Open: should a session expire in this store, or is its lifetime bounded somewhere else? The
-files do not say.

package/knowledge/questions/should-secret-and-credential-reads-be-audited-by-default.md

@@ -1,32 +0,0 @@
----
-type: question
-title: Should secret and credential reads be audited by default?
-description: The Kysely secret and credential stores leave auditing off, leave reads unaudited unless asked, and the secret store never records bulk reads; the generic query audit goes the other way
-tags: [audit, secrets, credentials, kysely]
----
-
-# Should secret and credential reads be audited by default?
-
-`KyselySecretService` (`packages/services/kysely/src/kysely-secret-service.ts`) defaults
-`audit` and `auditReads` to false (`kysely-secret-service.ts:42-43`). `logAudit` returns
-early when auditing is off, and for reads when `auditReads` is off
-(`kysely-secret-service.ts:56-57`). A single `getSecret` records a read
-(`kysely-secret-service.ts:129`). `getSecrets` records nothing, even with auditing on
-(`kysely-secret-service.ts:178-209`). Writes, deletes and rotations are recorded when
-auditing is on (`kysely-secret-service.ts:170`, `:175`, `:237`).
-
-`KyselyCredentialService` (`packages/services/kysely/src/kysely-credential-service.ts`)
-has the same defaults (`kysely-credential-service.ts:40-41`) and the same gate
-(`kysely-credential-service.ts:50-56`). `get` records a read (`:140`), and `getAll`
-records one row per credential, still under the same flag (`:207-230`, `:227`).
-
-`createAuditedKysely` goes the other way. It skips selects only when `auditReads` is
-explicitly `false` (`packages/services/kysely/src/create-audited-kysely.ts:196-198`), so
-database selects are audited by default.
-
-Current behaviour: secret and credential reads leave no record until the app turns
-auditing on, and bulk secret reads never leave one. The code does not say whether that is
-meant.
-
-Open: should secret and credential reads be audited by default, and should `getSecrets`
-record a row per key? The files do not say.

package/run-tests.sh

@@ -1,61 +0,0 @@
-#!/bin/bash
-
-# Enable nullglob to handle cases where no files match the pattern
-shopt -s nullglob
-
-# Initialize variables for options
-watch_mode=false
-coverage_mode=false
-
-# Parse command-line options
-while [[ $# -gt 0 ]]; do
-  case $1 in
-    --watch)
-      watch_mode=true
-      shift
-      ;;
-    --coverage)
-      coverage_mode=true
-      shift
-      ;;
-    *)
-      echo "Unknown option: $1"
-      exit 1
-      ;;
-  esac
-done
-
-# Define the pattern to match your test files
-pattern="src/*.test.ts"
-
-# Expand the pattern into an array of files
-files=($(find src -type f -name "*.test.ts"))
-
-# Check if any files matched the pattern
-if [ ${#files[@]} -eq 0 ]; then
-  echo "No test files found matching pattern: $pattern"
-  if [ "${STRICT_TEST_DISCOVERY}" = "1" ]; then
-    exit 1
-  fi
-  exit 0
-fi
-
-# Construct the node command
-#
-# Every other package runs its tests on bun. This one stays on node because
-# better-sqlite3, which every one of these suites opens its fixture database
-# with, aborts the bun process on load.
-node_cmd=(node --import tsx --test)
-
-# Append options based on flags
-if [ "$watch_mode" = true ]; then
-  node_cmd+=(--watch)
-fi
-
-if [ "$coverage_mode" = true ]; then
-  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
-  export PIKKU_TEST_COVERAGE=1
-fi
-
-# Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"