feat(core): the {{ … }} interpolation engine + static secret-taint gate (1.L2)

Implement workstream 1.L2 — the runtime `{{ … }}` resolver every node's input
flows through, plus the parse-time secret-taint gate — on top of 1.L's lexer.

Runtime resolver (`resolveTemplate` / `resolveContext`):
- A pipe-filter registry — `json`, `length`, `default(…)`, and `read_file`. The
  engine stays pure (CLAUDE.md rule 5): `read_file` calls a host-injected
  `ResolverCapabilities.readFile` seam, never `node:fs`. An absent capability is
  a typed error, not a crash.
- A safe `.prop` / `[n]` / `["k"]` path accessor — no `eval`/`new Function`,
  own-property only (no prototype reads), quote-aware bracket scanning.
- Eager-once, `Object.freeze`d context: each `context` entry resolves a single
  time, in declared order, into a deterministic snapshot (re-resolve is identical
  — the property checkpoint/resume, 1.R, relies on).
- Every failure is a typed, secret-free `InterpolationError` (code discriminant,
  the offending `{{ … }}` as location; a host path stays on `cause`, off the
  message).

Static, parse-time gates wired into `parseWorkflow` (reads structure only, never
a value):
- `analyzeSecretTaint` (ADR-0029(c)): a `secret`-typed input — or anything
  transitively derived from one through a `context` entry OR an `input` default —
  is rejected from agent/human text via a field-named `WorkflowSecretLeakError`.
  The taint closes to a fixpoint over both laundering intermediates.
- `analyzeContextReferences`: a `context` value that reads `{{run.outputs[…]}}`
  is a parse error (context resolves before any node runs).

`ReferenceSite` now carries a `category` so the taint gate can target text sites.

Scope (1.L2 only): node-existence / `$ref` / `agent_ref` / handle resolution and
the cycle check remain 1.M; `condition`/`transform`/`merge_fn` JS remains the
1.AB sandbox.

Findings from an adversarial review pass folded in: the input-default taint
laundering path, a `json` filter that let a circular/BigInt `JSON.stringify`
throw escape the typed-error contract, a `getByPath` prototype-member read and a
quoted-key-with-`]` mis-parse, plus test-honesty and doc fixes.

Refs: ADR-0029, ADR-0023, ADR-0035; docs/reference/contracts/workflow-yaml-spec.md
§Context-and-interpolation. No new runtime dependency (engine-deps unchanged).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: cemililik

packages/core/src/errors.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
-import { WorkflowSyntaxError, WorkflowValidationError, type WorkflowIssue } from './errors.js';
+import {
+  InterpolationError,
+  WorkflowSecretLeakError,
+  WorkflowSyntaxError,
+  WorkflowValidationError,
+  type SecretLeak,
+  type WorkflowIssue,
+} from './errors.js';
 
 const issue = (field: string): WorkflowIssue => ({ field, message: 'bad' });
 
@@ -46,3 +53,60 @@ describe('WorkflowSyntaxError', () => {
     expect(err.column).toBeUndefined();
   });
 });
+
+describe('WorkflowSecretLeakError', () => {
+  const leak = (over: Partial<SecretLeak> = {}): SecretLeak => ({
+    location: 'node `n`.prompt_template',
+    secret: 'inputs.api_key',
+    ...over,
+  });
+
+  it('summarizes the first leak, names the field/symbol, and cites the ADR', () => {
+    const err = new WorkflowSecretLeakError([leak()]);
+    expect(err.code).toBe('secret_interpolation');
+    expect(err.message).toBe(
+      'node `n`.prompt_template interpolates the secret `inputs.api_key` — secrets are rejected from agent/human text (ADR-0029)',
+    );
+  });
+
+  it('includes a `via` hop and a plural "more" suffix', () => {
+    const err = new WorkflowSecretLeakError([
+      leak({ secret: 'ctx.creds', via: 'inputs.api_key' }),
+      leak(),
+      leak(),
+    ]);
+    expect(err.message).toContain('the secret `ctx.creds` (via `inputs.api_key`)');
+    expect(err.message).toContain('(and 2 more leaks)');
+  });
+
+  it('uses a singular "more leak" suffix for exactly two leaks', () => {
+    expect(new WorkflowSecretLeakError([leak(), leak()]).message).toContain('(and 1 more leak)');
+  });
+
+  it('summarizes an empty leak list defensively', () => {
+    expect(new WorkflowSecretLeakError([]).message).toBe('secret interpolation rejected');
+  });
+
+  it('omits a `via` that equals the secret (a direct, un-laundered reference)', () => {
+    const err = new WorkflowSecretLeakError([leak({ via: 'inputs.api_key' })]);
+    expect(err.message).not.toContain('(via');
+  });
+});
+
+describe('InterpolationError', () => {
+  it('carries a typed code and the offending reference as location', () => {
+    const err = new InterpolationError('unknown_filter', 'unknown filter `nope`', {
+      location: '{{inputs.x | nope}}',
+    });
+    expect(err.code).toBe('unknown_filter');
+    expect(err.location).toBe('{{inputs.x | nope}}');
+    expect(err.cause).toBeUndefined();
+  });
+
+  it('keeps a host error on cause and omits location when not given', () => {
+    const cause = new Error('inner');
+    const err = new InterpolationError('read_file_failed', 'read failed', { cause });
+    expect(err.cause).toBe(cause);
+    expect(err.location).toBeUndefined();
+  });
+});

packages/core/src/errors.ts

@@ -1,15 +1,20 @@
 /**
- * Typed, discriminated errors thrown by the engine's `WorkflowYAMLParser` (1.L). They mirror the
- * `@relavium/llm` `LlmConfigError` pattern — a base class with a stable `code` discriminant and
- * structured, secret-free context, narrowed on `code` and never on `message`
- * (docs/standards/error-handling.md). The user-facing fields — `message`, `issues`, `field`, the
- * `source` label, and the line/column — name the offending field/node and never carry an authored
- * value, a stack trace, or an absolute path. An internal `cause`, where attached, is a non-secret
- * diagnostic (a YAML rule, never the source text) kept for logs per error-handling.md; the raw
- * ZodError is deliberately NOT attached, as it can carry an authored `received` value.
+ * Typed, discriminated errors thrown by the engine's `WorkflowYAMLParser` (1.L) and the `{{ … }}`
+ * interpolation engine (1.L2). They mirror the `@relavium/llm` `LlmConfigError` pattern — a base
+ * class with a stable `code` discriminant and structured, secret-free context, narrowed on `code`
+ * and never on `message` (docs/standards/error-handling.md). The user-facing fields — `message`,
+ * `issues`, `field`, `leaks`, the `source` label, and the line/column — name the offending
+ * field/node/symbol and never carry an authored value, a stack trace, or an absolute path. An
+ * internal `cause`, where attached, is a non-secret diagnostic (a YAML rule, or a host `readFile`
+ * error) kept for logs per error-handling.md; the raw ZodError is deliberately NOT attached, as it
+ * can carry an authored `received` value.
+ *
+ * Two families: the parse-time {@link WorkflowParseError} (syntax / schema / secret-leak), thrown by
+ * `parseWorkflow`; and the runtime {@link InterpolationError}, thrown while resolving a template
+ * against a run scope.
  */
 
-export type WorkflowParseErrorCode = 'invalid_yaml' | 'schema_validation';
+export type WorkflowParseErrorCode = 'invalid_yaml' | 'schema_validation' | 'secret_interpolation';
 
 /** One field-named validation problem — the unit the VS Code language server later renders. */
 export interface WorkflowIssue {
@@ -19,6 +24,19 @@ export interface WorkflowIssue {
   readonly message: string;
 }
 
+/**
+ * One rejected secret interpolation (ADR-0029(c)). Every field is a *name* — an authored input name,
+ * context key, or field locator — never a resolved value, so the finding is safe to surface and log.
+ */
+export interface SecretLeak {
+  /** Where the secret was interpolated — e.g. ``node `scan`.prompt_template``. */
+  readonly location: string;
+  /** The tainted symbol referenced at that site — e.g. `inputs.api_key` or `ctx.creds` (a name). */
+  readonly secret: string;
+  /** The deeper tainted symbol, when laundered through a `context` entry — e.g. `inputs.api_key`. */
+  readonly via?: string;
+}
+
 /** Base for every parser error — callers narrow on `code`, never on `message`. */
 export abstract class WorkflowParseError extends Error {
   abstract readonly code: WorkflowParseErrorCode;
@@ -78,3 +96,70 @@ function summarize(issues: readonly WorkflowIssue[]): string {
   const more = rest > 0 ? ` (and ${rest} more issue${suffix})` : '';
   return `${first.field}: ${first.message}${more}`;
 }
+
+/**
+ * A `secret`-typed value — or anything transitively derived from one through a `context` entry —
+ * reaches agent/human text (`prompt_template`, `system_prompt[_append]`, `message_template`,
+ * `assignee`). Rejected at parse so a run never starts on it (ADR-0029(c)). The message names the
+ * offending field and the tainted symbol; it never carries the secret's value.
+ */
+export class WorkflowSecretLeakError extends WorkflowParseError {
+  readonly code = 'secret_interpolation';
+  readonly leaks: readonly SecretLeak[];
+
+  constructor(leaks: readonly SecretLeak[], opts?: { source?: string; cause?: unknown }) {
+    super(summarizeLeaks(leaks), opts?.source, opts?.cause);
+    this.name = 'WorkflowSecretLeakError';
+    this.leaks = leaks;
+  }
+}
+
+function summarizeLeaks(leaks: readonly SecretLeak[]): string {
+  const first = leaks[0];
+  if (first === undefined) {
+    return 'secret interpolation rejected';
+  }
+  const via =
+    first.via !== undefined && first.via !== first.secret ? ` (via \`${first.via}\`)` : '';
+  const rest = leaks.length - 1;
+  const suffix = rest === 1 ? '' : 's';
+  const more = rest > 0 ? ` (and ${rest} more leak${suffix})` : '';
+  return `${first.location} interpolates the secret \`${first.secret}\`${via} — secrets are rejected from agent/human text (ADR-0029)${more}`;
+}
+
+/** Stable discriminant for a runtime interpolation failure — callers narrow on `code`, not `message`. */
+export type InterpolationErrorCode =
+  | 'unresolved_reference' // a `{{ … }}` head/path resolved to no value (and no `| default(…)` rescued it)
+  | 'unknown_namespace' // a reference reads from a namespace the resolver does not serve (e.g. `secrets`)
+  | 'unknown_filter' // a pipe filter name is not in the registry
+  | 'filter_arity' // a filter was given the wrong number of arguments
+  | 'filter_type' // a filter cannot apply to the value's type (e.g. `length` on a number)
+  | 'unserializable' // a reference resolved to an object/array used as text without a `| json` filter
+  | 'invalid_path' // a malformed property/index access after the head
+  | 'read_file_unavailable' // the `read_file` filter ran without a host `readFile` capability
+  | 'read_file_failed'; // the host `readFile` capability threw (cause kept for logs, off the message)
+
+/**
+ * A runtime interpolation failure raised while *resolving* `{{ … }}` against a run scope (1.L2) —
+ * distinct from the parse-time {@link WorkflowParseError} family. User-facing and secret-free: the
+ * message names the offending reference (its verbatim `{{ … }}`) and never a resolved value; an
+ * absolute path from a host `readFile` failure stays on the `cause` (for logs), never in the message.
+ */
+export class InterpolationError extends Error {
+  readonly code: InterpolationErrorCode;
+  /** The offending `{{ … }}` occurrence, verbatim — names the reference, never a resolved value. */
+  readonly location?: string;
+
+  constructor(
+    code: InterpolationErrorCode,
+    message: string,
+    opts?: { location?: string; cause?: unknown },
+  ) {
+    super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
+    this.name = 'InterpolationError';
+    this.code = code;
+    if (opts?.location !== undefined) {
+      this.location = opts.location;
+    }
+  }
+}

packages/core/src/index.ts

@@ -6,13 +6,24 @@
  * Code extension host, and Bun alike.
  */
 
-// WorkflowYAMLParser (1.L) — parse + validate a `.relavium.yaml` string into a typed definition.
+// WorkflowYAMLParser (1.L / 1.L2) — parse + validate + static interpolation gates into a typed def.
 export { parseWorkflow } from './parser.js';
 export type { WorkflowDefinition, ParseWorkflowOptions } from './parser.js';
 
 // Typed, field-named, secret-free parse/validation errors — narrow on `code`, never on `message`.
-export { WorkflowParseError, WorkflowSyntaxError, WorkflowValidationError } from './errors.js';
-export type { WorkflowParseErrorCode, WorkflowIssue } from './errors.js';
+export {
+  WorkflowParseError,
+  WorkflowSyntaxError,
+  WorkflowValidationError,
+  WorkflowSecretLeakError,
+  InterpolationError,
+} from './errors.js';
+export type {
+  WorkflowParseErrorCode,
+  WorkflowIssue,
+  SecretLeak,
+  InterpolationErrorCode,
+} from './errors.js';
 
 // Structured, un-evaluated interpolation references — the view the DAG builder (1.M) consumes.
 export { parseTemplate, templateReferences } from './interpolation/references.js';
@@ -24,4 +35,11 @@ export type {
   FilterArg,
 } from './interpolation/references.js';
 export { collectReferences } from './interpolation/collect.js';
-export type { ReferenceSite } from './interpolation/collect.js';
+export type { ReferenceSite, ReferenceSiteCategory } from './interpolation/collect.js';
+
+// Static interpolation analyses (1.L2) — also consumed by the future VS Code language server.
+export { analyzeSecretTaint, analyzeContextReferences } from './interpolation/analyze.js';
+
+// The `{{ … }}` runtime resolver (1.L2) — evaluate templates against a run scope, eager-once context.
+export { resolveTemplate, resolveContext } from './interpolation/resolve.js';
+export type { RunScope, ResolverCapabilities } from './interpolation/scope.js';