@pikku/core 0.12.29 → 0.12.30

package/CHANGELOG.md

@@ -1,3 +1,67 @@
+## 0.12.30
+
+### Patch Changes
+
+- cd101a5: feat(core): add `auditLog` service slot for per-invocation audit logs
+
+  `CoreSingletonServices` now declares `auditLog?: AuditLog`, giving the
+  per-request audit log returned by `createInvocationAudit` a typed home in the
+  service container. Apps wire it in `createWireServices`
+  (`return { auditLog, kysely: createAuditedKysely(kysely, { audit: auditLog }) }`)
+  and the runner flushes its buffer via `close()` when the invocation ends.
+
+  Previously there was no slot to return it from: `audit` is typed `AuditService`
+  (the durable sink, `.audit()`), while `createInvocationAudit` returns an
+  `AuditLog` (the request-scoped buffer, `.write/.flush/.close`). Returning the
+  buffer under `audit` was a type error, so audited-Kysely wiring could not
+  type-check. `auditLog` is distinct from `audit` and never shadows it.
+
+- ac16265: fix(core): read email template assets from the absolute `emailsMeta.src` directly
+
+  `getEmailTemplateAssets` passed an absolute `baseDir` (e.g. `/project/emails`) into
+  `readProjectFile`, which resolves `join(basePath, '..', relativePath)`. Because
+  `path.join` does not treat an absolute second segment as a root reset, this produced
+  a non-existent compound path (`/project/packages/functions/project/emails/...`), so
+  every asset read returned `null` and the email preview reported all source files
+  (`theme, locale, html, subject, text`) as missing. Read the assets directly via
+  `readFile(join(baseDir, rel))` instead, which resolves correctly for an absolute
+  base. Verified live: a previously all-missing preview now renders.
+
+- a05e864: fix(core): allow multiple independent suspend points in one workflow
+
+  `getSuspendStepName()` returned the constant `'__workflow_suspend'` for every
+  `workflow.suspend()` call, so all suspends in a run shared a single step row.
+  Once the first suspend resolved (row → `succeeded`), every later `suspend()`
+  read that same `succeeded` row and fell straight through without pausing — so a
+  workflow could only ever have one working suspend point, and a second one (e.g.
+  wait-for-build, then wait-for-approval) was silently skipped.
+
+  The suspend step is now keyed on its `reason` (used raw, just namespaced so it
+  can't collide with a `do`/`sleep` step of the same name), so each distinct
+  reason is its own step row. A workflow can now have multiple independent
+  suspends, including dynamic reasons in loops (`suspend(`Wait for ${i}`)`),
+  exactly like dynamic `do()` step names. As with `do()`/`sleep()`, the reason is
+  the suspend's stable identity and must be derived deterministically so it
+  matches on replay. `suspend(reason)` is unchanged at the call site.
+
+- 20750fd: feat(workflow): decide step dispatch purely per-function
+
+  Workflow step execution (inline vs queue dispatch) is now decided entirely by
+  the step's function `inline` flag — the workflow-level / run-level `inline`
+  meta no longer participates in per-step dispatch.
+  - Steps default to **inline**, so a normally-started (queue-backed) workflow
+    runs its whole chain in one orchestrator pass instead of one queue
+    round-trip per step.
+  - A function marked `inline: false` is dispatched via the queue (its own
+    worker, retry isolation). When `inline: false` but no `queueService` is
+    configured, the step falls back to inline and emits a `logger.warn` instead
+    of silently swallowing the misconfiguration.
+  - Removed the now-unused workflow-level `inline` from `WorkflowsMeta` /
+    `WorkflowRuntimeMeta`, the inspector's workflow extraction, the DSL→graph
+    converter, and the deploy analyzer / service inference (which now key off
+    the per-function flag). Run-level `inline` is retained: it still controls
+    whether a whole run executes in-process without queue infrastructure.
+
 ## 0.12.29
 
 ### Patch Changes

package/dist/services/meta-service.js

@@ -306,6 +306,20 @@ export class LocalMetaService {
             readEmailFile(`templates/${templateName}.subject.txt`),
             readEmailFile(`templates/${templateName}.text.txt`),
         ]);
+        const missing = [
+            ...(themeRaw ? [] : ['theme']),
+            ...(localeRaw ? [] : ['locale']),
+            ...(templateHtml ? [] : ['html']),
+            ...(templateSubject ? [] : ['subject']),
+            ...(templateText ? [] : ['text']),
+        ];
+        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(',')}`);
+        }
         return {
             theme: themeRaw ? JSON.parse(themeRaw) : {},
             strings: localeRaw
@@ -318,13 +332,7 @@ export class LocalMetaService {
             html: templateHtml ?? '',
             subject: templateSubject ?? '',
             text: templateText ?? '',
-            missing: [
-                ...(themeRaw ? [] : ['theme']),
-                ...(localeRaw ? [] : ['locale']),
-                ...(templateHtml ? [] : ['html']),
-                ...(templateSubject ? [] : ['subject']),
-                ...(templateText ? [] : ['text']),
-            ],
+            missing,
         };
     }
     async getServicesMeta() {

package/dist/types/core.types.d.ts

@@ -28,7 +28,7 @@ import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
 import type { MetaService } from '../services/meta-service.js';
 import type { SessionStore } from '../services/session-store.js';
-import type { AuditDurability, AuditService } from '../services/audit-service.js';
+import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
 export interface FunctionServicesMeta {
     optimized: boolean;
@@ -196,6 +196,14 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     metaService?: MetaService;
     /** Audit service for durable or staged audit event capture */
     audit?: AuditService;
+    /**
+     * Per-invocation audit log. Typically created in `createWireServices` via
+     * `createInvocationAudit(audit, wire)` and returned as a wire service so the
+     * runner flushes its buffer (via `close()`) when the invocation ends. Distinct
+     * from `audit` (the durable sink): this is the request-scoped buffer that
+     * writes into it.
+     */
+    auditLog?: AuditLog;
     /** Session store for persisting user sessions keyed by pikkuUserId */
     sessionStore?: SessionStore;
 }

package/dist/wirings/secret/secret.types.d.ts

@@ -4,6 +4,12 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
+     * Stored in the generated secrets metadata so consumers can tell when a
+     * secret was last updated and whether it is due for rotation.
+     */
+    rotationPeriod?: string;
 };
 export type OAuth2CredentialConfig = {
     tokenSecretId: string;
@@ -20,6 +26,7 @@ export type SecretDefinitionMeta = {
     secretId: string;
     schema?: Record<string, unknown> | string;
     oauth2?: OAuth2CredentialConfig;
+    rotationPeriod?: string;
     sourceFile?: string;
 };
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -33,6 +33,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     secretId: def.secretId,
                     schema: def.schema,
                     oauth2: def.oauth2,
+                    rotationPeriod: def.rotationPeriod,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -47,6 +48,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 secretId: def.secretId,
                 schema: def.schema,
                 oauth2: def.oauth2,
+                rotationPeriod: def.rotationPeriod,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -27,7 +27,11 @@ export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> |
  */
 export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<void>;
 /**
- * Type signature for workflow.suspend() - used by inspector
+ * Type signature for workflow.suspend() - used by inspector.
+ * `reason` is both the human-readable message stored on the suspended run and
+ * the suspend point's stable identity (used raw as the durable step name), so a
+ * workflow can have multiple independent suspends — including dynamic reasons in
+ * loops, like dynamic `do()` step names.
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>;
 /**

package/dist/wirings/workflow/graph/graph-runner.js

@@ -359,7 +359,7 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
                 parentRunId: runId,
                 parentStepId: stepId,
             };
-            const shouldInline = subWorkflowMeta.inline || !getSingletonServices()?.queueService;
+            const shouldInline = !getSingletonServices()?.queueService;
             const { runId: childRunId } = await workflowService.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
             await workflowService.setStepChildRunId(stepId, childRunId);
             if (shouldInline) {

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -335,6 +335,17 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private rpcStep;
     private inlineStep;
     private sleepStep;
+    /**
+     * Derive the durable step name for a suspend point from its `reason`, so each
+     * distinct reason is its own step row — letting one workflow have multiple
+     * independent suspends (e.g. wait-for-build, then wait-for-approval), and
+     * supporting dynamic reasons in loops (`suspend(`Wait for ${i}`)`) exactly
+     * like dynamic `do()` step names. The reason is used raw (it's just a text
+     * step name), only namespaced so it can't collide with a `do`/`sleep` step of
+     * the same name. Like `do()` / `sleep()`, the reason is the step's stable
+     * identity: it MUST be derived deterministically so it's the same every time
+     * the workflow replays through that point.
+     */
     private getSuspendStepName;
     private suspendStep;
     createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuWorkflowWire;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -484,16 +484,25 @@ export class PikkuWorkflowService {
      *   through to the inline execution path.
      */
     async dispatchStep(runId, stepName, rpcName, data, stepOptions) {
-        if (!getSingletonServices()?.queueService) {
-            return false;
-        }
-        // Functions default to inline execution. Only dispatch via queue when the
-        // function explicitly sets inline: false.
+        // Step execution is decided purely by the function's `inline` flag (default
+        // true). Only a function explicitly marked `inline: false` dispatches via
+        // the queue. The run-level inline state is intentionally NOT consulted
+        // here: default steps run inline even inside a queue-dispatched run, so a
+        // normally-started workflow executes its steps in one orchestrator-worker
+        // pass instead of one queue round-trip per step.
         const functionsMeta = pikkuState(null, 'function', 'meta');
         const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName];
         const rpcMeta = typeof rpcFuncId === 'string' ? functionsMeta[rpcFuncId] : undefined;
         const forceQueue = rpcMeta?.inline === false;
-        if (!forceQueue && this.isInline(runId)) {
+        if (!forceQueue) {
+            return false;
+        }
+        // The function opted out of inline execution (`inline: false`) but no queue
+        // service is configured to dispatch it. Fall back to inline so the workflow
+        // still progresses, but warn loudly — silently swallowing this hides a real
+        // misconfiguration (the step won't get its own worker/retry isolation).
+        if (!getSingletonServices()?.queueService) {
+            getSingletonServices()?.logger.warn(`Workflow step '${stepName}' (function '${rpcName}') is marked 'inline: false' but no queue service is configured — running it inline instead of dispatching to a queue.`);
             return false;
         }
         const retries = stepOptions?.retries ?? 0;
@@ -553,9 +562,7 @@ export class PikkuWorkflowService {
         }
         if (workflowMeta.source === 'graph' ||
             workflowMeta.source === 'dynamic-workflow') {
-            const shouldInline = options?.inline ||
-                workflowMeta.inline ||
-                !getSingletonServices()?.queueService;
+            const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire, workflowMeta);
         }
         // DSL workflow - check registration exists
@@ -567,9 +574,7 @@ export class PikkuWorkflowService {
         if (!workflowMeta.graphHash) {
             throw new Error(`Missing workflow graphHash for '${name}'`);
         }
-        const shouldInline = options?.inline ||
-            workflowMeta.inline ||
-            !getSingletonServices()?.queueService;
+        const shouldInline = options?.inline || !getSingletonServices()?.queueService;
         const runId = await this.createRun(name, input, shouldInline, workflowMeta.graphHash, wire, {
             deterministic: workflowMeta.deterministic,
             plannedSteps: workflowMeta.plannedSteps,
@@ -808,7 +813,7 @@ export class PikkuWorkflowService {
                             parentRunId: runId,
                             parentStepId: stepState.stepId,
                         };
-                        const shouldInline = subWorkflowMeta.inline || !getSingletonServices()?.queueService;
+                        const shouldInline = !getSingletonServices()?.queueService;
                         const { runId: childRunId } = await this.startWorkflow(rpcName, data, childWire, rpcService, { inline: shouldInline });
                         await this.setStepChildRunId(stepState.stepId, childRunId);
                         if (shouldInline) {
@@ -1115,26 +1120,34 @@ export class PikkuWorkflowService {
         await new Promise((resolve) => setTimeout(resolve, getDurationInMilliseconds(duration)));
         await this.setStepResult(stepState.stepId, null);
     }
+    /**
+     * Derive the durable step name for a suspend point from its `reason`, so each
+     * distinct reason is its own step row — letting one workflow have multiple
+     * independent suspends (e.g. wait-for-build, then wait-for-approval), and
+     * supporting dynamic reasons in loops (`suspend(`Wait for ${i}`)`) exactly
+     * like dynamic `do()` step names. The reason is used raw (it's just a text
+     * step name), only namespaced so it can't collide with a `do`/`sleep` step of
+     * the same name. Like `do()` / `sleep()`, the reason is the step's stable
+     * identity: it MUST be derived deterministically so it's the same every time
+     * the workflow replays through that point.
+     */
     getSuspendStepName(reason) {
-        if (!reason) {
-            return '__workflow_suspend';
-        }
-        return '__workflow_suspend';
+        return `__workflow_suspend:${reason}`;
     }
     async suspendStep(runId, reason) {
-        const stepName = this.getSuspendStepName(reason);
-        await this.withStepLock(runId, stepName, async () => {
+        const suspendStepName = this.getSuspendStepName(reason);
+        await this.withStepLock(runId, suspendStepName, async () => {
             let stepState;
             try {
-                stepState = await this.getStepState(runId, stepName);
+                stepState = await this.getStepState(runId, suspendStepName);
             }
             catch {
-                stepState = await this.insertStepState(runId, stepName, 'pikkuWorkflowSuspend', {
+                stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
                     reason,
                 });
             }
             if (!stepState.stepId) {
-                stepState = await this.insertStepState(runId, stepName, 'pikkuWorkflowSuspend', {
+                stepState = await this.insertStepState(runId, suspendStepName, 'pikkuWorkflowSuspend', {
                     reason,
                 });
             }
@@ -1175,7 +1188,8 @@ export class PikkuWorkflowService {
                 await this.sleepStep(runId, stepName, getDurationInMilliseconds(duration));
             },
             suspend: async (reason) => {
-                await this.suspendStep(runId, reason || 'Workflow suspended');
+                this.verifyStepName(reason);
+                await this.suspendStep(runId, reason);
             },
         };
         return workflowWire;

package/dist/wirings/workflow/workflow.types.d.ts

@@ -228,7 +228,6 @@ export type WorkflowsMeta = Record<string, CommonWireMeta & {
     steps: WorkflowStepMeta[];
     context?: WorkflowContext;
     dsl?: boolean;
-    inline?: boolean;
     expose?: boolean;
 }>;
 /**
@@ -247,8 +246,6 @@ export interface WorkflowRuntimeMeta {
     description?: string;
     /** Tags for organization */
     tags?: string[];
-    /** If true, workflow always executes inline without queues */
-    inline?: boolean;
     /** Serialized nodes */
     nodes?: Record<string, any>;
     /** Entry node IDs for graph workflows (computed at build time) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.29",
+  "version": "0.12.30",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/services/meta-service.ts

@@ -562,6 +562,24 @@ export class LocalMetaService implements MetaService {
       readEmailFile(`templates/${templateName}.text.txt`),
     ])
 
+    const missing = [
+      ...(themeRaw ? [] : ['theme']),
+      ...(localeRaw ? [] : ['locale']),
+      ...(templateHtml ? [] : ['html']),
+      ...(templateSubject ? [] : ['subject']),
+      ...(templateText ? [] : ['text']),
+    ]
+
+    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(',')}`
+      )
+    }
+
     return {
       theme: themeRaw ? (JSON.parse(themeRaw) as Record<string, unknown>) : {},
       strings: localeRaw
@@ -574,13 +592,7 @@ export class LocalMetaService implements MetaService {
       html: templateHtml ?? '',
       subject: templateSubject ?? '',
       text: templateText ?? '',
-      missing: [
-        ...(themeRaw ? [] : ['theme']),
-        ...(localeRaw ? [] : ['locale']),
-        ...(templateHtml ? [] : ['html']),
-        ...(templateSubject ? [] : ['subject']),
-        ...(templateText ? [] : ['text']),
-      ],
+      missing,
     }
   }
 

package/src/types/core.types.ts

@@ -40,6 +40,7 @@ import type { MetaService } from '../services/meta-service.js'
 import type { SessionStore } from '../services/session-store.js'
 import type {
   AuditDurability,
+  AuditLog,
   AuditService,
 } from '../services/audit-service.js'
 
@@ -255,6 +256,14 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   metaService?: MetaService
   /** Audit service for durable or staged audit event capture */
   audit?: AuditService
+  /**
+   * Per-invocation audit log. Typically created in `createWireServices` via
+   * `createInvocationAudit(audit, wire)` and returned as a wire service so the
+   * runner flushes its buffer (via `close()`) when the invocation ends. Distinct
+   * from `audit` (the durable sink): this is the request-scoped buffer that
+   * writes into it.
+   */
+  auditLog?: AuditLog
   /** Session store for persisting user sessions keyed by pikkuUserId */
   sessionStore?: SessionStore
 }

package/src/wirings/secret/secret.types.ts

@@ -4,6 +4,12 @@ export type CoreSecret<T = unknown> = {
   description?: string
   secretId: string
   schema: T
+  /**
+   * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
+   * Stored in the generated secrets metadata so consumers can tell when a
+   * secret was last updated and whether it is due for rotation.
+   */
+  rotationPeriod?: string
 }
 
 export type OAuth2CredentialConfig = {
@@ -22,6 +28,7 @@ export type SecretDefinitionMeta = {
   secretId: string
   schema?: Record<string, unknown> | string
   oauth2?: OAuth2CredentialConfig
+  rotationPeriod?: string
   sourceFile?: string
 }
 

package/src/wirings/secret/validate-secret-definitions.ts

@@ -57,6 +57,7 @@ export function validateAndBuildSecretDefinitionsMeta(
           secretId: def.secretId,
           schema: def.schema,
           oauth2: def.oauth2,
+          rotationPeriod: def.rotationPeriod,
           sourceFile: def.sourceFile,
         }
       }
@@ -73,6 +74,7 @@ export function validateAndBuildSecretDefinitionsMeta(
         secretId: def.secretId,
         schema: def.schema,
         oauth2: def.oauth2,
+        rotationPeriod: def.rotationPeriod,
         sourceFile: def.sourceFile,
       }
     }

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -46,7 +46,11 @@ export type WorkflowWireSleep = (
 ) => Promise<void>
 
 /**
- * Type signature for workflow.suspend() - used by inspector
+ * Type signature for workflow.suspend() - used by inspector.
+ * `reason` is both the human-readable message stored on the suspended run and
+ * the suspend point's stable identity (used raw as the durable step name), so a
+ * workflow can have multiple independent suspends — including dynamic reasons in
+ * loops, like dynamic `do()` step names.
  */
 export type WorkflowWireSuspend = (reason: string) => Promise<void>
 

package/src/wirings/workflow/graph/graph-runner.test.ts

@@ -485,7 +485,7 @@ describe('graph-runner bugs', () => {
     delete metaState['testInlineRpcMissing']
   })
 
-  test('graph workflow with inline: true in meta should run inline', async () => {
+  test('graph workflow started with the inline flag should run inline', async () => {
     const ws = new InMemoryWorkflowService()
     let executed = false
 
@@ -511,7 +511,6 @@ describe('graph-runner bugs', () => {
       name: 'testInlineMetaGraph',
       pikkuFuncId: 'testInlineMetaGraph',
       source: 'graph',
-      inline: true,
       entryNodeIds: ['a'],
       graphHash: 'inline-meta-graph-hash',
       nodes: {

package/src/wirings/workflow/graph/graph-runner.ts

@@ -497,8 +497,7 @@ export async function executeGraphStep(
         parentRunId: runId,
         parentStepId: stepId,
       }
-      const shouldInline =
-        subWorkflowMeta.inline || !getSingletonServices()?.queueService
+      const shouldInline = !getSingletonServices()?.queueService
       const { runId: childRunId } = await workflowService.startWorkflow(
         rpcName,
         data,