@pikku/core 0.12.72 → 0.12.77

package/dist/services/queue-webhook-service.js

@@ -2,23 +2,11 @@ import { getSingletonServices } from '../pikku-state.js';
 import { getDurationInMilliseconds } from '../time-utils.js';
 import { safeFetch } from '../utils/safe-fetch.js';
 import { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
-/** Cap on the response body captured on a failed attempt. */
 const MAX_CAPTURED_RESPONSE_BODY = 2_000;
-/**
- * Default {@link WebhookService} implementation: serializes and signs the
- * payload, then enqueues a delivery job onto the `pikku-outgoing-webhooks`
- * queue. The signature is computed at enqueue time so the signing key never
- * enters the queue payload; the actual HTTP POST happens in
- * {@link pikkuWebhookWorkerFunc}, and the queue's `attempts`/`backoff`
- * options drive retries.
- */
+// knowledge: decisions/security/webhook-bodies-are-signed-before-they-are-enqueued.md
 export class QueueWebhookService extends WebhookService {
     queueService;
-    /**
-     * The queue is a constructor dependency rather than a `getSingletonServices()`
-     * lookup so that a project wiring up outgoing webhooks without a queue fails
-     * to compile, instead of throwing on the first `send()`.
-     */
+    // knowledge: decisions/internals/webhook-service-collaborators-are-constructor-args-not-locator-lookups.md
     constructor(queueService) {
         super();
         this.queueService = queueService;
@@ -29,10 +17,8 @@ export class QueueWebhookService extends WebhookService {
         return { jobId };
     }
     /**
-     * Build the signed job payload and its retry options — the shared work a
-     * `send()` does before enqueueing. Factored out (and `protected`) so a
-     * store-backed subclass can persist a delivery row and attach its
-     * `deliveryId` without re-implementing signing or the retry policy.
+     * `protected` so a store-backed subclass can persist a delivery row and attach
+     * its `deliveryId` without re-implementing signing or the retry policy.
      */
     async prepareDelivery(input) {
         const services = getSingletonServices();
@@ -45,8 +31,8 @@ export class QueueWebhookService extends WebhookService {
         };
         let secret = input.secret;
         if (secret === undefined && webhookConfig?.secret) {
-            // Naive read — any caching is the secret service's concern, not ours.
-            secret = await services.secrets.getSecret(webhookConfig.secret);
+            // Naive read: caching is the secret service's concern, not ours.
+            secret = (await services.secrets.getSecret(webhookConfig.secret)).reveal();
             if (!secret) {
                 services.logger.error(`Webhook signing secret '${webhookConfig.secret}' (config.webhook.secret) resolved to nothing — outgoing webhooks will be sent UNSIGNED.`);
             }
@@ -63,13 +49,7 @@ export class QueueWebhookService extends WebhookService {
         };
         return { jobData, options: this.resolveJobOptions(input) };
     }
-    /**
-     * Resolve a delivery's retry policy into queue job options, mirroring the
-     * workflow service: per-call values win over `config.webhook` defaults, an
-     * explicitly-set `retries` (including 0) is always honored, and `attempts`
-     * is ALWAYS passed so the queue can never fall back to its own default.
-     * Backoff is exponential unless a concrete `retryDelay` selects a fixed one.
-     */
+    // knowledge: decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md
     resolveJobOptions(input) {
         const webhookConfig = getSingletonServices().config?.webhook;
         const retries = input.retries ?? webhookConfig?.retries ?? DEFAULT_WEBHOOK_RETRIES;
@@ -82,18 +62,7 @@ export class QueueWebhookService extends WebhookService {
         return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
     }
 }
-/**
- * Queue worker for the `pikku-outgoing-webhooks` queue: POSTs the delivery to its
- * target URL. Any non-2xx response (or network error) throws so the queue
- * retries the job according to the `attempts`/`backoff` set at enqueue time;
- * the queue runner logs each failed attempt.
- *
- * A `deliveryId` is only present when a store-backed `webhookService` (e.g.
- * `KyselyWebhookService`) enqueued the job, so each attempt (success or failure)
- * is persisted via `webhookService.recordAttempt` before the throw — the console
- * delivery history reflects every try, not just the outcome. The queue-only
- * default never sets a `deliveryId`, so its base `recordAttempt` is never hit.
- */
+// knowledge: decisions/internals/webhook-delivery-history-records-every-attempt-best-effort.md
 export async function pikkuWebhookWorkerFunc(services, { url, body, headers, deliveryId }) {
     let statusCode;
     let responseBody;
@@ -104,8 +73,8 @@ export async function pikkuWebhookWorkerFunc(services, { url, body, headers, del
         allowedHosts = getSingletonServices().config?.webhook?.allowedHosts;
     }
     catch {
-        // Singleton services not initialised (e.g. a bare worker invocation) — fall
-        // back to the default private-host block with no allowlist.
+        // Uninitialised singletons (a bare worker invocation): fall back to the
+        // default private-host block rather than failing the delivery.
     }
     try {
         const response = await safeFetch(url, {
@@ -125,7 +94,6 @@ export async function pikkuWebhookWorkerFunc(services, { url, body, headers, del
         error = e instanceof Error ? e.message : String(e);
     }
     if (deliveryId && services.webhookService) {
-        // Best-effort history: a store failure must not mask the delivery result.
         await services.webhookService
             .recordAttempt(deliveryId, { statusCode, responseBody, error, delivered })
             .catch((storeError) => services.logger.error(`Failed to record webhook delivery attempt for ${deliveryId}`, storeError));

package/dist/services/scheduler-service.d.ts

@@ -1,71 +1,22 @@
 import type { CoreUserSession } from '../types/core.types.js';
-/**
- * Minimal metadata for listing scheduled tasks
- */
 export interface ScheduledTaskSummary {
-    /** Unique task ID */
     taskId: string;
-    /** RPC function name to invoke */
     rpcName: string;
-    /** Scheduled execution time */
     scheduledFor: Date;
 }
-/**
- * Full metadata for a scheduled task retrieved from the queue
- */
 export interface ScheduledTaskInfo extends ScheduledTaskSummary {
-    /** Data to pass to the RPC function */
     data?: any;
-    /** User session */
     session?: CoreUserSession;
-    /** Task status */
     status?: 'scheduled' | 'active' | 'completed' | 'failed';
 }
-/**
- * Abstract scheduler service for persistent scheduled task management
- * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
- */
 export declare abstract class SchedulerService {
-    /**
-     * Initialize the scheduler service
-     */
     abstract init(): Promise<void>;
-    /**
-     * Schedule a one-off delayed RPC call
-     * @param delay - Delay before execution (number in milliseconds or duration string like "5h", "30m")
-     * @param rpcName - RPC function name to invoke
-     * @param data - Data to pass to the RPC function
-     * @param session - Optional user session
-     * @returns Task ID
-     */
+    /** `delay` is milliseconds as a number, or a duration string such as `"5h"` / `"30m"`. */
     abstract scheduleRPC(delay: number | string, rpcName: string, data?: any, session?: CoreUserSession): Promise<string>;
-    /**
-     * Unschedule a task by ID
-     * @param taskId - Task ID
-     * @returns Success status
-     */
     abstract unschedule(taskId: string): Promise<boolean>;
-    /**
-     * Get a scheduled task by ID with full details
-     * @param taskId - Task ID
-     * @returns Task info or null if not found
-     */
     abstract getTask(taskId: string): Promise<ScheduledTaskInfo | null>;
-    /**
-     * Get all scheduled tasks with minimal info
-     * @returns Array of task summaries with taskId, rpcName, and schedule
-     */
     abstract getAllTasks(): Promise<ScheduledTaskSummary[]>;
-    /**
-     * Close any open connections
-     */
     abstract close(): Promise<void>;
-    /**
-     * Start recurring scheduled tasks
-     */
     start(): Promise<void>;
-    /**
-     * Stop recurring scheduled tasks
-     */
     stop(): Promise<void>;
 }

package/dist/services/scheduler-service.js

@@ -1,14 +1,4 @@
-/**
- * Abstract scheduler service for persistent scheduled task management
- * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
- */
 export class SchedulerService {
-    /**
-     * Start recurring scheduled tasks
-     */
     async start() { }
-    /**
-     * Stop recurring scheduled tasks
-     */
     async stop() { }
 }

package/dist/services/schema-service.d.ts

@@ -1,30 +1,7 @@
-/**
- * Interface for a schema service that handles schema compilation, validation, and management.
- */
 export interface SchemaService {
-    /**
-     * Compiles a schema with the provided name and value, making it available for use.
-     * @param {string} name - The unique name for the schema.
-     * @param {any} value - The schema definition or configuration to be compiled.
-     * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
-     */
     compileSchema: (name: string, value: any) => Promise<void> | void;
-    /**
-     * Validates data against a specified schema.
-     * @param {string} schema - The name of the schema to validate against.
-     * @param {any} data - The data to validate against the schema.
-     * @returns {Promise<void> | void} A promise if asynchronous, or void if synchronous.
-     */
     validateSchema: (schema: string, data: any) => Promise<void> | void;
-    /**
-     * Retrieves a set of all registered schema names.
-     * @returns {Set<string>} A set containing the names of all available schemas.
-     */
     getSchemaNames: () => Set<string>;
-    /**
-     * Retrieves the property keys from a compiled JSON schema.
-     * @param {string} schemaName - The name of the schema.
-     * @returns {string[]} An array of property keys, or empty array if schema not found.
-     */
+    /** Empty when the schema is not registered. */
     getSchemaKeys: (schemaName: string) => string[];
 }

package/dist/services/scope-service.d.ts

@@ -1,67 +1,82 @@
 import type { FlatScope } from '../wirings/scope/scope.types.js';
-/** A role: a named, admin-composed bag of scopes. */
+import type { SystemRole } from '../wirings/role/role.types.js';
 export interface Role {
     name: string;
     description?: string;
     scopes: string[];
-}
-/**
- * Resolves and administers the scopes granted to a user.
- *
- * Implementations are called at the **session boundary** — e.g. better-auth's
- * `mapSession` — never by the function runner. The runner reads
- * `session.scopes` and never performs I/O, which keeps it viable on Workers
- * and Lambda. Because the session is rebuilt per request, a scope change takes
- * effect on the next call with nothing cached and nothing to invalidate.
- *
- * `syncScopes` is deliberately additive: scopes are declared in code, so a
- * removed declaration leaves an inert row rather than silently revoking a
- * grant mid-deploy. Removal is an explicit operation (`pikku scopes prune`).
- */
-export interface ScopeService {
     /**
-     * Registers the declared scope set. Additive — never deletes.
-     * Called once during startup with the generated scope list.
+     * True when the role was declared in code with `defineSystemRole` rather
+     * than composed by an admin. System roles may be granted, but not renamed,
+     * re-scoped or deleted — see {@link ScopeService.syncSystemRoles}.
      */
-    syncScopes(scopes: FlatScope[]): Promise<void>;
+    system?: boolean;
     /**
-     * Every scope a user holds: the union of their role-derived scopes and any
-     * scopes granted to them directly.
+     * False when a system role's declaration has been removed from code but its
+     * row survives: still held by whoever holds it, no longer offered for new
+     * grants, awaiting `pikku roles prune`.
      */
+    declared?: boolean;
+}
+export interface ScopeService {
+    syncScopes(scopes: FlatScope[]): Promise<void>;
+    /** The union of role-derived scopes and scopes granted directly. */
     resolveScopes(userId: string): Promise<string[]>;
     /**
-     * The scope vocabulary in the store: everything a role can be composed from.
-     *
-     * `declared: false` marks a scope that is still present but no longer
-     * declared in code — inert (no function can require it) and awaiting
-     * `pikku scopes prune`.
+     * The whole vocabulary a role can be composed from. `declared: false` marks a
+     * scope still in the store but no longer declared in code: inert, since no
+     * function can require it, and awaiting `pikku scopes prune`.
      */
     listScopes(): Promise<Array<FlatScope & {
         declared: boolean;
     }>>;
+    /**
+     * Registers the roles declared with `defineSystemRole`. Additive on the same
+     * terms as {@link syncScopes}: a removed declaration leaves the row in place,
+     * marked `declared: false`, rather than revoking everyone's grant on deploy.
+     *
+     * A role's scope set *is* re-synced, because that is the declaration's whole
+     * content — editing `defineSystemRole` is how you change what a system role
+     * means, and the deploy is when it takes effect.
+     *
+     * Called once during startup with the generated role list.
+     */
+    syncSystemRoles(roles: SystemRole[]): Promise<void>;
+    /**
+     * Creates an admin-composed role.
+     *
+     * Must throw {@link SystemRoleShadowedError} when `role.name` matches a
+     * declared system role. Two rows answering to one name make "does this user
+     * hold `buyer`?" depend on which the store returns first.
+     */
     createRole(role: Role): Promise<void>;
+    /** Must throw {@link SystemRoleImmutableError} for a system role. */
     deleteRole(name: string): Promise<void>;
+    /** Must throw {@link SystemRoleImmutableError} for a system role. */
     setRoleScopes(name: string, scopes: string[]): Promise<void>;
     listRoles(): Promise<Role[]>;
     addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
     removeUserFromRole(userId: string, role: string): Promise<void>;
     listUserRoles(userId: string): Promise<string[]>;
-    /**
-     * Grants a scope directly to a user, outside of any role. Additive: the
-     * resolved set is the union of role-derived and directly-granted scopes.
-     */
+    /** Grants outside of any role; additive with the user's role-derived scopes. */
     addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
     removeScopeFromUser(userId: string, scope: string): Promise<void>;
     /** Only the scopes granted directly, not those inherited from roles. */
     listUserScopes(userId: string): Promise<string[]>;
-    /**
-     * Scopes present in the store that are no longer declared in code, with the
-     * roles that would lose them. Powers `pikku scopes audit`.
-     */
+    /** Undeclared scopes with the roles that would lose them; powers `pikku scopes audit`. */
     findStaleScopes(): Promise<Array<{
         scope: string;
         roles: string[];
     }>>;
     /** Removes undeclared scopes, cascading them out of roles. */
     pruneScopes(): Promise<string[]>;
+    /**
+     * System roles in the store whose declaration has gone, with the number of
+     * users still holding each. Powers `pikku roles audit`.
+     */
+    findStaleSystemRoles(): Promise<Array<{
+        role: string;
+        users: number;
+    }>>;
+    /** Removes undeclared system roles, cascading them out of user grants. */
+    pruneSystemRoles(): Promise<string[]>;
 }

package/dist/services/scoped-secret-service.d.ts

@@ -1,16 +1,13 @@
-import type { SecretService } from './secret-service.js';
-/**
- * A read-only wrapper around SecretService that restricts access
- * to only a defined set of allowed secret keys.
- */
+import type { SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 export declare class ScopedSecretService implements SecretService {
     private secrets;
     private allowedKeys;
     constructor(secrets: SecretService, allowedKeys: Set<string>);
     private assertAllowed;
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret(_key: string, _value: unknown): Promise<void>;
     deleteSecret(_key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }

package/dist/services/scoped-secret-service.js

@@ -1,7 +1,3 @@
-/**
- * A read-only wrapper around SecretService that restricts access
- * to only a defined set of allowed secret keys.
- */
 export class ScopedSecretService {
     secrets;
     allowedKeys;

package/dist/services/secret-host-binding.d.ts

@@ -0,0 +1,8 @@
+import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
+export declare class SecretHostNotAllowedError extends Error {
+    readonly secretId: string;
+    readonly host: string;
+    constructor(secretId: string, host: string, allowedHosts: string[] | undefined);
+}
+/** Refuses a secret/host pairing the declarations do not permit. */
+export declare const assertSecretAllowedForHost: (secretId: string, url: string | URL, secretDefinitions: SecretDefinitionsMeta | undefined, requireAllowedHosts?: boolean) => void;

package/dist/services/secret-host-binding.js

@@ -0,0 +1,36 @@
+export class SecretHostNotAllowedError extends Error {
+    secretId;
+    host;
+    constructor(secretId, host, allowedHosts) {
+        super(allowedHosts?.length
+            ? `Secret '${secretId}' may not be sent to '${host}' — it is declared for ${allowedHosts.map((h) => `'${h}'`).join(', ')}. Add the host to allowedHosts on its defineSecret if this is intended.`
+            : `Secret '${secretId}' has no allowedHosts and this project requires one. Declare the hosts it may be sent to on its defineSecret.`);
+        this.secretId = secretId;
+        this.host = host;
+        this.name = 'SecretHostNotAllowedError';
+    }
+}
+/** Exact match, or a single leading `*.` wildcard anchored on a dot. */
+const hostMatches = (host, pattern) => {
+    const h = host.toLowerCase();
+    const p = pattern.toLowerCase();
+    if (p.startsWith('*.')) {
+        return h.endsWith(p.slice(1)) && h.length > p.length - 1;
+    }
+    return h === p;
+};
+/** Refuses a secret/host pairing the declarations do not permit. */
+export const assertSecretAllowedForHost = (secretId, url, secretDefinitions, requireAllowedHosts = false) => {
+    const host = (typeof url === 'string' ? new URL(url) : url).hostname;
+    const definition = Object.values(secretDefinitions ?? {}).find((d) => d.secretId === secretId);
+    const allowedHosts = definition?.allowedHosts;
+    if (!allowedHosts?.length) {
+        if (requireAllowedHosts) {
+            throw new SecretHostNotAllowedError(secretId, host, allowedHosts);
+        }
+        return;
+    }
+    if (!allowedHosts.some((pattern) => hostMatches(host, pattern))) {
+        throw new SecretHostNotAllowedError(secretId, host, allowedHosts);
+    }
+};

package/dist/services/secret-service.d.ts

@@ -1,42 +1,19 @@
-/**
- * Interface for retrieving and managing secrets.
- */
+import type { SecretValue } from '../secret-value.js';
+/** A record of secrets, each still wrapped. */
+export type SecretValues<T> = {
+    [K in keyof T]: SecretValue<T[K]>;
+};
 export interface SecretService {
-    /**
-     * Retrieves a secret by key, typed as T (defaults to string).
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws If the secret is not found.
-     */
-    getSecret<T = string>(key: string): Promise<T>;
-    /**
-     * Checks if a secret exists without throwing.
-     * @param key - The key of the secret to check.
-     * @returns A promise that resolves to true if the secret exists, false otherwise.
-     */
+    /** Throws if the secret is not found. Unwrap the result with `.reveal()`. */
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
+    /** Answers for any key, including a disallowed one — it must not throw. */
     hasSecret(key: string): Promise<boolean>;
-    /**
-     * Stores a secret value.
-     * @param key - The key to store the secret under.
-     * @param value - The value to store.
-     * @returns A promise that resolves when the secret is stored.
-     */
     setSecret(key: string, value: unknown): Promise<void>;
-    /**
-     * Deletes a secret by key.
-     * @param key - The key of the secret to delete.
-     * @returns A promise that resolves when the secret is deleted.
-     */
     deleteSecret(key: string): Promise<void>;
     /**
-     * Retrieves multiple secrets in a single batch operation.
-     * Returns a map of key → value for successfully fetched secrets; missing
-     * keys are omitted rather than throwing, so the result is typed as
-     * `Partial<T>` and callers must handle keys that may be absent at runtime.
-     *
-     * Pass a shape as `T` to get a typed result without casting, e.g.
-     * `await secrets.getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
-     * @param keys - The keys of the secrets to retrieve.
+     * Missing keys are omitted rather than throwing, hence `Partial<T>`: callers
+     * must handle keys absent at runtime. Pass a shape as `T` to avoid casting,
+     * e.g. `getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
      */
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }

package/dist/services/secretless.d.ts

@@ -0,0 +1,6 @@
+import type { SecretlessServices } from '../types/core.types.js';
+export declare class SecretAccessDeniedError extends Error {
+    constructor(context: string);
+}
+/** Returns `services` with `secrets` replaced by a throwing accessor. */
+export declare const withoutSecrets: <T extends object>(services: T, context: string) => SecretlessServices<T>;

package/dist/services/secretless.js

@@ -0,0 +1,21 @@
+export class SecretAccessDeniedError extends Error {
+    constructor(context) {
+        super(`'secrets' is not available inside ${context}. SecretService is confined to pikkuServices, pikkuWireServices, addon service factories and middleware — give a service the secret when you construct it and ask that service here.`);
+        this.name = 'SecretAccessDeniedError';
+    }
+}
+/** Returns `services` with `secrets` replaced by a throwing accessor. */
+export const withoutSecrets = (services, context) => {
+    if (!('secrets' in services)) {
+        return services;
+    }
+    const stripped = { ...services };
+    Object.defineProperty(stripped, 'secrets', {
+        get() {
+            throw new SecretAccessDeniedError(context);
+        },
+        configurable: true,
+        enumerable: false,
+    });
+    return stripped;
+};

package/dist/services/stub-tracker.d.ts

@@ -4,10 +4,9 @@ export type StubCall = {
     args: unknown[];
 };
 /**
- * Tracks calls made to stubbed services and enforces strict mode:
- * once a scenario asserts any call on a service, every recorded call on that
- * service must be verified by end of scenario — otherwise the After hook fails.
- * Services never touched by an assertion stay lenient.
+ * Strict per service: once a scenario asserts any call on a service, every
+ * recorded call on it must be verified by the end of the scenario or the After
+ * hook fails. A service no assertion ever touched stays lenient.
  */
 export declare class StubTracker {
     private readonly calls;
@@ -21,23 +20,13 @@ export declare class StubTracker {
     assertNoCalls(service: string, method?: string, predicate?: (args: unknown[]) => boolean, description?: string): void;
     verify(): void;
 }
-/**
- * Creates a Proxy suitable for passing as `existingServices` to
- * `createSingletonServices`. Every property returns `tracker.stub(prop)`
- * EXCEPT `schema`, which returns `undefined` so the service factory creates
- * a real schema service. Stubbing the schema makes validation a no-op —
- * required fields pass silently and tests validate nothing.
- */
+/** Pass as `existingServices` to `createSingletonServices`. */
 export declare function createStubProxy(tracker: StubTracker): Record<string, unknown>;
-/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+/** The process-wide tracker `stub()`/`spy()` record into; read by the console's getStubCalls/resetStubs RPCs. */
 export declare const getStubTracker: () => StubTracker;
-/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+/** True when the server was started by `pikku dev --test`, which sets PIKKU_TEST_RUN. */
 export declare const isTestRun: () => boolean;
-/**
- * Creates a recording fake for a service. Methods present on `impl` run and
- * their result is returned; missing methods resolve `undefined`. Every call
- * is recorded so scenarios can assert via workflow.expectService().
- */
+/** Methods on `impl` run and return; every other method resolves `undefined`. */
 export declare function stub<T = any>(service: string, impl?: Partial<T>): T;
 /** Wraps a real service so every method call is recorded and passed through */
 export declare function spy<T extends object>(service: string, real: T): T;

package/dist/services/stub-tracker.js

@@ -1,8 +1,7 @@
 /**
- * Tracks calls made to stubbed services and enforces strict mode:
- * once a scenario asserts any call on a service, every recorded call on that
- * service must be verified by end of scenario — otherwise the After hook fails.
- * Services never touched by an assertion stay lenient.
+ * Strict per service: once a scenario asserts any call on a service, every
+ * recorded call on it must be verified by the end of the scenario or the After
+ * hook fails. A service no assertion ever touched stays lenient.
  */
 export class StubTracker {
     calls = new Map();
@@ -87,16 +86,11 @@ export class StubTracker {
         }
     }
 }
-/**
- * Creates a Proxy suitable for passing as `existingServices` to
- * `createSingletonServices`. Every property returns `tracker.stub(prop)`
- * EXCEPT `schema`, which returns `undefined` so the service factory creates
- * a real schema service. Stubbing the schema makes validation a no-op —
- * required fields pass silently and tests validate nothing.
- */
+/** Pass as `existingServices` to `createSingletonServices`. */
 export function createStubProxy(tracker) {
     return new Proxy({}, {
         get(_, prop) {
+            // knowledge: decisions/internals/the-schema-service-is-never-stubbed.md
             if (prop === 'schema')
                 return undefined;
             return tracker.stub(prop);
@@ -104,16 +98,12 @@ export function createStubProxy(tracker) {
     });
 }
 const defaultStubTracker = new StubTracker();
-/** The process-wide tracker that `stub()`/`spy()` record into — read by the console's getStubCalls/resetStubs RPCs */
+/** The process-wide tracker `stub()`/`spy()` record into; read by the console's getStubCalls/resetStubs RPCs. */
 export const getStubTracker = () => defaultStubTracker;
-/** True when the server was started by `pikku dev --test` (sets PIKKU_TEST_RUN) */
+/** True when the server was started by `pikku dev --test`, which sets PIKKU_TEST_RUN. */
 export const isTestRun = () => globalThis
     .process?.env?.PIKKU_TEST_RUN === 'true';
-/**
- * Creates a recording fake for a service. Methods present on `impl` run and
- * their result is returned; missing methods resolve `undefined`. Every call
- * is recorded so scenarios can assert via workflow.expectService().
- */
+/** Methods on `impl` run and return; every other method resolves `undefined`. */
 export function stub(service, impl) {
     return new Proxy((impl ?? {}), {
         get(target, method) {

package/dist/services/system-role-guard.d.ts

@@ -0,0 +1,33 @@
+import type { Role } from './scope-service.js';
+/**
+ * The guards a {@link ScopeService} implementation must apply before mutating
+ * a role.
+ *
+ * Shared rather than left to each implementation because the rule is a
+ * contract, not a policy: a store that lets the console delete `buyer` makes
+ * every persona and scenario written against `buyer` silently stop testing
+ * what it claims to, and nothing fails at the point of the mistake. Two
+ * implementations disagreeing about that would be worse than either rule.
+ *
+ * `isSystemRole` is passed in rather than a role list, so an implementation can
+ * answer it from a column, a cached set, or a query, whichever is cheap.
+ */
+export type IsSystemRole = (name: string) => boolean | Promise<boolean>;
+/**
+ * Refuses a destructive or re-scoping operation against a declared role.
+ *
+ * @param operation a verb phrase for the message, e.g. `'delete role'`.
+ */
+export declare const assertRoleIsMutable: (name: string, isSystemRole: IsSystemRole, operation: string) => Promise<void>;
+/**
+ * Refuses a new custom role that would shadow a declared one.
+ */
+export declare const assertRoleNameAvailable: (name: string, isSystemRole: IsSystemRole) => Promise<void>;
+/**
+ * Why the console must render a role as locked, or `null` when it is editable.
+ *
+ * Returned rather than a boolean so the UI shows a reason instead of a
+ * disabled button with no explanation — the difference between a user filing a
+ * bug and a user editing the declaration.
+ */
+export declare const roleLockReason: (role: Role) => string | null;