@pikku/core 0.12.66 → 0.12.69

package/CHANGELOG.md

@@ -1,3 +1,156 @@
+## 0.12.69
+
+### Patch Changes
+
+- 24252b8: Emit queue meta for workflow-only projects, so per-workflow orchestrator queues actually work.
+
+  Workflows synthesise their own `wf-orchestrator-*` / `wf-step-*` queue meta during
+  post-processing, and those entries have no declaring source file. The queue codegen
+  bailed early on `queueWorkers.files.size === 0`, so a project that uses workflows but
+  hand-declares no `wireQueueWorker` wrote no queue meta at all — and the generated
+  bootstrap therefore never imported it.
+
+  With `queue.meta` empty at runtime, `getOrchestratorQueueName()` never found a
+  per-workflow queue and every workflow silently fell back to the single shared
+  `pikku-workflow-orchestrator` queue. Nothing failed, but the isolation was gone: one
+  long-running workflow step head-of-line-blocked every other workflow queued behind it.
+
+  The codegen now gates on the meta alone. `@pikku/core` additionally warns at wiring
+  time when workflows are registered but no per-workflow orchestrator queue is present,
+  so this degradation can't recur silently.
+
+- e3d4454: Add job groups, so one shared queue can stay fair without splitting into one
+  queue per producer.
+
+  A job may now carry `group: { id, tier }`, and a worker may cap how many jobs
+  of any one group run at once via `groupConcurrency`. On pg-boss this maps to
+  `localGroupConcurrency`, which excludes at-capacity groups from the fetch query
+  itself, so a capped group costs nothing rather than being fetched and restored.
+  BullMQ declares it unsupported (groups are a BullMQ Pro feature) — being
+  push-based, it can simply use a queue per group at no polling cost.
+
+  Workflow services accept a `queueStrategy`. The default `'per-workflow'` is
+  unchanged: every workflow gets its own `wf-orchestrator-*` / `wf-step-*` queue,
+  which is also what lets serverless providers deploy one unit per workflow. The
+  new `'shared-groups'` routes every workflow through the shared
+  orchestrator/step-worker queues and isolates them by group instead, so a
+  monolith runs one set of pollers rather than one per workflow — on a
+  pull-based backend with dozens of workflows that is the difference between
+  hundreds of poll loops and twenty. It is for single-process runtimes only; a
+  per-unit serverless deploy still needs the per-workflow queues to route to its
+  units.
+
+## 0.12.68
+
+### Patch Changes
+
+- f11675f: Forward the parent run's `context` into delegated sub-agent invocations.
+
+  A supervisor agent's injected `context` (the "Current context" block holding the
+  authoritative identifiers — organizationId, project/stage ids) was appended only
+  to the supervisor's own instructions. When it delegated, the sub-agent tool's
+  input schema carries just `{ message, session }`, and `buildToolDefs` invoked the
+  sub-agent with `{ message, threadId, resourceId }` — dropping the context. The
+  sub-agent therefore never saw the real ids and depended on the model re-typing
+  them into the free-text `message`, which weaker models routinely botch, producing
+  schema-validation and permission rejections that the agent then retries — burning
+  steps and ballooning the transcript.
+
+  `buildToolDefs` now takes the parent `context` and forwards it (via the new
+  `buildSubAgentRunInput` helper) into both the streaming and non-streaming
+  sub-agent invocations, so a specialist inherits the same identifier block in its
+  instructions.
+
+## 0.12.67
+
+### Patch Changes
+
+- ae4f59a: Gate admin capabilities on scopes, and scaffold user management
+
+  Admin capabilities were gated on `user.role === 'admin'` — a single text column
+  meaning "can do everything". Impersonating a user, rebinding a shared
+  credential and reading the user directory are distinct capabilities that one
+  user can hold independently, so they are now scopes on an `admin` tree:
+
+  | Gate                                   | Scope                    |
+  | -------------------------------------- | ------------------------ |
+  | impersonation                          | `admin:impersonate`      |
+  | `credentialOAuth`'s `canLinkSingleton` | `admin:credentials:link` |
+  | reading the user directory             | `admin:users:list`       |
+  | creating a user out of band            | `admin:users:create`     |
+  | ban / unban                            | `admin:users:ban`        |
+  | delete a user                          | `admin:users:remove`     |
+  | revoke a user's sessions               | `admin:users:sessions`   |
+  | set a user's password                  | `admin:users:password`   |
+
+  Holding the bare `admin` scope satisfies all of them via pikku's existing
+  parent-grant rule, so it is a one-for-one replacement for the old role.
+
+  better-auth's `admin()` plugin is still what implements ban, delete,
+  session-revocation and set-password, so it stays. Its `user.role` column is no
+  longer something pikku grants: it is _projected_ from the scope store when a
+  session is built, and only from the scopes whose capability better-auth's own
+  endpoints gate on the caller's role. Someone granted `admin:users:list` can read
+  the directory — which goes straight to the auth adapter — without gaining the
+  power to ban, and revoking a scope demotes the role on the next sign-in. Scopes
+  remain the single source of truth.
+
+  New `scaffold.userAdmin` in `pikku.config.json` generates the whole set —
+  `pikkuAdminListUsers`, `pikkuAdminCreateUser`, `pikkuAdminSetUserBanned`,
+  `pikkuAdminRemoveUser`, `pikkuAdminRevokeUserSessions` and
+  `pikkuAdminSetUserPassword` — into your project. Listing or banning a user is
+  ordinary application behaviour and must not require installing the console.
+  Codegen fails with an actionable error if better-auth is wired without
+  `admin()`. The console's Users page calls these same functions, showing each
+  action only where the caller holds its scope.
+
+  Every scaffold now emits a directory named for its domain — `scaffold/admin/`,
+  `scaffold/rpc/`, `scaffold/agent/`, `scaffold/auth/`, `scaffold/console/`,
+  `scaffold/graph/`, `scaffold/realtime/`, `scaffold/scenarios/`,
+  `scaffold/webhook/`, `scaffold/workflow/` — holding its wiring file beside a
+  `*.schemas.gen.ts` sibling, and every generated payload is a zod schema instead
+  of a TypeScript generic. The schemas have to stand alone: the inspector reads a
+  zod schema by importing the module that declares it, which it cannot do for a
+  wiring file whose relative pikku-types import per-unit deploy codegen rewrites.
+
+  Resolving a schema by reference rather than by name also fixes the agent HTTP
+  surface. `agentCaller` and `agentStreamCaller` take the same payload but had to
+  repeat the type literal verbatim in each generic position, because the extractor
+  synthesised the schema name from the _function_ name and so recorded an
+  `inputSchemaName` with no schema behind it whenever the two shared a named
+  alias — every agent call through that alias failed with `MissingSchemaError`.
+  One `AgentCall` schema now backs both.
+
+  Where a payload's shape belongs to `@pikku/core` (`WorkflowRunStatus`,
+  `FunctionCoverageReport`, `StubCall[]`) the generated function carries no
+  `output` schema and the inspector infers it from the handler's return type;
+  re-declaring a core type in zod would be a second definition free to drift.
+
+  Upgrading rewrites the layout in place: codegen prunes the pre-directory copy of
+  each scaffold file before it inspects the source tree, since the old flat file
+  still wires the same routes and leaving it behind would wire everything twice.
+
+  `@pikku/core` gains `hasScopes(required, held)`, the non-throwing counterpart to
+  `verifyScopes`, and declares `auth` on `CoreSingletonServices` — the auth
+  instance the generated `pikkuServices` wrapper already injected but never typed.
+  A scope root declared twice (an addon and its host both contributing the same
+  `admin` tree) now flattens to one entry per id instead of emitting it twice.
+
+  BREAKING: there is no role fallback for the scope-gated capabilities. An app
+  that relied on the old default must register a `ScopeService` and grant `admin`
+  (or a narrower `admin:*` scope). Every gate fails closed and warns when no
+  `ScopeService` is registered. `delegatedAuth`'s `defaultRole`/`mapRole` now
+  grant a pikku role through the `ScopeService` instead of writing better-auth's
+  `role` column, and the `credentialOAuth` platform user no longer sets `banned`.
+
+  BREAKING: the console reads its user directory over the scaffolded
+  `pikkuAdminListUsers` RPC (gated on `admin:users:list`, backed by better-auth's
+  `$context.adapter`) instead of `client.admin.listUsers`, and
+  `UsersTableUser`/`UsersTableLabels` no longer carry `role` — there is no role
+  column to render. `@pikku/addon-console` no longer ships a `console:listUsers`
+  function: user management is not the console's job, so a host that wants the
+  Users page must enable `scaffold.userAdmin`.
+
 ## 0.12.66
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, RequireAtLeastOne, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, SerializedError, WireServices, } from './types/core.types.js';
+export type { AuthInstance, CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, ServerLifecycle, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuRawWire, PikkuWiringTypes, PostgresConfig, RequireAtLeastOne, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';
@@ -50,7 +50,7 @@ export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wirings/rpc/wire
 export type { PikkuPackageState } from './types/state.types.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
-export { verifyScopes } from './scopes.js';
+export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';
 export { addGlobalPermission, checkAuthPermissions } from './permissions.js';
-export { verifyScopes } from './scopes.js';
+export { hasScopes, verifyScopes } from './scopes.js';
 export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './utils.js';
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';

package/dist/scopes.d.ts

@@ -1,4 +1,18 @@
 import type { CoreUserSession } from './types/core.types.js';
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.

package/dist/scopes.js

@@ -31,6 +31,42 @@ const satisfyingGrants = (scope) => {
  * `admin`.
  */
 const holds = (held, scope) => satisfyingGrants(scope).some((grant) => held.has(grant));
+/**
+ * The first required scope a set of held grants does not satisfy, or `null`
+ * when every one is satisfied.
+ *
+ * Scopes are an AND gate: every entry in `required` must be satisfied. This is
+ * deliberately distinct from `permissions`, which OR together — a scope can
+ * only ever narrow access, so adding one to a function can never widen it.
+ *
+ * Fails closed: an absent `held` satisfies nothing.
+ */
+const firstUnsatisfied = (required, held) => {
+    if (!required || required.length === 0) {
+        return null;
+    }
+    const grants = new Set(held ?? []);
+    for (const scope of required) {
+        if (!holds(grants, scope)) {
+            return scope;
+        }
+    }
+    return null;
+};
+/**
+ * Whether a set of held grants satisfies every required scope.
+ *
+ * The non-throwing counterpart to {@link verifyScopes}, for deciding rather
+ * than enforcing — an authorization gate that falls back to another check when
+ * it is not satisfied, rather than rejecting the request outright.
+ *
+ * Fails closed: an absent or empty `held` satisfies nothing. An empty
+ * `required` is satisfied by anything.
+ *
+ * @param required - Scopes to check for. Empty means no gate.
+ * @param held - The grants held, e.g. `session.scopes`. May be undefined.
+ */
+export const hasScopes = (required, held) => firstUnsatisfied(required, held) === null;
 /**
  * Verifies that a session holds every required scope, throwing on the first
  * one it does not.
@@ -47,13 +83,8 @@ const holds = (held, scope) => satisfyingGrants(scope).some((grant) => held.has(
  * @throws {MissingScopeError} Naming the first unsatisfied scope.
  */
 export const verifyScopes = (required, session) => {
-    if (!required || required.length === 0) {
-        return;
-    }
-    const held = new Set(session?.scopes ?? []);
-    for (const scope of required) {
-        if (!holds(held, scope)) {
-            throw new MissingScopeError(scope);
-        }
+    const missing = firstUnsatisfied(required, session?.scopes);
+    if (missing !== null) {
+        throw new MissingScopeError(missing);
     }
 };

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,6 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
-import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
 /**
  * In-memory implementation of WorkflowService for inline-only execution
  *
@@ -17,7 +17,7 @@ import type { WorkflowPlannedStep, WorkflowRun, WorkflowRunService, WorkflowRunW
  * ```
  */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
-    constructor();
+    constructor(options?: WorkflowQueueOptions);
     private sleepTimers;
     private runs;
     private steps;

package/dist/services/in-memory-workflow-service.js

@@ -17,8 +17,8 @@ import { isExpectedError } from '../errors/error-handler.js';
  * ```
  */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
-    constructor() {
-        super({ wireQueues: false });
+    constructor(options = {}) {
+        super({ ...options, wireQueues: false });
     }
     sleepTimers = new Set();
     runs = new Map();

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

@@ -209,6 +209,21 @@ export interface CoreUserSession {
      */
     scopes?: string[];
 }
+/**
+ * The shape pikku needs from whatever auth library a project wires: something
+ * that can answer an HTTP request and expose its own endpoints as callable
+ * methods. Kept structural so core stays independent of any one auth package —
+ * `@pikku/better-auth`'s `BetterAuthInstance` is this type.
+ */
+export interface AuthInstance {
+    handler: (request: Request) => Promise<Response>;
+    api: Record<string, any>;
+    /**
+     * The auth library's resolved context. Optional because a hand-built instance
+     * may omit it.
+     */
+    $context?: Promise<any>;
+}
 /**
  * Interface for core singleton services provided by Pikku.
  */
@@ -280,6 +295,13 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      * better-auth's `mapSession`), never by the function runner.
      */
     scopeService?: ScopeService;
+    /**
+     * The project's resolved auth instance, built once by the factory an auth
+     * package registers (e.g. `pikkuBetterAuth`) and injected by the generated
+     * `pikkuServices` wrapper — which is why service factories are forbidden from
+     * returning it themselves. Absent when the project wires no auth.
+     */
+    auth?: () => Promise<AuthInstance>;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -168,7 +168,24 @@ export type ScopedChannel = AIStreamChannel & {
     }>;
 };
 export declare function createScopedChannel(parent: AIStreamChannel, agentName: string, session: string): ScopedChannel;
-export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise'): Promise<{
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export declare function buildSubAgentRunInput(message: string, threadId: string, resourceId: string, parentContext?: string): {
+    message: string;
+    threadId: string;
+    resourceId: string;
+    context?: string;
+};
+export declare function buildToolDefs(params: RunAIAgentParams, agentSessionMap: Map<string, string>, resourceId: string, agentName: string, packageName: string | null, streamContext?: StreamContext, aiMiddlewares?: PikkuAIMiddlewareHooks[], agentMode?: 'delegate' | 'supervise', parentContext?: string): Promise<{
     tools: AIAgentToolDef[];
     missingRpcs: string[];
 }>;

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -325,7 +325,29 @@ export function createScopedChannel(parent, agentName, session) {
         clearState: () => parent.clearState(),
     };
 }
-export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode) {
+/**
+ * Build the run input for a delegated sub-agent.
+ *
+ * `context` is the PARENT run's identifier block (the "Current context" text
+ * with organizationId, project/stage ids). A sub-agent's tool-call schema only
+ * carries { message, session }, so unless the sub-agent inherits the parent's
+ * context it never sees the authoritative ids — it depends on the model
+ * re-typing them into `message`, which weak models botch, causing
+ * schema/permission rejections and retry loops. Forwarding it here is the
+ * regression this seam guards.
+ */
+export function buildSubAgentRunInput(message, threadId, resourceId, parentContext) {
+    return { message, threadId, resourceId, context: parentContext };
+}
+export async function buildToolDefs(params, agentSessionMap, resourceId, agentName, packageName, streamContext, aiMiddlewares, agentMode, 
+// The parent run's `context` (the "Current context" identifier block). A
+// delegated sub-agent's tool-call input schema only carries { message,
+// session }, so without inheriting this the sub-agent never sees the
+// authoritative ids (organizationId, project/stage ids) — it depends on the
+// model re-typing them into `message`, which weak models botch, causing
+// schema/permission rejections and retry loops. Forward it so the sub-agent
+// gets the same context block in its instructions.
+parentContext) {
     const singletonServices = getSingletonServices();
     const tools = [];
     const missingRpcs = [];
@@ -505,7 +527,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     subChannel.send(event);
                                 },
                             };
-                        const resultText = await streamAIAgent(subAgentName, { message, threadId, resourceId }, effectiveChannel, params, agentSessionMap, streamContext.options);
+                        const resultText = await streamAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
                         if (subChannel.approvals.length > 0) {
                             return {
                                 [APPROVAL_REQUIRED]: true,
@@ -525,7 +547,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         return resultText;
                     }
                     // No stream context: sub-agent runs non-streaming
-                    const result = await runAIAgent(subAgentName, { message, threadId, resourceId }, params, agentSessionMap);
+                    const result = await runAIAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {
                         return {
@@ -731,7 +753,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const allMessages = [...contextMessages, ...messages, userMessage];
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
-    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
+    const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode, input.context);
     let instructions = await buildInstructions(resolvedName, packageName);
     if (input.context) {
         instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;

package/dist/wirings/queue/index.d.ts

@@ -1,4 +1,4 @@
-export type { ConfigValidationResult, CoreQueueWorker, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
+export type { ConfigValidationResult, CoreQueueWorker, GroupConcurrencyConfig, JobGroup, JobOptions, PikkuJobConfig, PikkuWorkerConfig, PikkuQueue, QueueJob, QueueJobStatus, QueueService, QueueWorkers, QueueWorkersMeta, } from './queue.types.js';
 export { wireQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, QueueJobDiscardedError, QueueJobFailedError, } from './queue-runner.js';
 export { validateWorkerConfig } from './validate-worker-config.js';
 export type { QueueConfigMapping } from './validate-worker-config.js';

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

@@ -30,6 +30,34 @@ export interface PikkuWorkerConfig {
     maxStalledCount?: number;
     /** Condition to start processor at instance creation */
     autorun?: boolean;
+    /**
+     * Cap how many jobs of any one group ({@link JobOptions.group}) may run at
+     * once, so a single group can't occupy the whole worker. Lets one shared
+     * queue stay fair across producers instead of splitting it into one queue
+     * per producer — which multiplies polling cost on pull-based backends.
+     * Must not exceed {@link batchSize}.
+     */
+    groupConcurrency?: number | GroupConcurrencyConfig;
+}
+/**
+ * Per-group concurrency limits, optionally varied by tier so slow groups can
+ * be allowed more (or fewer) slots than the default.
+ */
+export interface GroupConcurrencyConfig {
+    /** Limit applied to any group without a matching tier */
+    default: number;
+    /** Per-tier overrides, keyed by {@link JobGroup.tier} */
+    tiers?: Record<string, number>;
+}
+/**
+ * Fairness key for a job. Jobs sharing an `id` count against the same
+ * {@link PikkuWorkerConfig.groupConcurrency} limit.
+ */
+export interface JobGroup {
+    /** Group this job belongs to (e.g. a workflow name) */
+    id: string;
+    /** Optional tier selecting a per-tier limit */
+    tier?: string;
 }
 /**
  * Configuration for individual jobs - how jobs behave
@@ -106,6 +134,8 @@ export interface JobOptions {
     jobId?: string;
     /** Pikku user ID to propagate to the queue worker for credential resolution */
     pikkuUserId?: string;
+    /** Fairness key — counts against the worker's {@link PikkuWorkerConfig.groupConcurrency} */
+    group?: JobGroup;
 }
 /**
  * Queue provider interface for job publishing operations

package/dist/wirings/scope/validate-scope-definitions.d.ts

@@ -3,6 +3,14 @@ import type { FlatScope, ScopeDefinitions, ScopeDefinitionsMeta } from './scope.
  * Flattens declared scope trees into the full list of grantable scope ids,
  * depth-first. Every node is emitted, including intermediate ones.
  *
+ * Ids are unique. A root may legitimately be declared more than once — an addon
+ * and its host app both contributing the same `admin` tree, say — and
+ * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
+ * declarations are identical, so the second one is redundant rather than
+ * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
+ * object literal keyed by id (duplicates are a TypeScript error), and a
+ * ScopeService syncs one row per scope instead of re-writing the same one.
+ *
  * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
  * the declared set into its store.
  */

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

@@ -30,6 +30,14 @@ const flattenNodes = (nodes, prefix, out) => {
  * Flattens declared scope trees into the full list of grantable scope ids,
  * depth-first. Every node is emitted, including intermediate ones.
  *
+ * Ids are unique. A root may legitimately be declared more than once — an addon
+ * and its host app both contributing the same `admin` tree, say — and
+ * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
+ * declarations are identical, so the second one is redundant rather than
+ * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
+ * object literal keyed by id (duplicates are a TypeScript error), and a
+ * ScopeService syncs one row per scope instead of re-writing the same one.
+ *
  * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
  * the declared set into its store.
  */
@@ -39,7 +47,14 @@ export const flattenScopeDefinitions = (definitions) => {
         out.push({ id: def.name, description: def.description });
         flattenNodes(def.scopes, def.name, out);
     }
-    return out;
+    const seen = new Set();
+    return out.filter((scope) => {
+        if (seen.has(scope.id)) {
+            return false;
+        }
+        seen.add(scope.id);
+        return true;
+    });
 };
 /**
  * Validates declared scopes and keys them by name.

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

@@ -11,5 +11,5 @@ export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGr
 export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';

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

@@ -1,10 +1,10 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowQueueOptions, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import type { ScenarioActors } from '../../services/scenario-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
-import type { JobOptions } from '../queue/queue.types.js';
+import type { GroupConcurrencyConfig, JobGroup, JobOptions } from '../queue/queue.types.js';
 /**
  * Default number of retries for a workflow step when none is specified. The
  * workflow — not the queue — owns retry policy; a step inherits this unless it
@@ -98,10 +98,13 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runActors;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
+    protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
+    protected readonly queueConcurrency: number;
+    protected readonly queueGroupConcurrency: number | GroupConcurrencyConfig;
     constructor(options?: {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
-    });
+    } & WorkflowQueueOptions);
     private safeMirror;
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
@@ -519,4 +522,14 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     protected getOrchestratorQueueName(workflowName?: string): string;
     protected getStepWorkerQueueName(rpcName?: string): string;
+    /**
+     * Fairness key for a job on a shared queue. Under `'per-workflow'` the queue
+     * name already isolates workflows, so no group is needed — returning one
+     * anyway would cap a workflow inside its own dedicated queue.
+     *
+     * The tier repeats the id so a workflow can be given its own limit purely
+     * from config, with no per-workflow wiring; an unmatched tier falls back to
+     * the default limit.
+     */
+    protected getJobGroup(id?: string): JobGroup | undefined;
 }