@pikku/inspector 0.12.55 → 0.12.58

package/src/add/add-scenario-step.test.ts

@@ -243,6 +243,25 @@ describe('pikkuScenarioStep', () => {
     }
   })
 
+  test('a graded agent run is a witness too', async () => {
+    // An agent's answer cannot be matched against a fixed string, so a scenario
+    // that grades one is asserting — even though `expectScore`, like the other
+    // helpers, is an inline step that reaches PKU680 as nothing at all.
+    const { criticals, cleanup } = await run([
+      "const answer = await scenario.when('asks for a summary', 'runAssistant', { prompt: 'hi' }, { actor: actors.shopper })",
+      "await scenario.expectScore('answered briefly', answer.runId, 'brevity', { atLeast: 0.8 })",
+    ])
+    try {
+      assert.equal(
+        criticals.filter((c) => c.code === 'PKU680').length,
+        0,
+        `got: ${JSON.stringify(criticals)}`
+      )
+    } finally {
+      await cleanup()
+    }
+  })
+
   test('an expectation parked in an uncalled helper is still no assertion', async () => {
     const { criticals, cleanup } = await run([
       'const neverCalled = async () => {',

package/src/add/add-wire-addon.test.ts

@@ -61,9 +61,52 @@ describe('addWireAddon', () => {
       secretOverrides: undefined,
       variableOverrides: undefined,
       credentialOverrides: undefined,
+      globalSecrets: undefined,
+      globalCredentials: undefined,
     })
   })
 
+  test('captures the reason an addon was exempted from credential scoping', () => {
+    const declarations = inspect(`
+      wireAddon({
+        name: 'console',
+        package: '@pikku/addon-console',
+        globalCredentials: 'links credentials an operator names at runtime',
+      })
+    `)
+
+    assert.equal(
+      declarations.get('console').globalCredentials,
+      'links credentials an operator names at runtime'
+    )
+  })
+
+  test('captures the reason an addon was exempted from secret scoping', () => {
+    const declarations = inspect(`
+      wireAddon({
+        name: 'console',
+        package: '@pikku/addon-console',
+        globalSecrets: 'administers secrets an operator names at runtime',
+      })
+    `)
+
+    assert.equal(
+      declarations.get('console').globalSecrets,
+      'administers secrets an operator names at runtime'
+    )
+  })
+
+  test('a globalSecrets reason that is not a literal still reports the grant', () => {
+    // Unlike `scopes`, dropping this would under-report: the grant is real at
+    // runtime whatever the reason evaluates to. The source text is recorded so
+    // the manifest names the addon and points at where the reason comes from.
+    const declarations = inspect(`
+      wireAddon({ name: 'console', package: '@x/y', globalSecrets: REASON })
+    `)
+
+    assert.equal(declarations.get('console').globalSecrets, 'REASON')
+  })
+
   test('leaves the gates undefined when none are declared', () => {
     const declarations = inspect(`
       wireAddon({ name: 'console', package: '@pikku/addon-console' })

package/src/add/add-wire-addon.ts

@@ -60,6 +60,8 @@ export function addWireAddon(
   let secretOverrides: Record<string, string> | undefined
   let variableOverrides: Record<string, string> | undefined
   let credentialOverrides: Record<string, string> | undefined
+  let globalSecrets: string | undefined
+  let globalCredentials: string | undefined
 
   for (const prop of firstArg.properties) {
     if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
@@ -102,6 +104,16 @@ export function addWireAddon(
       ts.isObjectLiteralExpression(prop.initializer)
     ) {
       credentialOverrides = parseStringRecord(prop.initializer)
+    } else if (key === 'globalSecrets') {
+      // The grant is real at runtime whatever the reason evaluates to, so a
+      // non-literal is recorded as its source text rather than dropped.
+      globalSecrets = ts.isStringLiteral(prop.initializer)
+        ? prop.initializer.text
+        : prop.initializer.getText()
+    } else if (key === 'globalCredentials') {
+      globalCredentials = ts.isStringLiteral(prop.initializer)
+        ? prop.initializer.text
+        : prop.initializer.getText()
     }
   }
 
@@ -118,6 +130,8 @@ export function addWireAddon(
     secretOverrides,
     variableOverrides,
     credentialOverrides,
+    globalSecrets,
+    globalCredentials,
   })
   state.rpc.usedAddons.add(name)
   state.rpc.wireAddonFiles.add(node.getSourceFile().fileName)

package/src/add/scenario-instrumentation.ts

@@ -13,12 +13,18 @@
  * `pikku dev` registers the implementations itself. Ignoring by name (rather
  * than deleting the scaffold and requiring every project to regenerate) is what
  * keeps an existing project's checked-in `scenarios.gen.ts` from deploying.
+ *
+ * `pikkuScenarioGradeRun` was never scaffolded — it arrived after the split —
+ * but it belongs here for the same reason: grading a run on demand, ignoring the
+ * sample rate that governs live traffic, is a thing you do to a development
+ * server, and the name is reserved so an application cannot claim it.
  */
 export const SCENARIO_INSTRUMENTATION_FUNCTIONS = [
   'pikkuScenarioTakeLiveCoverage',
   'pikkuScenarioResetLiveCoverage',
   'pikkuScenarioResetStubs',
   'pikkuScenarioGetStubCalls',
+  'pikkuScenarioGradeRun',
 ] as const
 
 export type ScenarioInstrumentationFunction =

package/src/error-codes.ts

@@ -45,6 +45,7 @@ export enum ErrorCode {
 
   // Configuration errors
   SCHEMA_GENERATION_ERROR = 'PKU456',
+  SCHEMA_REFERENCE_UNRESOLVED = 'PKU463',
   INLINE_SCHEMA = 'PKU489',
 
   // Function errors
@@ -90,6 +91,9 @@ export enum ErrorCode {
   AGENT_TOOL_NOT_FOUND = 'PKU153',
   AGENT_TOOL_MISSING_DESCRIPTION = 'PKU154',
 
+  // Agent scorer reference errors
+  AGENT_SCORER_NOT_FOUND = 'PKU155',
+
   // File structure errors
   SCHEMA_AND_WIRING_COLOCATED = 'PKU490',
 

package/src/inspector.ts

@@ -16,6 +16,7 @@ import {
   stampAuthHandlerServices,
   validateAgentModels,
   validateAgentToolReferences,
+  validateAgentScorerReferences,
   validateSecretOverrides,
   validateVariableOverrides,
   validateCredentialOverrides,
@@ -28,10 +29,10 @@ import {
   computeMiddlewareGroupsMeta,
   computePermissionsGroupsMeta,
   computeRequiredSchemas,
-  computeSecretBrokers,
   validateNoSecretAliasServices,
   validateSecretUsage,
   computeDiagnostics,
+  validateSchemaReferences,
   validateSchemaWiringSeparation,
   validateScenarioServices,
   validateScenarioSteps,
@@ -41,7 +42,7 @@ import { validateExposedFunctionsGated } from './utils/validate-exposed-function
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js'
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js'
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js'
-import { pikkuState } from '@pikku/core/internal'
+import { pikkuState } from '@pikku/core/ecosystem'
 import { resolveLatestVersions } from './utils/resolve-versions.js'
 import { finalizeWorkflows } from './utils/workflow/graph/finalize-workflows.js'
 import {
@@ -159,6 +160,10 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       agentsMeta: {},
       files: new Map(),
     },
+    scorers: {
+      scorersMeta: {},
+      files: new Map(),
+    },
     cli: {
       meta: {
         programs: {},
@@ -444,6 +449,12 @@ export const inspect = async (
     // Re-load addon schemas (generateAllSchemas replaces state.schemas)
     await loadAddonSchemas(logger, state)
 
+    // After the addon merge, not before: an addon supplies its own schemas here,
+    // and checking earlier would report every one of them as unresolved.
+    if (options.schemaConfig) {
+      validateSchemaReferences(logger, state)
+    }
+
     state.manifest.initial = options.manifest ?? null
     const contracts = extractContractsFromMeta(state.functions.meta)
     const baseManifest = state.manifest.initial ?? createEmptyManifest()
@@ -477,7 +488,6 @@ export const inspect = async (
     computeResolvedIOTypes(state)
     computeMiddlewareGroupsMeta(state)
     computePermissionsGroupsMeta(state)
-    computeSecretBrokers(state)
     validateNoSecretAliasServices(logger, checker, state)
     validateSecretUsage(logger, state)
     computeDiagnostics(state)
@@ -504,8 +514,9 @@ export const inspect = async (
       )
     }
 
-    validateAgentModels(logger, state)
+    validateAgentModels(logger, state, options.modelAliases)
     validateAgentToolReferences(logger, state, options)
+    validateAgentScorerReferences(logger, state)
     validateSecretOverrides(logger, state)
     validateVariableOverrides(logger, state)
     validateCredentialOverrides(logger, state)

package/src/types.ts

@@ -13,6 +13,7 @@ import type {
   MCPPromptMeta,
 } from '@pikku/core/mcp'
 import type { AIAgentMeta } from '@pikku/core/ai-agent'
+import type { ScorerMeta } from '@pikku/core/ai-scorer'
 import type { CLIMeta } from '@pikku/core/cli'
 import type { CLICommandMeta } from '@pikku/core/cli'
 import type { NodesMeta } from '@pikku/core/node'
@@ -298,6 +299,8 @@ export type InspectorOptions = Partial<{
    * tool's own name, so this is a quality gate rather than a correctness one.
    */
   strictMeta: boolean
+  /** The `models` table from pikku.config.json, alias -> `provider/model`. */
+  modelAliases: Record<string, string>
   sourceFile: ts.SourceFile
   /**
    * The project's tsconfig, read for its path mappings only. The inspector's
@@ -585,6 +588,16 @@ export interface InspectorState {
         secretOverrides?: Record<string, string>
         variableOverrides?: Record<string, string>
         credentialOverrides?: Record<string, string>
+        /**
+         * The app's stated reason for handing this instance the whole
+         * `SecretService` instead of one scoped to its declared secrets.
+         */
+        globalSecrets?: string
+        /**
+         * The app's stated reason for handing this instance the whole
+         * `CredentialService` instead of one scoped to its declared credentials.
+         */
+        globalCredentials?: string
       }
     >
     wireAddonFiles: Set<string>
@@ -599,6 +612,10 @@ export interface InspectorState {
     agentsMeta: AIAgentMeta
     files: Map<string, { path: string; exportedName: string }>
   }
+  scorers: {
+    scorersMeta: ScorerMeta
+    files: Map<string, { path: string; exportedName: string }>
+  }
   cli: {
     meta: CLIMeta
     files: Set<string>

package/src/utils/filter-inspector-state.ts

@@ -419,6 +419,14 @@ export function filterInspectorState(
       agentsMeta: JSON.parse(JSON.stringify(state.agents?.agentsMeta ?? {})),
       files: new Map(),
     },
+    // Scorers carry through every filter. They are named by the agents that
+    // survive it, and a deployment that quietly stopped grading would look
+    // exactly like one whose scorers all returned nothing.
+    scorers: {
+      ...state.scorers,
+      scorersMeta: JSON.parse(JSON.stringify(state.scorers?.scorersMeta ?? {})),
+      files: new Map(state.scorers?.files ?? []),
+    },
     rpc: {
       ...state.rpc,
       internalMeta: { ...state.rpc.internalMeta }, // Clone to avoid mutating original

package/src/utils/post-process.test.ts

@@ -11,6 +11,7 @@ import {
   validateRemoteAddonDependencies,
   validateRemoteAddonAuth,
   validateAgentToolReferences,
+  validateAgentModels,
 } from './post-process.js'
 import { ErrorCode } from '../error-codes.js'
 import type { InspectorState, InspectorLogger } from '../types.js'
@@ -713,3 +714,73 @@ describe('validateAgentToolReferences (ref() resolved at build time)', () => {
     assert.deepEqual(criticals, [])
   })
 })
+
+const makeModelState = (
+  models: Record<string, string>
+): Omit<InspectorState, 'typesLookup'> =>
+  ({
+    agents: {
+      agentsMeta: Object.fromEntries(
+        Object.entries(models).map(([name, model]) => [
+          name,
+          { name, model, sourceFile: `src/${name}.agent.ts` },
+        ])
+      ),
+    },
+  }) as unknown as Omit<InspectorState, 'typesLookup'>
+
+describe('validateAgentModels (aliases resolve against pikku.config.json)', () => {
+  test('a provider-qualified model needs no alias', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentModels(logger, makeModelState({ triage: 'openai/gpt-5-mini' }))
+    assert.deepEqual(criticals, [])
+  })
+
+  test('a missing model is still reported', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentModels(logger, makeModelState({ triage: '' }))
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.MISSING_MODEL)
+  })
+
+  test('a bare name that the models table defines is accepted', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentModels(logger, makeModelState({ triage: 'cheap' }), {
+      cheap: 'openai/gpt-5-mini',
+    })
+    assert.deepEqual(criticals, [])
+  })
+
+  test('a bare name with no alias is an error naming the ones that exist', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentModels(logger, makeModelState({ triage: 'exspensive' }), {
+      cheap: 'openai/gpt-5-mini',
+      expensive: 'openai/gpt-5',
+    })
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.INVALID_MODEL)
+    assert.match(criticals[0]!.message, /cheap, expensive/)
+  })
+
+  test('with no models table a bare name still fails, as it always has', () => {
+    const { logger, criticals } = makeCriticalLogger()
+    validateAgentModels(logger, makeModelState({ triage: 'gpt-5-mini' }))
+    assert.equal(criticals.length, 1)
+    assert.equal(criticals[0]!.code, ErrorCode.INVALID_MODEL)
+  })
+
+  for (const inherited of ['toString', 'constructor', '__proto__']) {
+    test(`a bare '${inherited}' is not an alias just because Object has one`, () => {
+      const { logger, criticals } = makeCriticalLogger()
+      validateAgentModels(logger, makeModelState({ triage: inherited }), {
+        cheap: 'openai/gpt-5-mini',
+      })
+      assert.equal(
+        criticals.length,
+        1,
+        'an inherited property name must not read as a configured alias'
+      )
+      assert.equal(criticals[0]!.code, ErrorCode.INVALID_MODEL)
+    })
+  }
+})

package/src/utils/post-process.ts

@@ -15,7 +15,6 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { extractTypeKeys } from './type-utils.js'
 import { ErrorCode } from '../error-codes.js'
-import { isSecretBrokerFunction } from './secret-brokers.js'
 import { findSecretAliasServices } from './secret-alias-services.js'
 import { relative } from 'node:path'
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js'
@@ -689,9 +688,71 @@ export function computeRequiredSchemas(
   ])
 }
 
+/**
+ * Every schema a function's contract names has to exist once codegen is done.
+ *
+ * The way it stops existing is quiet. `generateCustomTypes` hands the schema
+ * generator a virtual source file that *imports* each named contract type, so a
+ * type that is declared but never exported resolves to nothing and yields no
+ * schema — while the function's meta still carries the name. Nothing downstream
+ * reads that name until the first call, which fails with a runtime
+ * `MissingSchemaError` in a deployment rather than in the build that caused it.
+ *
+ * Reported rather than critical: the reference is only *guaranteed* to break
+ * the functions that are actually invoked, so this blocks CI through
+ * `--fail-on-error` without failing a dev server over a function nobody calls.
+ */
+export function validateSchemaReferences(
+  logger: InspectorLogger,
+  state: InspectorState
+): void {
+  const { functions, schemas } = state
+  const available = new Set(Object.keys(schemas ?? {}))
+  const unresolved: string[] = []
+
+  const resolve = (typeName: string): string => {
+    try {
+      return functions.typesMap.getUniqueName(typeName)
+    } catch {
+      return typeName
+    }
+  }
+
+  for (const [funcName, meta] of Object.entries(functions.meta)) {
+    for (const [role, declared] of [
+      ['input', meta.inputs?.[0]],
+      ['output', meta.outputs?.[0]],
+    ] as const) {
+      if (!declared || PRIMITIVE_TYPES.has(declared)) continue
+      const resolved = resolve(declared)
+      if (PRIMITIVE_TYPES.has(resolved) || available.has(resolved)) continue
+      unresolved.push(`${funcName}.${role} → '${resolved}'`)
+    }
+  }
+
+  if (unresolved.length === 0) return
+
+  logger.diagnostic({
+    severity: 'error',
+    code: ErrorCode.SCHEMA_REFERENCE_UNRESOLVED,
+    message:
+      `${unresolved.length} function contract${unresolved.length === 1 ? '' : 's'} ` +
+      `name${unresolved.length === 1 ? 's' : ''} a schema that was never generated, so ` +
+      `calling ${unresolved.length === 1 ? 'it' : 'them'} fails at runtime with ` +
+      `MissingSchemaError: ${unresolved.join(', ')}. ` +
+      `The usual cause is a named type used as the function's input/output that ` +
+      `is declared but not exported — export it, or inline the type at the call site.`,
+  })
+}
+
+/**
+ * A model is either concrete (`provider/model`) or an alias, which must appear
+ * in the `models` table from pikku.config.json.
+ */
 export function validateAgentModels(
   logger: InspectorLogger,
-  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>,
+  modelAliases: Record<string, string> = {}
 ): void {
   for (const [, meta] of Object.entries(state.agents.agentsMeta)) {
     const model = meta.model
@@ -702,10 +763,17 @@ export function validateAgentModels(
       )
       continue
     }
-    if (!model.includes('/')) {
+    // `hasOwn`, not a truthy lookup: every object literal inherits `toString`,
+    // `constructor` and `__proto__`, so a bare model named after one of them
+    // would read as a configured alias and pass a check nothing else repeats.
+    if (!model.includes('/') && !Object.hasOwn(modelAliases, model)) {
+      const known = Object.keys(modelAliases).sort()
       logger.critical(
         ErrorCode.INVALID_MODEL,
-        `AI agent '${meta.name}' uses model '${model}', which must be provider-qualified as '<provider>/<model>' (e.g. 'openai/gpt-4').`
+        `AI agent '${meta.name}' uses model '${model}', which is neither provider-qualified as '<provider>/<model>' (e.g. 'openai/gpt-4') nor an alias in the "models" table of pikku.config.json. ` +
+          (known.length
+            ? `Known aliases: ${known.join(', ')}.`
+            : `No "models" aliases are configured.`)
       )
     }
   }
@@ -925,15 +993,6 @@ export function validateSchemaWiringSeparation(
   }
 }
 
-/** Marks the functions that keep the full `SecretService`. */
-export function computeSecretBrokers(state: InspectorState): void {
-  for (const [id, meta] of Object.entries(state.functions.meta)) {
-    if (isSecretBrokerFunction(meta.pikkuFuncId ?? id)) {
-      meta.secretBroker = true
-    }
-  }
-}
-
 /**
  * Refuses a singleton service that is a `SecretService` under another name.
  *
@@ -972,9 +1031,6 @@ export function validateNoSecretAliasServices(
   }
 
   for (const [id, meta] of Object.entries(state.functions.meta)) {
-    if (meta.secretBroker) {
-      continue
-    }
     report('Function', id, meta.services?.services ?? [])
   }
   for (const [id, def] of Object.entries(state.permissions.definitions)) {
@@ -1227,6 +1283,32 @@ export function validateAgentToolReferences(
   }
 }
 
+/**
+ * Validates that every scorer an agent asks to be graded by exists.
+ *
+ * The runtime warns and skips an unresolvable name rather than failing a run
+ * that has already answered the user — which means a typo would otherwise cost
+ * nothing visible and simply grade nothing, forever.
+ */
+export function validateAgentScorerReferences(
+  logger: InspectorLogger,
+  state: InspectorState | Omit<InspectorState, 'typesLookup'>
+): void {
+  const known = Object.keys(state.scorers.scorersMeta)
+
+  for (const [agentKey, agent] of Object.entries(state.agents.agentsMeta)) {
+    const where = agent.sourceFile ? ` (${agent.sourceFile})` : ''
+    for (const scorer of agent.scorers ?? []) {
+      if (known.includes(scorer)) continue
+      logger.critical(
+        ErrorCode.AGENT_SCORER_NOT_FOUND,
+        `AI agent '${agentKey}'${where} asks to be graded by scorer '${scorer}', which is not declared in this project. ` +
+          `Declared scorers: ${known.join(', ') || 'none'}.`
+      )
+    }
+  }
+}
+
 /**
  * Validates that every scope granted by a system role is declared via
  * `defineScope`. Runs after all visitors, so declaration order does not matter.

package/src/utils/serialize-inspector-state.ts

@@ -170,6 +170,8 @@ export interface SerializableInspectorState {
           secretOverrides?: Record<string, string>
           variableOverrides?: Record<string, string>
           credentialOverrides?: Record<string, string>
+          globalSecrets?: string
+          globalCredentials?: string
         },
       ]
     >
@@ -185,6 +187,10 @@ export interface SerializableInspectorState {
     agentsMeta: InspectorState['agents']['agentsMeta']
     files: [string, { path: string; exportedName: string }][]
   }
+  scorers: {
+    scorersMeta: InspectorState['scorers']['scorersMeta']
+    files: [string, { path: string; exportedName: string }][]
+  }
   cli: {
     meta: InspectorState['cli']['meta']
     files: string[]
@@ -409,6 +415,10 @@ export function serializeInspectorState(
       agentsMeta: state.agents?.agentsMeta ?? {},
       files: Array.from(state.agents?.files?.entries() ?? []),
     },
+    scorers: {
+      scorersMeta: state.scorers?.scorersMeta ?? {},
+      files: Array.from(state.scorers?.files?.entries() ?? []),
+    },
     cli: {
       meta: state.cli.meta,
       files: Array.from(state.cli.files),
@@ -613,6 +623,10 @@ export function deserializeInspectorState(
       agentsMeta: data.agents?.agentsMeta || {},
       files: new Map(data.agents?.files || []),
     },
+    scorers: {
+      scorersMeta: data.scorers?.scorersMeta || {},
+      files: new Map(data.scorers?.files || []),
+    },
     cli: {
       meta: data.cli.meta,
       files: new Set(data.cli.files),

package/src/utils/workflow/dsl/extract-approval-policy.test.ts

@@ -0,0 +1,68 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import * as ts from 'typescript'
+import { extractDSLWorkflow } from './extract-dsl-workflow.js'
+import type { ApprovalStepMeta } from '@pikku/core/workflow'
+
+const checker = {
+  getSymbolAtLocation: () => undefined,
+  getAliasedSymbol: () => undefined,
+  getShorthandAssignmentValueSymbol: () => undefined,
+  getTypeAtLocation: () => undefined,
+} as unknown as ts.TypeChecker
+
+/** Extracts the single approval step from a workflow body. */
+const approvalStepFor = (options: string): ApprovalStepMeta => {
+  const file = ts.createSourceFile(
+    'wf.ts',
+    `const wf = pikkuWorkflowFunc({
+      func: async (services, data, { workflow }) => {
+        await workflow.approval('Release funds', ${options})
+      },
+    })`,
+    ts.ScriptTarget.Latest,
+    true
+  )
+
+  let node: ts.Node | undefined
+  const visit = (n: ts.Node) => {
+    if (ts.isCallExpression(n) && n.expression.getText() === 'pikkuWorkflowFunc') {
+      node = n
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(file)
+  assert.ok(node, 'failed to find the workflow definition')
+
+  const result = extractDSLWorkflow(node, checker)
+  assert.equal(result.status, 'ok', JSON.stringify(result))
+  const step = result.steps?.find(
+    (s): s is ApprovalStepMeta => s.type === 'approval'
+  )
+  assert.ok(step, 'no approval step was extracted')
+  return step
+}
+
+describe('an approval gate carries its policy into the graph', () => {
+  test('approvers and approverScope survive extraction', () => {
+    const step = approvalStepFor(
+      `{ schema: DecisionSchema, approvers: 'not-initiator', approverScope: 'payments:approve' }`
+    )
+    assert.equal(step.approvers, 'not-initiator')
+    assert.equal(step.approverScope, 'payments:approve')
+  })
+
+  test('expiry still survives alongside them', () => {
+    const step = approvalStepFor(
+      `{ schema: DecisionSchema, expiry: '3d', approvers: 'owner' }`
+    )
+    assert.equal(step.expiry, '3d')
+    assert.equal(step.approvers, 'owner')
+  })
+
+  test('a gate declaring no policy records none', () => {
+    const step = approvalStepFor(`{ schema: DecisionSchema }`)
+    assert.equal(step.approvers, undefined)
+    assert.equal(step.approverScope, undefined)
+  })
+})

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -1051,14 +1051,15 @@ function extractApprovalStep(
       step.outputVar = outputVar
     }
     // The `schema` option is a runtime value validated inside the workflow body,
-    // so it is deliberately not serialized here — only `expiry`, which the graph
-    // and planned-step ladder need in order to describe the gate.
+    // so it is deliberately not serialized here — only the literal options the
+    // graph and planned-step ladder need in order to describe the gate.
     const options = args[1]
     if (options && ts.isObjectLiteralExpression(options)) {
       for (const prop of options.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue
+        const name = prop.name.getText()
         if (
-          ts.isPropertyAssignment(prop) &&
-          prop.name.getText() === 'expiry' &&
+          name === 'expiry' &&
           (ts.isStringLiteral(prop.initializer) ||
             ts.isNumericLiteral(prop.initializer))
         ) {
@@ -1066,6 +1067,13 @@ function extractApprovalStep(
             ? Number(prop.initializer.text)
             : prop.initializer.text
         }
+        if (name === 'approvers' && ts.isStringLiteral(prop.initializer)) {
+          step.approvers = prop.initializer
+            .text as ApprovalStepMeta['approvers']
+        }
+        if (name === 'approverScope' && ts.isStringLiteral(prop.initializer)) {
+          step.approverScope = prop.initializer.text
+        }
       }
     }
     return step