@pikku/core 0.12.86 → 0.12.89

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

@@ -105,12 +105,12 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged — and, because it does not opt in, gains no re-dispatches
-     * either. A store must have an atomic `withStepLock` before overriding this,
-     * or no concurrency for one to exclude: the relay makes duplicate dispatch
-     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-     * duplicate from becoming a second execution. `kysely-postgres` and
-     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     * either. A store must have an atomic `claimStepForExecution` before
+     * overriding this, or no concurrency for one to exclude: the relay makes
+     * duplicate dispatch routine, and the claim is what keeps a duplicate from
+     * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+     * status-guarded claim, `in-memory` on being inline and single-process;
+     * `mongodb` still qualifies on neither.
      */
     protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
         runId: string;
@@ -176,6 +176,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
     executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: PikkuRPC): Promise<void>;
+    /**
+     * Take sole ownership of a step before it runs, returning the state to run
+     * under — or `null` when another dispatch already owns it.
+     *
+     * Dispatch is at-least-once by design: the relay re-dispatches steps it
+     * believes were dropped, and a queue can redeliver a job it already handed
+     * out. This is the one place that keeps a duplicate dispatch from becoming a
+     * second execution of a side-effecting step, so it is only as strong as the
+     * exclusion it is built on — and `withStepLock` excludes nothing unless the
+     * store backs it with a real primitive. A store able to express the decision
+     * as one conditional write should override this rather than reach for a lock,
+     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
     private executeWorkflowStepInner;
     orchestrateWorkflow(runId: string, rpcService: PikkuRPC): Promise<void>;
     private verifyQueueService;

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

@@ -8,14 +8,15 @@ import { RPCNotFoundError } from '../rpc/rpc-runner.js';
 import { deriveInvocationId } from './workflow-invocation-id.js';
 import { approvalDeciderFrom } from './workflow-approval-policy.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
-import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, } from './workflow-constants.js';
-import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepFunctionMismatchError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
+import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, isRunSettled, } from './workflow-constants.js';
+import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
 import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
 import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
 import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
 import { auditApprovalDecision } from './workflow-approval-audit.js';
 import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js';
+import { claimStepByReadThenWrite } from './workflow-step-claim.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
     runExtension;
@@ -261,12 +262,12 @@ export class PikkuWorkflowService {
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged — and, because it does not opt in, gains no re-dispatches
-     * either. A store must have an atomic `withStepLock` before overriding this,
-     * or no concurrency for one to exclude: the relay makes duplicate dispatch
-     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-     * duplicate from becoming a second execution. `kysely-postgres` and
-     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     * either. A store must have an atomic `claimStepForExecution` before
+     * overriding this, or no concurrency for one to exclude: the relay makes
+     * duplicate dispatch routine, and the claim is what keeps a duplicate from
+     * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+     * status-guarded claim, `in-memory` on being inline and single-process;
+     * `mongodb` still qualifies on neither.
      */
     async findUndispatchedSteps(_before, _limit) {
         return [];
@@ -283,7 +284,7 @@ export class PikkuWorkflowService {
      * scheduled task at whatever interval suits the workload.
      */
     async recoverStalledRuns(options) {
-        return sweepStalledRuns((before, limit) => this.findStalledRunIds(before, limit), options, this.sweepDeps);
+        return sweepStalledRuns((before, limit) => this.findStalledRunIds(before, limit), this.redispatchBackoff, options, this.sweepDeps);
     }
     /**
      * Re-drive steps whose dispatch was lost. Not self-starting — call it from a
@@ -545,6 +546,8 @@ export class PikkuWorkflowService {
         if (!run) {
             throw new WorkflowRunNotFoundError(runId);
         }
+        if (isRunSettled(run.status))
+            return;
         const resolved = resolveWorkflowMeta(run.workflow);
         const workflowMeta = resolved?.meta;
         const pkgName = resolved?.packageName ?? null;
@@ -697,25 +700,24 @@ export class PikkuWorkflowService {
             this.exitExecution(runId);
         }
     }
+    /**
+     * Take sole ownership of a step before it runs, returning the state to run
+     * under — or `null` when another dispatch already owns it.
+     *
+     * Dispatch is at-least-once by design: the relay re-dispatches steps it
+     * believes were dropped, and a queue can redeliver a job it already handed
+     * out. This is the one place that keeps a duplicate dispatch from becoming a
+     * second execution of a side-effecting step, so it is only as strong as the
+     * exclusion it is built on — and `withStepLock` excludes nothing unless the
+     * store backs it with a real primitive. A store able to express the decision
+     * as one conditional write should override this rather than reach for a lock,
+     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     */
+    async claimStepForExecution(runId, stepName, rpcName) {
+        return this.withStepLock(runId, stepName, () => claimStepByReadThenWrite(this, runId, stepName, rpcName));
+    }
     async executeWorkflowStepInner(runId, stepName, rpcName, data, rpcService) {
-        const claimed = await this.withStepLock(runId, stepName, async () => {
-            const stepState = await this.getStepState(runId, stepName);
-            // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
-            if (stepState.rpcName !== undefined &&
-                stepState.rpcName !== (rpcName ?? null)) {
-                throw new WorkflowStepFunctionMismatchError(runId, stepName);
-            }
-            if (stepState.status === 'succeeded' || stepState.status === 'running') {
-                return null;
-            }
-            if (stepState.status === 'failed') {
-                return this.createRetryAttempt(stepState.stepId, 'running');
-            }
-            if (stepState.status === 'pending' || stepState.status === 'scheduled') {
-                await this.setStepRunning(stepState.stepId);
-            }
-            return stepState;
-        });
+        const claimed = await this.claimStepForExecution(runId, stepName, rpcName);
         if (!claimed) {
             return;
         }

package/dist/wirings/workflow/workflow-constants.d.ts

@@ -3,6 +3,23 @@ export declare const DEFAULT_STEP_RETRIES = 5;
 export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
 /** Statuses a run cannot leave at all. */
 export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+/**
+ * True for a run that will never move again, whatever arrives for it.
+ *
+ * Worth checking before doing anything with an orchestrator message, because
+ * such a message is routine rather than exceptional: the queue is
+ * at-least-once, the relay re-dispatches on purpose, and a run can settle
+ * while a message for it is still in flight. Replaying one is not free —
+ * `runWorkflowJob` takes the run lock and re-enters the workflow body, and a
+ * body re-entered after its run failed can park on a wait that nothing will
+ * ever satisfy, holding the lock and the connection under it until something
+ * external gives up. Every leaked advisory lock seen in production traced back
+ * to that: a granted lock, an idle session, and a run already `failed`.
+ *
+ * Note `suspended` is deliberately absent. It ends a run's *current* pass but
+ * not the run, which resumes when its approval or signal arrives.
+ */
+export declare const isRunSettled: (status: string) => boolean;
 export declare const WORKFLOW_POLL_MIN_MS = 10;
 export declare const WORKFLOW_POLL_FACTOR = 1.6;
 export declare const WORKFLOW_CHILD_POLL_MAX_MS = 500;

package/dist/wirings/workflow/workflow-constants.js

@@ -12,6 +12,23 @@ export const WORKFLOW_TERMINAL_STATES = new Set([
     'failed',
     'cancelled',
 ]);
+/**
+ * True for a run that will never move again, whatever arrives for it.
+ *
+ * Worth checking before doing anything with an orchestrator message, because
+ * such a message is routine rather than exceptional: the queue is
+ * at-least-once, the relay re-dispatches on purpose, and a run can settle
+ * while a message for it is still in flight. Replaying one is not free —
+ * `runWorkflowJob` takes the run lock and re-enters the workflow body, and a
+ * body re-entered after its run failed can park on a wait that nothing will
+ * ever satisfy, holding the lock and the connection under it until something
+ * external gives up. Every leaked advisory lock seen in production traced back
+ * to that: a granted lock, an idle session, and a run already `failed`.
+ *
+ * Note `suspended` is deliberately absent. It ends a run's *current* pass but
+ * not the run, which resumes when its approval or signal arrives.
+ */
+export const isRunSettled = (status) => WORKFLOW_TERMINAL_STATES.has(status);
 export const WORKFLOW_POLL_MIN_MS = 10;
 export const WORKFLOW_POLL_FACTOR = 1.6;
 export const WORKFLOW_CHILD_POLL_MAX_MS = 500;

package/dist/wirings/workflow/workflow-recovery.d.ts

@@ -7,6 +7,15 @@ import type { Logger } from '../../services/logger.js';
  * owed a job, so holding off a single step while resuming its run would
  * suppress nothing.
  *
+ * For the same reason one instance is shared by every sweep rather than kept
+ * per sweep. The record is of the action, not of the signal that prompted it:
+ * a stalled run and an undispatched step are different observations, but both
+ * are answered by the one orchestrator message, so a run the relay re-drove a
+ * moment ago gains nothing from the stalled sweep re-driving it again. Sharing
+ * is what makes the guarantee a message-per-run-per-window instead of one per
+ * sweep, and no recovery is lost by it: whichever sweep gets there first
+ * performs the identical re-drive, and the cap keeps the delay at 10m.
+ *
  * Losing this on restart costs extra dispatches, never correctness.
  */
 export declare class RedispatchBackoff {
@@ -34,8 +43,16 @@ type SweepDeps = {
  * actually stuck costs an orchestration pass and changes nothing. That
  * idempotence is what makes an idle-time heuristic safe here; a run that is
  * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ *
+ * Idempotent is not free, though: a run stays stalled until something clears
+ * the reason it stalled, so an unconditional sweep re-queues the same runs on
+ * every tick forever. That is how a handful of wedged runs became a queue of
+ * thousands that could not drain — each pass added work the previous pass had
+ * not finished. The same per-run backoff the relay uses bounds it: a run is
+ * re-driven, then held off for a doubling delay, so a sweep costs at most one
+ * message per run per window rather than one per run per tick.
  */
-export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, options: {
+export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, backoff: RedispatchBackoff, options: {
     stalledAfterMs?: number;
     limit?: number;
 } | undefined, deps: SweepDeps) => Promise<{

package/dist/wirings/workflow/workflow-recovery.js

@@ -7,6 +7,15 @@ import { DEFAULT_STALLED_RUN_LIMIT, DEFAULT_STALLED_RUN_MS, DEFAULT_UNDISPATCHED
  * owed a job, so holding off a single step while resuming its run would
  * suppress nothing.
  *
+ * For the same reason one instance is shared by every sweep rather than kept
+ * per sweep. The record is of the action, not of the signal that prompted it:
+ * a stalled run and an undispatched step are different observations, but both
+ * are answered by the one orchestrator message, so a run the relay re-drove a
+ * moment ago gains nothing from the stalled sweep re-driving it again. Sharing
+ * is what makes the guarantee a message-per-run-per-window instead of one per
+ * sweep, and no recovery is lost by it: whichever sweep gets there first
+ * performs the identical re-drive, and the cap keeps the delay at 10m.
+ *
  * Losing this on restart costs extra dispatches, never correctness.
  */
 export class RedispatchBackoff {
@@ -61,10 +70,29 @@ const resumeEach = async (runIds, { resume, logger }, failure) => {
  * actually stuck costs an orchestration pass and changes nothing. That
  * idempotence is what makes an idle-time heuristic safe here; a run that is
  * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ *
+ * Idempotent is not free, though: a run stays stalled until something clears
+ * the reason it stalled, so an unconditional sweep re-queues the same runs on
+ * every tick forever. That is how a handful of wedged runs became a queue of
+ * thousands that could not drain — each pass added work the previous pass had
+ * not finished. The same per-run backoff the relay uses bounds it: a run is
+ * re-driven, then held off for a doubling delay, so a sweep costs at most one
+ * message per run per window rather than one per run per tick.
  */
-export const sweepStalledRuns = async (findStalledRunIds, options, deps) => {
+export const sweepStalledRuns = async (findStalledRunIds, backoff, options, deps) => {
     const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
-    const runIds = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    const found = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    const now = Date.now();
+    const runIds = [];
+    for (const runId of found) {
+        if (!backoff.isEligible(runId, now))
+            continue;
+        // Noted before the resume, not after: a run whose resume throws is exactly
+        // the run most likely to still be here next tick, and re-driving it every
+        // tick is the amplification this backoff exists to stop.
+        backoff.note(runId, now);
+        runIds.push(runId);
+    }
     return {
         resumed: await resumeEach(runIds, deps, (runId, detail) => `Failed to resume stalled workflow run ${runId}: ${detail}`),
     };

package/dist/wirings/workflow/workflow-step-claim.d.ts

@@ -0,0 +1,16 @@
+import type { StepState } from './workflow.types.js';
+/** What claiming a step needs from the workflow service. */
+export type StepClaimStore = {
+    getStepState(runId: string, stepName: string): Promise<StepState>;
+    setStepRunning(stepId: string): Promise<void>;
+    createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+};
+/**
+ * Decide whether this dispatch owns the step, by reading its state and then
+ * writing it — which only excludes a concurrent dispatch when the caller holds
+ * a lock that genuinely excludes one.
+ *
+ * A store that can express the whole decision as a single conditional write
+ * should do that instead of calling this.
+ */
+export declare const claimStepByReadThenWrite: (store: StepClaimStore, runId: string, stepName: string, rpcName: string) => Promise<StepState | null>;

package/dist/wirings/workflow/workflow-step-claim.js

@@ -0,0 +1,27 @@
+import { WorkflowStepFunctionMismatchError } from './workflow-errors.js';
+/**
+ * Decide whether this dispatch owns the step, by reading its state and then
+ * writing it — which only excludes a concurrent dispatch when the caller holds
+ * a lock that genuinely excludes one.
+ *
+ * A store that can express the whole decision as a single conditional write
+ * should do that instead of calling this.
+ */
+export const claimStepByReadThenWrite = async (store, runId, stepName, rpcName) => {
+    const stepState = await store.getStepState(runId, stepName);
+    // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
+    if (stepState.rpcName !== undefined &&
+        stepState.rpcName !== (rpcName ?? null)) {
+        throw new WorkflowStepFunctionMismatchError(runId, stepName);
+    }
+    if (stepState.status === 'succeeded' || stepState.status === 'running') {
+        return null;
+    }
+    if (stepState.status === 'failed') {
+        return store.createRetryAttempt(stepState.stepId, 'running');
+    }
+    if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+        await store.setStepRunning(stepState.stepId);
+    }
+    return stepState;
+};

package/knowledge/decisions/security/a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md

@@ -0,0 +1,47 @@
+---
+type: decision
+title: A scaffold flag says a surface exists, not who may call it
+description: scaffold.<feature> is boolean | { path } — the auth field is gone, because the function runner already enforces each generated function's own auth, wiring, scopes and addon
+tags: config, authorization, codegen, scaffold
+---
+
+# A scaffold flag says a surface exists, not who may call it
+
+`scaffold.<feature>` carried an `auth` field, defaulting closed — see
+[[scaffold-features-are-authenticated-unless-opted-out]], which this supersedes.
+The field is gone. `PikkuScaffoldFeature` is now `boolean | { path?: string }`:
+whether the surface is generated, and where the file goes.
+
+The field was a second gate in front of one that already runs. `resolveSession`
+in `packages/core/src/function/function-runner.ts` throws `ForbiddenError` for a
+`pikkuFunc` with no session, unconditionally; a `pikkuSessionlessFunc` requires
+one when its own `auth: true` says so, when its wiring says so, or when
+`resolveAddonAuth` does. That is where authentication is decided, per function,
+by whoever wrote it. A config flag three directories away could only be coarser
+than that, and being coarser was the whole problem the earlier decision was
+trying to work around by defaulting it closed.
+
+So the generated dispatchers — public RPC, public agent, workflow routes and the
+events channel — emit a fixed `auth: false` on every function and wiring they
+write. That is not the scaffold declaring the surface public. It is the
+dispatcher declining to gate, because it does not know what it is forwarding to:
+`rpcCaller` hands whatever name it was given to `rpc.exposed`, and the function
+that resolves there is the one that answers for itself. Omitting the field would
+not have been neutral — a wiring with no `auth` requires a session — so the
+wrapper would reject the call before the gate that decides ever ran, which is a
+harder gate than the config field it replaced, applied by the layer least
+qualified to apply it.
+
+The scoped admin surfaces do not emit it. `userAdmin` and `virtualUser` generate
+`pikkuFunc` with `scopes: ['admin:users:...']` — session-required by
+construction, and the function that decides rather than a wrapper in front of
+one. `auth: false` there is refused by `runPikkuFunc` with a warning telling you
+to use `pikkuSessionlessFunc` instead, and `auth: true` would only restate the
+type.
+
+`pikku enable <feature>` lost its `--noAuth` flag with the field it wrote.
+
+**What this rules out:** reading a scaffold flag as an authorization decision;
+gating a surface in the config instead of on the function that answers it; and
+letting a generated dispatcher inherit the default `auth: true`, which reads as
+"undecided" and behaves as "denied".

package/knowledge/decisions/security/index.md

@@ -50,7 +50,8 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [Queue job identities are signed at enqueue](queue-job-identities-are-signed-at-enqueue.md) — A job's pikkuUserId is an HMAC claim bound to the queue and payload; an unverifiable claim is dropped, never trusted
 - [Queue jobs carry the producer's pikku user id](queue-jobs-carry-the-producers-pikku-user-id.md) — A job's pikkuUserId is trusted as identity by the worker, so enqueue rights are effectively act-as-user rights
 - [Remote addon tokens are client credentials, not mesh trust](remote-addon-tokens-are-client-credentials-not-mesh-trust.md) — wireRemoteAddon authenticates as a client to a hosted library and fails closed on an empty token; it never uses PIKKU_REMOTE_SECRET
-- [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — scaffold.<feature> became boolean | { auth, path }, where true means authenticated — going public requires typing { auth: false }, and the legacy 'auth' | 'no-auth' strings are refused rather than coerced
+- [A scaffold flag says a surface exists, not who may call it](a-scaffold-flag-says-a-surface-exists-not-who-may-call-it.md) — scaffold.<feature> is boolean | { path }; the auth field is gone because the function runner already enforces each generated function's own auth, wiring, scopes and addon
+- [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — SUPERSEDED; retains why the legacy 'auth' | 'no-auth' strings are refused rather than coerced
 - [Scenario-step functions are never externally invocable over RPC](scenario-step-functions-are-never-externally-invocable.md) — rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
 - [Scope resolution happens at the session boundary and scope sync never deletes](scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md) — ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
 - [Self-authentication is declared, not detected](self-authentication-is-declared-not-detected.md) — A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it

package/knowledge/decisions/security/scaffold-features-are-authenticated-unless-opted-out.md

@@ -7,6 +7,12 @@ tags: config, authorization, codegen, scaffold
 
 # A scaffolded surface is authenticated unless the config opts out in writing
 
+**Superseded by
+[[a-scaffold-flag-says-a-surface-exists-not-who-may-call-it]]**: the `auth`
+field is gone entirely, because the function runner already enforces each
+generated function's own auth. The reasoning below still explains why the
+legacy `'auth' | 'no-auth'` strings are refused rather than coerced.
+
 `scaffold.<feature>` was `'auth' | 'no-auth' | false`. Two things were wrong
 with it, and they compounded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.86",
+  "version": "0.12.89",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/dev/hot-reload.ts

@@ -11,7 +11,7 @@ import type { Logger } from '../services/logger.js'
 import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
 import { createModuleRunner } from './module-runner.js'
 
-export * from './reload-meta.js'
+export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
 interface PikkuDevReloaderOptions {
   srcDirectories: string[]

package/src/types/core.types.ts

@@ -240,7 +240,7 @@ export type PikkuWire<
    * sets it; services that log fall back to the singleton logger.
    */
   logger: Logger
-  /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
+  /** Trace ID for distributed tracing — propagated across remote RPC calls via the x-request-id header */
   traceId: string
   functionId: string
   addonNamespace: string

package/src/types/index.ts

@@ -1,2 +1,25 @@
-export * from './core.types.js'
+export type {
+  AuthInstance,
+  CommonWireMeta,
+  CoreConfig,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateConfig,
+  CreateSingletonServices,
+  CreateWireServices,
+  GetCredential,
+  PikkuWire,
+  PikkuWiringTypes,
+  PostgresConfig,
+  SecretlessServices,
+  SecurityAuditIssue,
+  SecurityAuditReport,
+  SecurityAuditSummary,
+  SecurityAuditUpdate,
+  SecuritySeverity,
+  SecurityUpdateLevel,
+  ServerLifecycle,
+  WireServices,
+} from './core.types.js'
 export type * from './state.types.js'

package/src/wirings/agent/agent-memory.test.ts

@@ -74,6 +74,72 @@ describe('agent-memory', () => {
     })
   })
 
+  test('deepMergeWorkingMemory replaces an array re-emitted in full', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [{ id: 1 }, { id: 2 }], other: 'kept' },
+      { steps: [{ id: 1 }, { id: 2 }, { id: 3 }] }
+    )
+
+    assert.deepEqual(result, {
+      steps: [{ id: 1 }, { id: 2 }, { id: 3 }],
+      other: 'kept',
+    })
+  })
+
+  test('deepMergeWorkingMemory replaces rather than appends a partial array', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [{ id: 1 }, { id: 2 }] },
+      { steps: [{ id: 3 }] }
+    )
+
+    assert.deepEqual(result, { steps: [{ id: 3 }] })
+  })
+
+  test('deepMergeWorkingMemory clears an array field set to null', () => {
+    const result = deepMergeWorkingMemory(
+      { steps: [1, 2, 3], city: 'Berlin' },
+      {
+        steps: null,
+      }
+    )
+
+    assert.deepEqual(result, { city: 'Berlin' })
+  })
+
+  test('deepMergeWorkingMemory replaces arrays nested inside merged objects', () => {
+    const result = deepMergeWorkingMemory(
+      {
+        profile: {
+          name: 'Yasser',
+          tags: ['a', 'b'],
+        },
+      },
+      {
+        profile: {
+          tags: ['c'],
+        },
+      }
+    )
+
+    assert.deepEqual(result, {
+      profile: {
+        name: 'Yasser',
+        tags: ['c'],
+      },
+    })
+  })
+
+  test('deepMergeWorkingMemory replaces across array and object shape changes', () => {
+    assert.deepEqual(
+      deepMergeWorkingMemory({ value: { a: 1 } }, { value: [1, 2] }),
+      { value: [1, 2] }
+    )
+    assert.deepEqual(
+      deepMergeWorkingMemory({ value: [1, 2] }, { value: { a: 1 } }),
+      { value: { a: 1 } }
+    )
+  })
+
   test('deepMergeWorkingMemory ignores prototype-polluting keys', () => {
     const before = ({} as any).isAdmin
     deepMergeWorkingMemory(
@@ -107,6 +173,13 @@ describe('agent-memory', () => {
     assert.match(prompt, /<working_memory>/)
   })
 
+  test('buildWorkingMemoryPrompt tells the model arrays are replaced whole', () => {
+    const prompt = buildWorkingMemoryPrompt({ steps: [1] })
+
+    assert.match(prompt, /Arrays are replaced, not merged/)
+    assert.match(prompt, /repeat every item you want to keep/)
+  })
+
   test('buildWorkingMemoryPrompt marks empty memory explicitly', () => {
     const prompt = buildWorkingMemoryPrompt(null)
     assert.match(prompt, /Current working memory: \(empty\)/)

package/src/wirings/agent/agent-memory.ts

@@ -39,6 +39,17 @@ export function isWorkingMemoryEnabled(
   return !!memoryConfig?.workingMemory && !!storage
 }
 
+/**
+ * Merges a model-emitted working memory update into the stored state.
+ *
+ * Objects merge key by key, and `null` deletes a key. Arrays are replaced
+ * wholesale — deliberately, not as a side effect of the object guard below.
+ * The full state is echoed back to the model every turn by
+ * {@link buildWorkingMemoryPrompt}, so it can always re-emit an array in full,
+ * and appending instead would duplicate every item each time it did.
+ * `buildWorkingMemoryPrompt` states this contract to the model; the two must
+ * stay in agreement.
+ */
 export function deepMergeWorkingMemory(
   existing: Record<string, unknown>,
   updates: Record<string, unknown>
@@ -51,9 +62,10 @@ export function deepMergeWorkingMemory(
     const value = updates[key]
     if (value === null) {
       delete result[key]
+    } else if (Array.isArray(value)) {
+      result[key] = value
     } else if (
       typeof value === 'object' &&
-      !Array.isArray(value) &&
       typeof result[key] === 'object' &&
       result[key] !== null &&
       !Array.isArray(result[key])
@@ -100,7 +112,9 @@ export function buildWorkingMemoryPrompt(
     'When you learn new information, output a partial JSON update in <working_memory> tags. ' +
       'Only include durable facts you have actually derived or the user has confirmed. ' +
       'Do not output templates, placeholders, or narration. ' +
-      'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it.'
+      'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it. ' +
+      'Arrays are replaced, not merged: to change one, repeat every item you want to keep alongside the new ones, ' +
+      'because any item you leave out is deleted.'
   )
 
   return parts.join('\n\n')

package/src/wirings/agent/agent-middleware.types.test.ts

@@ -0,0 +1,41 @@
+// Type-checked via tsconfig.type-tests.json; no runtime assertions.
+
+import { pikkuAgentMiddleware } from '../../middleware/middleware-factories.js'
+import type { PikkuAgentMiddlewareHooks } from './agent.types.js'
+
+const _singletonServicesCompile = pikkuAgentMiddleware<{ count: number }>({
+  modifyInput: async ({ logger }, { messages, instructions }) => {
+    logger.info(`agent input: ${messages.length} messages`)
+    return { messages, instructions }
+  },
+  modifyOutputStream: async ({ logger }, { event, state }) => {
+    state.count = (state.count ?? 0) + 1
+    logger.info(`event: ${event.type}`)
+    return event
+  },
+  afterStep: async ({ variables }, { stepNumber }) => {
+    variables.get(`STEP_${stepNumber}`)
+  },
+  onError: async ({ logger }, { error }) => {
+    logger.error(error.message)
+  },
+})
+void _singletonServicesCompile
+
+const _wireServiceIsNotAvailable: PikkuAgentMiddlewareHooks = {
+  // @ts-expect-error — `http` is a wire service, and an agent run has no wire
+  modifyInput: async ({ http }, { messages, instructions }) => {
+    void http
+    return { messages, instructions }
+  },
+}
+void _wireServiceIsNotAvailable
+
+const _wireServiceIsNotAvailableToTheFactory = pikkuAgentMiddleware({
+  // @ts-expect-error — `channel` is a wire service, and an agent run has no wire
+  afterToolCall: async ({ channel }, { result }) => {
+    void channel
+    return { result }
+  },
+})
+void _wireServiceIsNotAvailableToTheFactory