@pikku/core 0.12.28 → 0.12.30

package/CHANGELOG.md

@@ -1,3 +1,73 @@
+## 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
+
+- 294e365: Fix body stream caching in PikkuFetchHTTPRequest so that arrayBuffer() can be called after body() has already consumed the stream via text(). This is required for Auth.js CSRF validation to work correctly when integrated with Pikku's internal fetch.
+
 ## 0.12.28
 
 ### 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/http/pikku-fetch-http-request.js

@@ -11,6 +11,9 @@ export class PikkuFetchHTTPRequest {
     #cookies;
     #params = {};
     #url;
+    #rawBodyText;
+    #rawBodyBuffer;
+    #bodyRead = false;
     constructor(request) {
         this.request = request;
         this.#url = new URL(request.url);
@@ -25,15 +28,45 @@ export class PikkuFetchHTTPRequest {
      * Retrieves the request body.
      * @returns A promise that resolves to the request body.
      */
-    json() {
-        return this.request.json();
+    async json() {
+        const text = await this.#readRawText();
+        return JSON.parse(text);
     }
     /**
      * Retrieves the raw request body as a Buffer.
      * @returns A promise that resolves to the raw request body.
      */
-    arrayBuffer() {
-        return this.request.arrayBuffer();
+    async arrayBuffer() {
+        if (this.#rawBodyBuffer !== undefined) {
+            return this.#rawBodyBuffer;
+        }
+        if (this.#bodyRead) {
+            if (this.#rawBodyText !== undefined) {
+                const buf = new TextEncoder().encode(this.#rawBodyText)
+                    .buffer;
+                this.#rawBodyBuffer = buf;
+                return buf;
+            }
+            return new ArrayBuffer(0);
+        }
+        const buf = await this.request.arrayBuffer();
+        this.#rawBodyBuffer = buf;
+        this.#bodyRead = true;
+        return buf;
+    }
+    async #readRawText() {
+        if (this.#rawBodyText !== undefined) {
+            return this.#rawBodyText;
+        }
+        if (this.#rawBodyBuffer !== undefined) {
+            const text = new TextDecoder().decode(this.#rawBodyBuffer);
+            this.#rawBodyText = text;
+            return text;
+        }
+        const text = await this.request.text();
+        this.#rawBodyText = text;
+        this.#bodyRead = true;
+        return text;
     }
     headers() {
         return Object.fromEntries(this.request.headers.entries());
@@ -111,7 +144,8 @@ export class PikkuFetchHTTPRequest {
         const contentType = this.header('content-type') || '';
         try {
             if (contentType.includes('application/json')) {
-                const parsed = await this.json();
+                const text = await this.#readRawText();
+                const parsed = text ? JSON.parse(text) : null;
                 body =
                     typeof parsed === 'object' &&
                         parsed !== null &&
@@ -120,15 +154,15 @@ export class PikkuFetchHTTPRequest {
                         : { data: parsed };
             }
             else if (contentType.includes('text/')) {
-                const text = await this.request.text();
+                const text = await this.#readRawText();
                 body = { data: text };
             }
             else if (contentType.includes('application/octet-stream')) {
-                const buffer = await this.request.arrayBuffer();
+                const buffer = await this.arrayBuffer();
                 body = { data: buffer };
             }
             else if (contentType === 'application/x-www-form-urlencoded') {
-                const text = await this.request.text();
+                const text = await this.#readRawText();
                 const params = new URLSearchParams(text);
                 let count = 0;
                 for (const _ of params) {

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.28",
+  "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/http/pikku-fetch-http-request.ts

@@ -14,6 +14,9 @@ export class PikkuFetchHTTPRequest<
   #cookies: Partial<Record<string, string>> | undefined
   #params: Partial<Record<string, string | string[]>> = {}
   #url: URL
+  #rawBodyText: string | undefined
+  #rawBodyBuffer: ArrayBuffer | undefined
+  #bodyRead = false
 
   constructor(private request: Request) {
     this.#url = new URL(request.url)
@@ -31,16 +34,47 @@ export class PikkuFetchHTTPRequest<
    * Retrieves the request body.
    * @returns A promise that resolves to the request body.
    */
-  public json(): Promise<In> {
-    return this.request.json()
+  public async json(): Promise<In> {
+    const text = await this.#readRawText()
+    return JSON.parse(text) as In
   }
 
   /**
    * Retrieves the raw request body as a Buffer.
    * @returns A promise that resolves to the raw request body.
    */
-  public arrayBuffer(): Promise<ArrayBuffer> {
-    return this.request.arrayBuffer()
+  public async arrayBuffer(): Promise<ArrayBuffer> {
+    if (this.#rawBodyBuffer !== undefined) {
+      return this.#rawBodyBuffer
+    }
+    if (this.#bodyRead) {
+      if (this.#rawBodyText !== undefined) {
+        const buf = new TextEncoder().encode(this.#rawBodyText)
+          .buffer as ArrayBuffer
+        this.#rawBodyBuffer = buf
+        return buf
+      }
+      return new ArrayBuffer(0)
+    }
+    const buf = await this.request.arrayBuffer()
+    this.#rawBodyBuffer = buf
+    this.#bodyRead = true
+    return buf
+  }
+
+  async #readRawText(): Promise<string> {
+    if (this.#rawBodyText !== undefined) {
+      return this.#rawBodyText
+    }
+    if (this.#rawBodyBuffer !== undefined) {
+      const text = new TextDecoder().decode(this.#rawBodyBuffer)
+      this.#rawBodyText = text
+      return text
+    }
+    const text = await this.request.text()
+    this.#rawBodyText = text
+    this.#bodyRead = true
+    return text
   }
 
   public headers(): Record<string, string> {
@@ -133,7 +167,8 @@ export class PikkuFetchHTTPRequest<
     const contentType = this.header('content-type') || ''
     try {
       if (contentType.includes('application/json')) {
-        const parsed = await this.json()
+        const text = await this.#readRawText()
+        const parsed = text ? JSON.parse(text) : null
         body =
           typeof parsed === 'object' &&
           parsed !== null &&
@@ -141,13 +176,13 @@ export class PikkuFetchHTTPRequest<
             ? parsed
             : { data: parsed }
       } else if (contentType.includes('text/')) {
-        const text = await this.request.text()
+        const text = await this.#readRawText()
         body = { data: text }
       } else if (contentType.includes('application/octet-stream')) {
-        const buffer = await this.request.arrayBuffer()
+        const buffer = await this.arrayBuffer()
         body = { data: buffer }
       } else if (contentType === 'application/x-www-form-urlencoded') {
-        const text = await this.request.text()
+        const text = await this.#readRawText()
         const params = new URLSearchParams(text)
         let count = 0
         for (const _ of params) {

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>