@pikku/core 0.12.72 → 0.12.77

package/src/services/meta-service.ts

@@ -17,7 +17,8 @@ import type {
   FeaturesMeta,
   WorkflowsMeta,
 } from '../wirings/workflow/workflow.types.js'
-import type { ScenarioActorConfig } from './scenario-actors-service.js'
+import type { ResolvedPersona } from './personas-service.js'
+import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js'
 import type {
   TriggerMeta,
   TriggerSourceMeta,
@@ -34,7 +35,6 @@ import type {
 import type { AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js'
 import type { GatewaysMeta } from '../wirings/gateway/gateway.types.js'
 
-// Re-export core types for consumers
 export type {
   FunctionMeta,
   FunctionsMeta,
@@ -146,39 +146,26 @@ export interface EmailTemplateAssets {
   missing: string[]
 }
 
-/**
- * Abstraction over .pikku metadata file access.
- * All paths are relative to the .pikku root directory.
- *
- * Node.js uses LocalMetaService (filesystem).
- * Cloudflare uses an R2/KV implementation.
- */
+/** Every `relativePath` below is relative to the `.pikku` root directory. */
 export interface MetaService {
-  /** Base path for local filesystem implementations. Undefined for remote/non-local implementations. */
+  /** Undefined for remote/non-local implementations. */
   readonly basePath?: string
-  /** Read a file's content by relative path. Returns null if not found. */
   readFile(relativePath: string): Promise<string | null>
-  /** List files in a directory by relative path. Returns empty array if not found. */
   readDir(relativePath: string): Promise<string[]>
-  /** Read a project source file relative to the project root (one level above .pikku). */
+  /** Relative to the project root, one level above `.pikku`. */
   readProjectFile(relativePath: string): Promise<string | null>
   /**
-   * Read a file from an *installed addon package's* own `.pikku` directory
-   * (resolved from node_modules), NOT the app's `.pikku`. `relativePath` is
-   * relative to that package's `.pikku` root (use `../` to reach the package
-   * root itself, e.g. `../README.md`). Returns null if the package or file is
-   * absent. Only local/Node implementations resolve packages; remote impls omit
-   * this and callers guard with `?.`.
+   * Reads an *installed addon package's* own `.pikku`, not the app's, with
+   * `relativePath` rooted there (`../README.md` reaches the package root).
+   * Optional because only local/Node implementations resolve packages — remote
+   * ones omit it and callers guard with `?.`.
    */
   readPackageFile?(
     packageName: string,
     relativePath: string
   ): Promise<string | null>
-  /** List a directory inside an installed addon package's `.pikku`. */
   readPackageDir?(packageName: string, relativePath: string): Promise<string[]>
 
-  // -- Typed metadata accessors --
-
   getHttpMeta(): Promise<HTTPWiringsMeta>
   getChannelsMeta(): Promise<ChannelsMeta>
   getSchedulerMeta(): Promise<ScheduledTasksMeta>
@@ -188,7 +175,16 @@ export interface MetaService {
   getGatewayMeta(): Promise<GatewaysMeta>
   getRpcMeta(): Promise<RPCMetaRecord>
   getWorkflowMeta(): Promise<WorkflowsMeta>
-  getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>>
+  getPersonasMeta(): Promise<Record<string, ResolvedPersona>>
+  /**
+   * The roles declared with `defineSystemRole`, keyed by name.
+   *
+   * A persona declares roles; a function checks scopes. Anything showing what a
+   * persona can reach — the console's persona page, a run's catalogue — needs
+   * this to get from one to the other, and needs it to be the same expansion the
+   * seed granted from rather than a second one.
+   */
+  getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta>
   getFeaturesMeta(): Promise<FeaturesMeta>
   getTriggerMeta(): Promise<TriggerMeta>
   getTriggerSourceMeta(): Promise<TriggerSourceMeta>
@@ -212,10 +208,6 @@ export interface MetaService {
   clearCache(): void
 }
 
-/**
- * Node.js filesystem implementation of MetaService.
- * Reads .gen.json files from a local .pikku directory.
- */
 export class LocalMetaService implements MetaService {
   public readonly basePath: string
 
@@ -228,8 +220,8 @@ export class LocalMetaService implements MetaService {
   private gatewayMetaCache: GatewaysMeta | null = null
   private rpcMetaCache: RPCMetaRecord | null = null
   private workflowMetaCache: WorkflowsMeta | null = null
-  private scenarioActorsMetaCache: Record<string, ScenarioActorConfig> | null =
-    null
+  private personasMetaCache: Record<string, ResolvedPersona> | null = null
+  private systemRolesMetaCache: SystemRoleDefinitionsMeta | null = null
   private featuresMetaCache: FeaturesMeta | null = null
   private triggerMetaCache: TriggerMeta | null = null
   private triggerSourceMetaCache: TriggerSourceMeta | null = null
@@ -271,10 +263,7 @@ export class LocalMetaService implements MetaService {
     }
   }
 
-  // Resolve an installed addon package's root dir from the app's node_modules.
-  // The addon packages have no main `exports` entry, so `require.resolve(pkg)`
-  // throws; instead we walk the node_modules search paths (anchored at the app
-  // root, one level above `.pikku`) and pick the first that contains the package.
+  // knowledge: decisions/internals/addon-package-roots-resolve-by-walking-node-module-search-paths.md
   private packageRootCache = new Map<string, string | null>()
   private resolvePackageRoot(packageName: string): string | null {
     const cached = this.packageRootCache.get(packageName)
@@ -332,7 +321,8 @@ export class LocalMetaService implements MetaService {
     this.gatewayMetaCache = null
     this.rpcMetaCache = null
     this.workflowMetaCache = null
-    this.scenarioActorsMetaCache = null
+    this.personasMetaCache = null
+    this.systemRolesMetaCache = null
     this.featuresMetaCache = null
     this.triggerMetaCache = null
     this.triggerSourceMetaCache = null
@@ -347,8 +337,6 @@ export class LocalMetaService implements MetaService {
     this.schemaCache.clear()
   }
 
-  // -- Private helpers --
-
   private async readMetaJson<T>(
     dir: string,
     baseName: string
@@ -360,8 +348,6 @@ export class LocalMetaService implements MetaService {
     return null
   }
 
-  // -- Typed metadata accessors --
-
   async getHttpMeta(): Promise<HTTPWiringsMeta> {
     if (this.httpMetaCache) return this.httpMetaCache
 
@@ -496,9 +482,7 @@ export class LocalMetaService implements MetaService {
 
     try {
       const result: WorkflowsMeta = {}
-      // Scenarios keep their meta in `scenarios/meta` so nothing app-facing
-      // imports them, but they are still workflows to anything reading meta off
-      // disk — the console's scenario list among them.
+      // knowledge: decisions/internals/scenario-meta-lives-apart-from-app-meta-but-merges-when-read-off-disk.md
       await Promise.all([
         this.readWorkflowMetaDir('workflow/meta', result),
         this.readWorkflowMetaDir('scenarios/meta', result),
@@ -513,12 +497,21 @@ export class LocalMetaService implements MetaService {
     }
   }
 
-  async getScenarioActorsMeta(): Promise<Record<string, ScenarioActorConfig>> {
-    if (this.scenarioActorsMetaCache) return this.scenarioActorsMetaCache
+  async getPersonasMeta(): Promise<Record<string, ResolvedPersona>> {
+    if (this.personasMetaCache) return this.personasMetaCache
+
+    const content = await this.readFile('workflow/personas.gen.json')
+    this.personasMetaCache = content ? JSON.parse(content) : {}
+    return this.personasMetaCache!
+  }
+
+  async getSystemRolesMeta(): Promise<SystemRoleDefinitionsMeta> {
+    if (this.systemRolesMetaCache) return this.systemRolesMetaCache
 
-    const content = await this.readFile('workflow/scenario-actors.gen.json')
-    this.scenarioActorsMetaCache = content ? JSON.parse(content) : {}
-    return this.scenarioActorsMetaCache!
+    // Beside the scopes it is composed from, which is where codegen writes it.
+    const content = await this.readFile('scopes/pikku-roles-meta.gen.json')
+    this.systemRolesMetaCache = content ? JSON.parse(content) : {}
+    return this.systemRolesMetaCache!
   }
 
   async getFeaturesMeta(): Promise<FeaturesMeta> {
@@ -556,8 +549,6 @@ export class LocalMetaService implements MetaService {
 
     const [content, scenarioContent] = await Promise.all([
       this.readMetaJson('function', 'pikku-functions-meta'),
-      // Scenario steps register only into the scenario bootstrap, but they are
-      // still functions to anything reading meta off disk.
       this.readMetaJson('scenarios', 'pikku-scenario-functions-meta'),
     ])
     this.functionsMetaCache = {
@@ -635,12 +626,7 @@ export class LocalMetaService implements MetaService {
   }
 
   async getEmailMeta(): Promise<EmailsMeta> {
-    // Read fresh every call — never cache. The email meta file is generated by
-    // `pikku all`/`pikku emails generate` and is regenerated DURING a long-lived
-    // session (sandbox boots the orchestrator before the user project's codegen
-    // has written it). Caching here once returned an empty {templates:{}} that
-    // then stuck for the whole session, leaving the console emails screen blank
-    // even after the file appeared. A local JSON read is essentially free.
+    // knowledge: decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md
     const content = await this.readFile('email/pikku-emails-meta.gen.json')
     return content
       ? JSON.parse(content)
@@ -662,9 +648,7 @@ export class LocalMetaService implements MetaService {
       )
     }
 
-    // emailsMeta.src is an absolute path resolved by the CLI at generation time.
-    // Read directly rather than through readProjectFile (which prepends the project
-    // root and produces a wrong compound path when baseDir is absolute).
+    // knowledge: decisions/internals/generated-src-paths-in-pikku-meta-are-absolute.md
     const baseDir = emailsMeta.src
     const readEmailFile = async (rel: string): Promise<string | null> => {
       try {
@@ -700,10 +684,6 @@ export class LocalMetaService implements MetaService {
     ]
 
     if (missing.length > 0) {
-      // Diagnostic for the intermittent "Missing source files" report: logs which
-      // process and which resolved baseDir saw the gap. Different pids across
-      // failures => multiple runtime workers with divergent cached `src`; same pid
-      // + transient absence => files being rewritten under us (e.g. regeneration).
       console.warn(
         `[email-assets] pid=${process.pid} template=${templateName} locale=${locale} baseDir=${baseDir} missing=${missing.join(',')}`
       )

package/src/services/{scenario-actors-service.ts → personas-service.ts}

@@ -2,6 +2,7 @@ import type {
   ConverseOptions,
   ActorFlowVerdict,
 } from '../wirings/actor-flow/actor-flow.types.js'
+import type { PersonaMeta } from '../wirings/persona/persona.types.js'
 
 /**
  * What the transport answered, for a step that treats the status as data.
@@ -34,8 +35,8 @@ export interface ScenarioHttpResponse<T = unknown> {
  * Drain a response into the shape a step can carry: the parsed body (an empty
  * one counting as no body at all) alongside the text it was parsed from.
  *
- * `invokeRaw` returns this, and a step that has to reach past an actor — a
- * route with no RPC, an identity no actor can hold — reaches for this rather
+ * `invokeRaw` returns this, and a step that has to reach past a persona — a
+ * route with no RPC, an identity no persona can hold — reaches for this rather
  * than writing the same record by hand.
  */
 export const readScenarioHttpResponse = async <T = unknown>(
@@ -77,7 +78,7 @@ export interface ScenarioJsonRequest {
 /**
  * POST JSON somewhere and report what came back, without throwing on a 4xx/5xx.
  *
- * Every scenario that reaches past an actor was writing this by hand — the same
+ * Every scenario that reaches past a persona was writing this by hand — the same
  * `content-type`, the same `JSON.stringify`, the same drain — and the copies had
  * drifted: some returned `res.json()`, which loses the status and throws
  * outright when the target answers an empty body or an HTML error page. A
@@ -104,39 +105,45 @@ export const postScenarioJson = async <T = unknown>(
 /** Per-call transport options. */
 export interface ScenarioInvokeOptions {
   /**
-   * Headers to send alongside the actor's own session. This is how a step
-   * expresses an identity the actor registry cannot — an impersonation header,
-   * or one of the header-shim principals a credential scenario invents.
+   * Headers to send alongside the persona's own session. This is how a step
+   * expresses an identity no declared persona can — an impersonation header, or
+   * one of the header-shim principals a credential scenario invents.
    */
   headers?: Record<string, string>
 }
 
 /**
- * The RPC surface an actor can reach, as name → input/output. A project binds
+ * The RPC surface a persona can reach, as name → input/output. A project binds
  * its generated exposed RPC map here; the default leaves every name open, which
- * is what an actor built by hand (or by a third-party driver) gets.
+ * is what a persona built by hand (or by a third-party driver) gets.
  */
 export type ScenarioRpcMap = Record<string, { input: any; output: any }>
 
 /**
- * The actor a step wire carries, for a project whose actor registry is known.
- * An empty registry keeps the open actor type rather than collapsing to
- * `never` — a project may still build actors itself.
+ * The persona a step's `actor` slot carries, for a project whose personas are
+ * known. No declared personas keeps the open type rather than collapsing to
+ * `never` — a project may still build one itself.
  */
-export type ScenarioActorOf<TActors> = [keyof TActors] extends [never]
-  ? ScenarioActor
-  : TActors[keyof TActors]
+export type ScenarioPersonaOf<TPersonas> = [keyof TPersonas] extends [never]
+  ? ScenarioPersona
+  : TPersonas[keyof TPersonas]
 
-/** A synthetic user (a user row flagged `actor`) that workflow steps run as over the real transport */
-export interface ScenarioActor<
+/**
+ * A declared person, signed in and acting over the real transport.
+ *
+ * The runtime half of `definePersonas()`: sign-in materialises a user row
+ * flagged `actor: true`, and everything a step or a virtual user does goes
+ * through here.
+ */
+export interface ScenarioPersona<
   TAgentName extends string = string,
   TRpcMap extends ScenarioRpcMap = ScenarioRpcMap,
 > {
-  /** Stable actor name (the key in pikku.config.json's actor registry). */
+  /** The id it was declared under — what a step's `actor` slot names. */
   readonly name: string
-  /** The actor's user email — flows use it for invites/lookups. */
+  /** Their address, computed from the id. Flows use it for invites/lookups. */
   readonly email: string
-  /** Invoke an exposed RPC as this actor over the real transport. */
+  /** Invoke an exposed RPC as this person over the real transport. */
   invoke<TName extends keyof TRpcMap & string>(
     rpcName: TName,
     data: TRpcMap[TName]['input']
@@ -151,32 +158,30 @@ export interface ScenarioActor<
     data: TRpcMap[TName]['input'],
     options?: ScenarioInvokeOptions
   ): Promise<ScenarioHttpResponse>
-  /** Converse with a Pikku AI agent in this actor's persona and return its verdict */
+  /** Converse with a Pikku AI agent in character and return its verdict. */
   converse(options: ConverseOptions<TAgentName>): Promise<ActorFlowVerdict>
-}
-
-/** Display/config metadata for an actor (from pikku.config.json) */
-export interface ScenarioActorConfig {
-  email: string
-  name?: string
-  jobTitle?: string
-  personality?: string
-  /**
-   * The persona this body is one of — the KIND of person, declared in
-   * `scenarios.personas`. Most personas have exactly one actor and it is
-   * materialised for them; a second body of the same persona is what tenant
-   * isolation and peer-sharing scenarios are made of.
-   */
-  persona?: string
   /**
-   * Scopes this actor holds, granted directly rather than through a role, and
-   * the roles it belongs to. Pikku carries them; it never applies them — which
-   * scope store exists and which roles have been created is the app's own, so
-   * the app's seed reads these back off `scenarioActorConfigs` and grants them.
+   * The roles this person actually holds on the stage, read back after signing
+   * in — what a run compares against the declaration before its first step.
+   *
+   * `null` when the target does not say. That is not the same as "no roles": a
+   * run that treats silence as an empty list refuses to start against every
+   * stage whose auth reports roles somewhere else, so the caller must decide
+   * whether it can verify at all.
    */
-  scopes?: readonly string[]
-  roles?: readonly string[]
+  sessionRoles(): Promise<string[] | null>
 }
 
-/** The injected `actors` service: actor name → actor. */
-export type ScenarioActors = Record<string, ScenarioActor>
+/**
+ * A declared persona with its address filled in — what codegen writes and what
+ * a seed, a scenario run and a virtual-user run all read.
+ *
+ * The address is not declared. It is derived from the persona's id and the
+ * project's persona domain, so two people can never accidentally share one and
+ * sign in as the same user row — which would silently collapse exactly the
+ * isolation scenarios a second person exists for.
+ */
+export type ResolvedPersona = PersonaMeta & { email: string }
+
+/** The injected `personas` service: persona id → persona. */
+export type ScenarioPersonas = Record<string, ScenarioPersona>

package/src/services/pikku-user-id.ts

@@ -3,15 +3,11 @@ import type { PikkuRawWire } from '../types/core.types.js'
 export type PikkuUserIdResolver = (wire: PikkuRawWire) => string | undefined
 
 export const defaultPikkuUserIdResolver: PikkuUserIdResolver = (wire) => {
-  // Explicit pikkuUserId on wire (set by earlier middleware or runner)
   if (wire.pikkuUserId) return wire.pikkuUserId
-  // Session userId (from auth middleware — user-defined session shape)
   const session = wire.session as Record<string, unknown> | undefined
   if (session?.userId && typeof session.userId === 'string')
     return session.userId
-  // Queue job: carried in job metadata
   if (wire.queue?.pikkuUserId) return wire.queue.pikkuUserId
-  // Workflow: carried in run wire metadata
   if (wire.workflow?.pikkuUserId) return wire.workflow.pikkuUserId
   return undefined
 }

package/src/services/queue-webhook-service.test.ts

@@ -14,6 +14,7 @@ import { InMemoryQueueService } from './in-memory-queue-service.js'
 import { wireQueueWorker } from '../wirings/queue/queue-runner.js'
 import { resetPikkuState, pikkuState } from '../pikku-state.js'
 import type { JobOptions } from '../wirings/queue/queue.types.js'
+import { createSecretValue } from '../secret-value.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
@@ -132,7 +133,7 @@ describe('QueueWebhookService.send', () => {
       secrets: {
         getSecret: async (key: string) => {
           assert.equal(key, 'WEBHOOK_SIGNING_KEY')
-          return 'resolved-key'
+          return createSecretValue('resolved-key')
         },
       },
     })

package/src/services/queue-webhook-service.ts

@@ -13,23 +13,11 @@ import {
   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 {
-  /**
-   * 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(protected queueService: QueueService) {
     super()
   }
@@ -45,10 +33,8 @@ export class QueueWebhookService extends WebhookService {
   }
 
   /**
-   * 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.
    */
   protected async prepareDelivery(
     input: SendWebhookInput
@@ -65,8 +51,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.`
@@ -89,13 +75,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
   private resolveJobOptions(input: SendWebhookInput): JobOptions {
     const webhookConfig = getSingletonServices().config?.webhook
     const retries =
@@ -111,18 +91,7 @@ export class QueueWebhookService extends WebhookService {
   }
 }
 
-/**
- * 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: { logger: Logger; webhookService?: WebhookService },
   { url, body, headers, deliveryId }: WebhookJobData
@@ -136,8 +105,8 @@ export async function pikkuWebhookWorkerFunc(
   try {
     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 {
@@ -165,7 +134,6 @@ export async function pikkuWebhookWorkerFunc(
   }
 
   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) =>

package/src/services/scheduler-service.ts

@@ -1,47 +1,21 @@
 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 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,
@@ -49,38 +23,15 @@ export abstract class SchedulerService {
     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
-   */
   async start(): Promise<void> {}
 
-  /**
-   * Stop recurring scheduled tasks
-   */
   async stop(): Promise<void> {}
 }

package/src/services/schema-service.ts

@@ -1,33 +1,10 @@
-/**
- * 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[]
 }