@pikku/kysely 0.13.34 → 0.13.37

package/dist/src/schema/index.d.ts

@@ -2,6 +2,17 @@ import { type Kysely } from 'kysely';
 import { type PikkuSchema, type RequiredTypes, type SchemaRequirement } from './pikku-schema.types.js';
 export type { PikkuSchema, RequiredTypes, SchemaContext, SchemaRequirement, SchemaStatement, SchemaStatementFactory, } from './pikku-schema.types.js';
 export { rawStatement, requiredType, schemaContext, unqualifiedContext, } from './pikku-schema.types.js';
+/**
+ * Re-point the schemas that reference Better Auth's `user` table at the table
+ * the project actually maps that model to.
+ *
+ * Better Auth's `user.modelName` decides the physical name: an app on a legacy
+ * `users` table has no `user` for the declaration to point at, so the scope
+ * schema read as unmet and was silently left out. The requirement, the column
+ * type lookup and every foreign key target are rewritten together, because they
+ * name the table three different ways.
+ */
+export declare const withUserTable: (schemas: PikkuSchema[], userTable: string) => PikkuSchema[];
 /**
  * Every table any part of the pikku runtime can need, in dependency order.
  *

package/dist/src/schema/index.js

@@ -18,6 +18,35 @@ import { workflowSchema } from './workflow.schema.js';
 import { virtualUserSchema } from './virtual-user.schema.js';
 import { virtualUserScheduleSchema } from './virtual-user-schedule.schema.js';
 export { rawStatement, requiredType, schemaContext, unqualifiedContext, } from './pikku-schema.types.js';
+/**
+ * Re-point the schemas that reference Better Auth's `user` table at the table
+ * the project actually maps that model to.
+ *
+ * Better Auth's `user.modelName` decides the physical name: an app on a legacy
+ * `users` table has no `user` for the declaration to point at, so the scope
+ * schema read as unmet and was silently left out. The requirement, the column
+ * type lookup and every foreign key target are rewritten together, because they
+ * name the table three different ways.
+ */
+export const withUserTable = (schemas, userTable) => {
+    if (userTable === 'user')
+        return schemas;
+    const retarget = (target) => target.startsWith('user.') ? `${userTable}.${target.slice(5)}` : target;
+    return schemas.map((schema) => ({
+        ...schema,
+        requires: schema.requires?.map((r) => r.table === 'user' ? { ...r, table: userTable } : r),
+        statements: schema.statements.map((statement) => (db, types, ctx) => statement(db, Object.fromEntries(Object.entries(types).flatMap(([key, value]) => key.startsWith(`${userTable}.`)
+            ? [
+                [key, value],
+                [`user.${key.slice(userTable.length + 1)}`, value],
+            ]
+            : [[key, value]])), {
+            ...ctx,
+            references: (column, target) => ctx.references(column, retarget(target)),
+            foreignKeys: (table, keys) => ctx.foreignKeys(table, Object.fromEntries(Object.entries(keys).map(([k, v]) => [k, retarget(v)]))),
+        })),
+    }));
+};
 /**
  * Every table any part of the pikku runtime can need, in dependency order.
  *

package/dist/src/schema/virtual-user-schedule.schema.d.ts

@@ -1,14 +1,14 @@
 import type { PikkuSchema } from './pikku-schema.types.js';
 /**
  * The `virtualUserSchedule` table {@link KyselyVirtualUserScheduleStore} writes
- * to: one row per persona that keeps using the app on its own.
+ * to: one row per virtual user that keeps using the app on its own.
  *
  * Its own schema rather than a third table in {@link virtualUserSchema}, and
- * owned by its own store: recording what a persona did and deciding that it
+ * owned by its own store: recording what a virtual user did and deciding that it
  * keeps going on its own are separate opt-ins, and a project that only wants
  * the first should not be handed a cadence table it never writes to.
  *
- * `persona` is the primary key: a persona has one cadence, and a second row for
+ * `virtualUserId` is the primary key: a virtual user has one cadence, and a second row for
  * the same one would mean two copies of the same user acting at once — not a
  * heavier test, a different and unreproducible one.
  */

package/dist/src/schema/virtual-user-schedule.schema.js

@@ -1,13 +1,13 @@
 /**
  * The `virtualUserSchedule` table {@link KyselyVirtualUserScheduleStore} writes
- * to: one row per persona that keeps using the app on its own.
+ * to: one row per virtual user that keeps using the app on its own.
  *
  * Its own schema rather than a third table in {@link virtualUserSchema}, and
- * owned by its own store: recording what a persona did and deciding that it
+ * owned by its own store: recording what a virtual user did and deciding that it
  * keeps going on its own are separate opt-ins, and a project that only wants
  * the first should not be handed a cadence table it never writes to.
  *
- * `persona` is the primary key: a persona has one cadence, and a second row for
+ * `virtualUserId` is the primary key: a virtual user has one cadence, and a second row for
  * the same one would mean two copies of the same user acting at once — not a
  * heavier test, a different and unreproducible one.
  */
@@ -17,7 +17,7 @@ export const virtualUserScheduleSchema = {
     statements: [
         (db, _types, ctx) => db.schema
             .createTable('virtualUserSchedule')
-            .addColumn('persona', 'varchar(255)', (col) => col.primaryKey())
+            .addColumn('virtualUserId', 'varchar(255)', (col) => col.primaryKey())
             // 0 or 1 rather than a boolean, matching the run tables: a bare sqlite
             // driver cannot bind one, and `SerializePlugin` is not installed
             // everywhere. Off by default, so creating the table spends nothing.
@@ -26,7 +26,7 @@ export const virtualUserScheduleSchema = {
             .addColumn('goals', ctx.text, (col) => col.defaultTo(ctx.defaultText('[]')).notNull())
             .addColumn('budget', ctx.text)
             // The gap to the next run is drawn between these rather than fixed, so
-            // the persona does not keep an appointment.
+            // the virtual user does not keep an appointment.
             .addColumn('minIntervalMs', 'bigint', (col) => col.notNull())
             .addColumn('maxIntervalMs', 'bigint', (col) => col.notNull())
             // The entire schedule. Written before a run is dispatched, so a tick

package/dist/src/schema/virtual-user.schema.d.ts

@@ -8,9 +8,9 @@ import type { PikkuSchema } from './pikku-schema.types.js';
  * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
  * applies it, so it arrives exactly when the thing that fills it does.
  *
- * `persona` is text rather than a foreign key: personas are declared in code
- * with `definePersonas()`, not rows, and a run has to outlive the deletion of
- * the persona it ran as.
+ * `virtualUserId` is text rather than a foreign key: virtual users are declared in code
+ * with `defineVirtualUsers()`, not rows, and a run has to outlive the deletion of
+ * the virtual user it ran as.
  *
  * The JSON columns are text on every engine, like the audit table's, because
  * the store serialises them itself — a project on SQLite and one on Postgres

package/dist/src/schema/virtual-user.schema.js

@@ -8,9 +8,9 @@ import { sql } from 'kysely';
  * put an empty table in every database. `KyselyVirtualUserRunStore.init()`
  * applies it, so it arrives exactly when the thing that fills it does.
  *
- * `persona` is text rather than a foreign key: personas are declared in code
- * with `definePersonas()`, not rows, and a run has to outlive the deletion of
- * the persona it ran as.
+ * `virtualUserId` is text rather than a foreign key: virtual users are declared in code
+ * with `defineVirtualUsers()`, not rows, and a run has to outlive the deletion of
+ * the virtual user it ran as.
  *
  * The JSON columns are text on every engine, like the audit table's, because
  * the store serialises them itself — a project on SQLite and one on Postgres
@@ -24,7 +24,7 @@ export const virtualUserSchema = {
         (db, _types, ctx) => db.schema
             .createTable('virtualUserRun')
             .addColumn('runId', 'varchar(36)', (col) => col.primaryKey())
-            .addColumn('persona', 'varchar(255)', (col) => col.notNull())
+            .addColumn('virtualUserId', 'varchar(255)', (col) => col.notNull())
             .addColumn('disposition', 'varchar(50)', (col) => col.notNull())
             .addColumn('seed', 'bigint', (col) => col.notNull())
             // running | completed | failed. Not derived from `finishedAt` being
@@ -46,19 +46,19 @@ export const virtualUserSchema = {
             .addColumn('startedBy', 'varchar(255)')
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addColumn('finishedAt', 'timestamp'),
-        // The two reads: the run list newest-first, and one persona's history when
-        // a finding needs comparing against what that persona found before.
+        // The two reads: the run list newest-first, and one virtual user's history when
+        // a finding needs comparing against what that virtual user found before.
         (db, _types, ctx) => db.schema
             .createIndex('idx_virtual_user_run_created')
             .on('virtualUserRun')
             .column('createdAt'),
         (db, _types, ctx) => db.schema
-            .createIndex('idx_virtual_user_run_persona')
+            .createIndex('idx_virtual_user_run_virtual_user_id')
             .on('virtualUserRun')
-            .columns(['persona', 'createdAt']),
+            .columns(['virtualUserId', 'createdAt']),
         // One row per turn, kept out of `virtualUserRun` so that listing runs does
         // not drag a budget's worth of transcript along with it. No foreign key
-        // onto the run for the same reason `persona` is not one: this table is
+        // onto the run for the same reason `virtualUserId` is not one: this table is
         // created by the store at boot on whatever engine the project uses, and a
         // cascade that half the engines enforce differently is worse than the read
         // rule that a step with no run is orphaned.

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

@@ -0,0 +1,25 @@
+---
+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

@@ -0,0 +1,22 @@
+---
+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-virtual-users-schedule-starts-disabled.md

@@ -0,0 +1,23 @@
+---
+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

@@ -53,7 +53,7 @@ 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 — fabric has the same classified columns and
+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.
 

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

@@ -0,0 +1,29 @@
+---
+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

@@ -7,12 +7,15 @@ 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/the-secrets-audit-table-is-declared-even-when-auditing-is-off.md

@@ -0,0 +1,22 @@
+---
+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/index.md

@@ -15,4 +15,5 @@ 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

@@ -0,0 +1,27 @@
+---
+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

@@ -0,0 +1,26 @@
+---
+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

@@ -0,0 +1,17 @@
+---
+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

@@ -0,0 +1,21 @@
+---
+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

@@ -0,0 +1,32 @@
+---
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.34",
+  "version": "0.13.37",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -15,6 +15,7 @@
     "pikku-kysely-pure": "dist/bin/pikku-kysely-pure.js"
   },
   "type": "module",
+  "sideEffects": false,
   "scripts": {
     "tsc": "tsc",
     "ncu": "npx npm-check-updates",
@@ -26,7 +27,7 @@
     "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.136"
+    "@pikku/core": "^0.12.142"
   },
   "dependencies": {
     "kysely": "^0.29.5"