@xemahq/dsl 0.1.1

package/src/workflow/lib/compiler/concurrency.ts

@@ -0,0 +1,223 @@
+import {
+  WorkflowErrorCode,
+  WorkflowTriggerKind,
+  type ConcurrencyGroup,
+  type TriggerPayload,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import type { WorkflowConcurrencyDeclaration } from '../types';
+import {
+  EMPTY_CONTEXT_SEEDS,
+  XemaActorKind,
+  compileExpression,
+  evaluateExpression,
+  parseTemplate,
+  TemplateSegmentKind,
+  type ExpressionContext,
+  type ExpressionNode,
+  type TemplateSegment,
+} from '../expression';
+
+/**
+ * Deterministically expand the authored concurrency `group` template into a
+ * concrete lease key. Two passes:
+ *
+ *   1. **Compile time** (`compileConcurrencyGroupTemplate`): tokenize and
+ *      pre-compile every embedded expression. Authoring errors fire here so
+ *      they block snapshot creation, not dispatch.
+ *   2. **Dispatch time** (`expandCompiledConcurrencyTemplate`): evaluate each
+ *      pre-compiled expression against the trigger / inputs / vars context
+ *      and stitch the literal + evaluated segments back together.
+ *
+ * Concurrency `group` is the one DSL field that opts in to partial
+ * interpolation (`product-development:${{ inputs.projectId }}`). Every
+ * other authored expression site enforces the "fully wrapped or pure
+ * literal" policy through `extractInterpolations` — see `compile.ts`.
+ */
+
+interface CompiledTemplateExpressionSegment {
+  readonly kind: TemplateSegmentKind.Expression;
+  readonly source: string;
+  readonly node: ExpressionNode;
+}
+
+interface CompiledTemplateLiteralSegment {
+  readonly kind: TemplateSegmentKind.Literal;
+  readonly value: string;
+}
+
+type CompiledTemplateSegment =
+  | CompiledTemplateExpressionSegment
+  | CompiledTemplateLiteralSegment;
+
+/**
+ * Tokenize and pre-compile every interpolation in the authored template.
+ * Pure function: same input always yields the same compiled segments.
+ */
+function compileConcurrencyGroupTemplate(
+  authored: string,
+): readonly CompiledTemplateSegment[] {
+  const segments = parseTemplate(authored, ['concurrency', 'group']);
+  return segments.map((segment) => compileSegment(segment));
+}
+
+function compileSegment(segment: TemplateSegment): CompiledTemplateSegment {
+  if (segment.kind === TemplateSegmentKind.Literal) {
+    return { kind: TemplateSegmentKind.Literal, value: segment.value };
+  }
+  return {
+    kind: TemplateSegmentKind.Expression,
+    source: segment.source,
+    node: compileExpression(segment.source),
+  };
+}
+
+function expandCompiledConcurrencyTemplate(
+  authored: string,
+  segments: readonly CompiledTemplateSegment[],
+  ctx: ExpressionContext,
+): string {
+  const out: string[] = [];
+  for (const segment of segments) {
+    if (segment.kind === TemplateSegmentKind.Literal) {
+      out.push(segment.value);
+      continue;
+    }
+    const value = evaluateExpression(segment.node, ctx);
+    out.push(stringifyConcurrencyValue(authored, segment.source, value));
+  }
+  return out.join('');
+}
+
+function stringifyConcurrencyValue(
+  authored: string,
+  expressionSource: string,
+  value: unknown,
+): string {
+  if (value === null || value === undefined) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Concurrency group expression '${expressionSource}' resolved to ${value === null ? 'null' : 'undefined'} — refuse to build an ambiguous lease key.`,
+      { authored, expression: expressionSource },
+    );
+  }
+  if (
+    typeof value !== 'string' &&
+    typeof value !== 'number' &&
+    typeof value !== 'boolean'
+  ) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Concurrency group expression '${expressionSource}' must resolve to string/number/boolean; got ${typeof value}.`,
+      { authored, expression: expressionSource, resultKind: typeof value },
+    );
+  }
+  return String(value);
+}
+
+function buildConcurrencyContext(
+  trigger: TriggerPayload,
+  inputs: Readonly<Record<string, unknown>>,
+  vars: Readonly<Record<string, unknown>>,
+): ExpressionContext {
+  // Concurrency runs before any job: no `needs`, no matrix, no `job`.
+  // `xema.*` is seeded with the run-level identity available at this
+  // point (org/project/correlation/actor) so authors may key concurrency
+  // groups off `xema.org.id` or `xema.project.id` without reaching into
+  // trigger metadata.
+  return {
+    needs: EMPTY_CONTEXT_SEEDS.needs,
+    matrix: EMPTY_CONTEXT_SEEDS.matrix,
+    inputs,
+    vars,
+    secrets: EMPTY_CONTEXT_SEEDS.secrets,
+    trigger,
+    job: EMPTY_CONTEXT_SEEDS.job,
+    payloadCache: EMPTY_CONTEXT_SEEDS.payloadCache,
+    xema: {
+      org: { id: trigger.orgId },
+      project: { id: trigger.projectId },
+      run: {
+        id: '',
+        attempt: 0,
+        startedAtIso: trigger.triggeredAt,
+        correlationId: trigger.correlationId,
+        actor: {
+          subject: trigger.actorSubject,
+          kind: actorKindFromTrigger(trigger),
+        },
+      },
+      workflow: { key: '', version: '' },
+      job: { key: '', attempt: 0 },
+    },
+  };
+}
+
+function actorKindFromTrigger(trigger: TriggerPayload): XemaActorKind {
+  if (trigger.actorSubject) return XemaActorKind.User;
+  switch (trigger.kind) {
+    case WorkflowTriggerKind.WEBHOOK:
+      return XemaActorKind.Webhook;
+    case WorkflowTriggerKind.SCHEDULE:
+      return XemaActorKind.Schedule;
+    default:
+      return XemaActorKind.System;
+  }
+}
+
+/**
+ * Compile + expand the authored concurrency declaration into the runtime
+ * `ConcurrencyGroup`. Returns `null` when the workflow declares no
+ * concurrency at all.
+ *
+ * Compile-time errors (malformed template, malformed expression body) and
+ * dispatch-time errors (expression evaluates to null/undefined or a
+ * non-stringifiable type, expanded key is empty) all surface as typed
+ * `WorkflowDslError`s — never silently degraded to a default group.
+ */
+export function compileConcurrency(
+  declaration: WorkflowConcurrencyDeclaration | undefined,
+  trigger: TriggerPayload,
+  inputs: Readonly<Record<string, unknown>>,
+  vars: Readonly<Record<string, unknown>>,
+): ConcurrencyGroup | null {
+  if (!declaration) return null;
+
+  const compiledSegments = compileConcurrencyGroupTemplate(declaration.group);
+  const ctx = buildConcurrencyContext(trigger, inputs, vars);
+  const leaseKey = expandCompiledConcurrencyTemplate(
+    declaration.group,
+    compiledSegments,
+    ctx,
+  );
+
+  if (leaseKey.length === 0) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Concurrency group expression '${declaration.group}' expanded to an empty string.`,
+      { authored: declaration.group },
+    );
+  }
+
+  return {
+    leaseKey,
+    mode: declaration.mode,
+  };
+}
+
+/**
+ * Compile-time-only validation hook: parse and pre-compile the concurrency
+ * template so authoring errors block snapshot creation. Used by
+ * `validateAllAuthoredExpressions` in the main compiler pass; the result is
+ * discarded because the dispatch path recompiles from the same source
+ * (determinism is preserved by the canonical workflow document hash).
+ */
+export function validateConcurrencyGroupTemplate(
+  declaration: WorkflowConcurrencyDeclaration | undefined,
+): void {
+  if (!declaration) return;
+  // Parse + compile every embedded expression; throw on any syntax error.
+  // The returned segments are intentionally discarded — the dispatch path
+  // recompiles from the same source string (deterministic).
+  compileConcurrencyGroupTemplate(declaration.group);
+}

package/src/workflow/lib/compiler/dag.ts

@@ -0,0 +1,108 @@
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+
+/**
+ * Topological sort for the job DAG. Returns jobs in a stable order where
+ * every job appears after all its `needs` predecessors.
+ *
+ * Cycle detection: Kahn's algorithm. If any node remains after the queue
+ * drains, there's a cycle. Stable order: within each ready set, jobs are
+ * visited in input order (so authoring order drives UI layout).
+ *
+ * Missing-need detection: if any `needs` entry references a jobKey that
+ * isn't in the graph, fail fast (can't be silently dropped — would hide
+ * a copy-paste bug).
+ */
+export function topologicalSort<T>(
+  nodes: readonly { key: string; payload: T; needs: readonly string[] }[],
+): readonly { key: string; payload: T; needs: readonly string[] }[] {
+  const byKey = new Map<string, { key: string; payload: T; needs: readonly string[] }>();
+  const inputOrder = new Map<string, number>();
+  nodes.forEach((node, i) => {
+    if (byKey.has(node.key)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Duplicate job key: ${node.key}`,
+        { key: node.key },
+      );
+    }
+    byKey.set(node.key, node);
+    inputOrder.set(node.key, i);
+  });
+
+  // Validate needs references before building indegree — unknown refs are
+  // a structural error, not a cycle error.
+  for (const node of nodes) {
+    for (const needKey of node.needs) {
+      if (!byKey.has(needKey)) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Job '${node.key}' declares needs: [${needKey}] but no such job exists.`,
+          { jobKey: node.key, missingNeed: needKey },
+        );
+      }
+      if (needKey === node.key) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_CYCLE_DETECTED,
+          `Job '${node.key}' cannot depend on itself.`,
+          { jobKey: node.key },
+        );
+      }
+    }
+  }
+
+  const indegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>();
+  for (const node of nodes) {
+    indegree.set(node.key, node.needs.length);
+    dependents.set(node.key, []);
+  }
+  for (const node of nodes) {
+    for (const needKey of node.needs) {
+      dependents.get(needKey)!.push(node.key);
+    }
+  }
+
+  const ready: string[] = [];
+  for (const [key, d] of indegree) {
+    if (d === 0) ready.push(key);
+  }
+  stableSortByInputOrder(ready, inputOrder);
+
+  const sorted: { key: string; payload: T; needs: readonly string[] }[] = [];
+  while (ready.length > 0) {
+    const key = ready.shift()!;
+    sorted.push(byKey.get(key)!);
+    const children = dependents.get(key)!;
+    const newlyReady: string[] = [];
+    for (const child of children) {
+      const next = indegree.get(child)! - 1;
+      indegree.set(child, next);
+      if (next === 0) newlyReady.push(child);
+    }
+    stableSortByInputOrder(newlyReady, inputOrder);
+    ready.push(...newlyReady);
+    stableSortByInputOrder(ready, inputOrder);
+  }
+
+  if (sorted.length !== nodes.length) {
+    const stuck = [...indegree.entries()]
+      .filter(([, d]) => d > 0)
+      .map(([k]) => k);
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_CYCLE_DETECTED,
+      `Workflow DAG contains a cycle. Jobs in cycle or downstream of one: ${stuck.join(', ')}`,
+      { stuck },
+    );
+  }
+
+  return sorted;
+}
+
+function stableSortByInputOrder(keys: string[], inputOrder: Map<string, number>): void {
+  keys.sort((a, b) => {
+    const ai = inputOrder.get(a)!;
+    const bi = inputOrder.get(b)!;
+    return ai - bi;
+  });
+}

package/src/workflow/lib/compiler/index.ts

@@ -0,0 +1,10 @@
+export { compileWorkflow } from './compile';
+export { canonicalJsonSha256, canonicalJsonStringify } from './canonical-json';
+export { compileManifestSource } from './manifest-source';
+export { getWorkspaceManifestContract, isAgentShapedAction } from './action-shape';
+export type {
+  CompileInput,
+  ResolvedAgent,
+  ResolvedDeliverableSpec,
+  ResolvedRef,
+} from './types';

package/src/workflow/lib/compiler/inputs.ts

@@ -0,0 +1,199 @@
+import {
+  WorkflowErrorCode,
+  WorkflowTriggerKind,
+  type TriggerPayload,
+} from '@xemahq/kernel-contracts/workflow';
+import { WorkflowDslError } from '../errors';
+import type { WorkflowDocument, WorkflowInputDeclaration } from '../types';
+
+/**
+ * Bind trigger inputs against the workflow's declared input schema(s),
+ * applying declared defaults. Missing-required / type-mismatch is a
+ * compile error — never a silent zero/null substitution (rule 2).
+ *
+ * We use the trigger kind to pick which declaration block governs:
+ *   - workflow_dispatch → on.workflow_dispatch.inputs
+ *   - schedule         → on.schedule[*].inputs (pre-bound on the schedule itself)
+ *   - workflow_call    → on.workflow_call.inputs
+ *   - webhook          → no input declaration; payload is the whole envelope
+ *
+ * Scheduled triggers carry their pre-bound inputs in `trigger.inputs`; we
+ * validate against the workflow_dispatch declaration if present, or pass
+ * through un-validated (schedule-authored inputs are trusted) — the engine
+ * validates schedule-level inputs at schedule-creation time instead.
+ */
+export function bindTriggerInputs(
+  workflow: WorkflowDocument,
+  trigger: TriggerPayload,
+  previewMode = false,
+): Readonly<Record<string, unknown>> {
+  switch (trigger.kind) {
+    case WorkflowTriggerKind.WORKFLOW_DISPATCH: {
+      if (workflow.on.workflow_dispatch === undefined) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Workflow does not declare an 'on.workflow_dispatch' trigger and cannot be dispatched. Declared triggers: [${Object.keys(workflow.on).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
+          { triggerKind: 'workflow_dispatch', declaredTriggers: Object.keys(workflow.on) },
+        );
+      }
+      const decl = workflow.on.workflow_dispatch.inputs ?? {};
+      return bindInputs(decl, trigger.inputs, 'workflow_dispatch', previewMode);
+    }
+    case WorkflowTriggerKind.WORKFLOW_CALL: {
+      if (workflow.on.workflow_call === undefined) {
+        throw new WorkflowDslError(
+          WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+          `Workflow does not declare an 'on.workflow_call' trigger and cannot be invoked from another workflow. Declared triggers: [${Object.keys(workflow.on).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
+          { triggerKind: 'workflow_call', declaredTriggers: Object.keys(workflow.on) },
+        );
+      }
+      const decl = workflow.on.workflow_call.inputs ?? {};
+      return bindInputs(decl, trigger.inputs, 'workflow_call', previewMode);
+    }
+    case WorkflowTriggerKind.SCHEDULE: {
+      // Schedule inputs were validated against workflow_dispatch.inputs at
+      // schedule-create time by workflow-engine-api. Here we just validate
+      // the resulting bound payload against the same schema (defense in
+      // depth; cheap).
+      const decl = workflow.on.workflow_dispatch?.inputs ?? {};
+      return bindInputs(decl, trigger.inputs, 'schedule', previewMode);
+    }
+    case WorkflowTriggerKind.WEBHOOK: {
+      // Webhook does not declare typed inputs at the workflow level —
+      // validation of the canonical envelope happens at integration-adapters-api.
+      return trigger.payload;
+    }
+  }
+}
+
+function bindInputs(
+  declarations: Readonly<Record<string, WorkflowInputDeclaration>>,
+  received: Readonly<Record<string, unknown>>,
+  label: string,
+  previewMode = false,
+): Readonly<Record<string, unknown>> {
+  const out: Record<string, unknown> = {};
+  const seen = new Set<string>();
+
+  for (const [name, decl] of Object.entries(declarations)) {
+    seen.add(name);
+    const hasValue = Object.hasOwn(received, name);
+    if (!hasValue) {
+      handleMissingInput(out, name, decl, label, previewMode);
+      continue;
+    }
+    const value = received[name];
+    assertInputType(value, decl, name, label);
+    out[name] = value;
+  }
+
+  // Reject unknown inputs — fail-fast beats silent pass-through.
+  for (const name of Object.keys(received)) {
+    if (!seen.has(name)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `${label} trigger received unknown input '${name}'. Declared inputs: [${Object.keys(declarations).sort((a, b) => a.localeCompare(b)).join(', ') || '(none)'}].`,
+        { label, inputName: name },
+      );
+    }
+  }
+
+  return out;
+}
+
+function handleMissingInput(
+  out: Record<string, unknown>,
+  name: string,
+  decl: WorkflowInputDeclaration,
+  label: string,
+  previewMode: boolean,
+): void {
+  if (decl.required !== true) {
+    // Optional inputs are always materialized in the bound payload so
+    // `${{ inputs.<name> }}` resolves deterministically — declared default
+    // when present, otherwise null. Without this, expressions referencing
+    // a not-provided optional input throw `Unknown property` at runtime.
+    out[name] = decl.default === undefined ? null : decl.default;
+    return;
+  }
+  if (previewMode) {
+    // In preview mode, substitute a type-appropriate sentinel so the
+    // compiler can validate structure (DAG, expressions, matrix)
+    // without requiring real input values. Never used on real runs.
+    out[name] = previewSentinel(decl.type);
+    return;
+  }
+  throw new WorkflowDslError(
+    WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+    `${label} trigger is missing required input '${name}'.`,
+    { label, inputName: name },
+  );
+}
+
+/**
+ * Returns a type-appropriate sentinel value for use in preview mode when
+ * a required input is missing. The sentinel must pass `assertInputType`
+ * for its declared type — it is never used outside of preview compilation.
+ */
+function previewSentinel(type: WorkflowInputDeclaration['type']): unknown {
+  switch (type) {
+    case 'string':
+      return '';
+    case 'number':
+      return 0;
+    case 'integer':
+      return 0;
+    case 'boolean':
+      return false;
+    case 'object':
+      return {};
+    case 'array':
+      return [];
+  }
+}
+
+function assertInputType(
+  value: unknown,
+  decl: WorkflowInputDeclaration,
+  name: string,
+  label: string,
+): void {
+  const received = classify(value);
+  if (received !== decl.type) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `${label} trigger input '${name}' expected ${decl.type}, received ${received}.`,
+      { label, inputName: name, expected: decl.type, received },
+    );
+  }
+  if (decl.enum !== undefined) {
+    if (!decl.enum.includes(value)) {
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `${label} trigger input '${name}' value not in enum.`,
+        { label, inputName: name, enum: decl.enum },
+      );
+    }
+  }
+}
+
+function classify(value: unknown): WorkflowInputDeclaration['type'] {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'object'; // null treated as absence; Ajv doesn't emit null type for us
+  switch (typeof value) {
+    case 'string':
+      return 'string';
+    case 'boolean':
+      return 'boolean';
+    case 'number':
+      return Number.isInteger(value) ? 'integer' : 'number';
+    case 'object':
+      return 'object';
+    default:
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `Unsupported input value kind: ${typeof value}`,
+        { valueKind: typeof value },
+      );
+  }
+}

package/src/workflow/lib/compiler/installation-resource-validator.ts

@@ -0,0 +1,114 @@
+import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+
+import { WorkflowDslError } from '../errors';
+import {
+  collectInstallationResourceHints,
+  type InstallationResourceFieldHint,
+} from '../installation-resource-kind';
+
+import type { InstallationCompileScope } from './types';
+
+/**
+ * Compile-time check that every `x-installation-resource` field on the
+ * action manifest's `inputs:` schema points at a resource bound to the
+ * calling biome installation.
+ *
+ * Cases handled:
+ *   - Expression-shaped value (`${{ ... }}`): the literal isn't known
+ *     yet, so we skip the binding check. Runtime auth lives at the
+ *     activity layer (`AuthFailed` from credentials/resolve).
+ *   - Literal string: must be in `boundResources[kind]`. Missing →
+ *     DSL error with `inputs.<path>` pointer.
+ *   - Array of strings (rare): every element must be bound.
+ *   - Undefined + optional: no-op.
+ *
+ * Skipped entirely when `installationScope` is undefined (system /
+ * org-wide dispatch) — only biome-installed runs get this gate.
+ */
+export function validateInstallationResourceBindings(input: {
+  jobKey: string;
+  actionId: string;
+  inputsSchema: unknown;
+  withValue: Readonly<Record<string, unknown>>;
+  scope: InstallationCompileScope | undefined;
+}): void {
+  if (!input.scope) {return;}
+  if (!input.inputsSchema) {return;}
+  const hints = collectInstallationResourceHints(input.inputsSchema);
+  if (hints.length === 0) {return;}
+  for (const hint of hints) {
+    const value = readPath(input.withValue, hint.path);
+    if (value === undefined || value === null || value === '') {
+      if (hint.optional) {continue;}
+      throw new WorkflowDslError(
+        WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+        `jobs.${input.jobKey}.with.${hint.path} is required (action ${input.actionId} declares x-installation-resource kind="${hint.kind}") but the with-block omitted it`,
+      );
+    }
+    const ctx = {
+      jobKey: input.jobKey,
+      actionId: input.actionId,
+      scope: input.scope,
+    };
+    if (typeof value === 'string') {
+      assertBound(ctx, hint, value);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === 'string') {
+          assertBound(ctx, hint, item);
+        }
+      }
+    }
+  }
+}
+
+function assertBound(
+  ctx: {
+    jobKey: string;
+    actionId: string;
+    scope: InstallationCompileScope;
+  },
+  hint: InstallationResourceFieldHint,
+  literal: string,
+): void {
+  // Expression-shaped values are deferred to runtime — the literal
+  // string the compiler sees here is the expression body itself
+  // (`${{ inputs.x }}`), not a resolvable id.
+  if (literal.startsWith('${{') || literal.includes('${{')) {return;}
+  const bound = ctx.scope.boundResources[hint.kind] ?? [];
+  if (bound.length === 0) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `jobs.${ctx.jobKey}.with.${hint.path} references ${hint.kind}="${literal}" but installation ${ctx.scope.installationId} has no ${hint.kind} resources bound — connect one before dispatching`,
+    );
+  }
+  if (!bound.includes(literal)) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `jobs.${ctx.jobKey}.with.${hint.path} references ${hint.kind}="${literal}" which is NOT bound to installation ${ctx.scope.installationId} (action ${ctx.actionId} declares x-installation-resource kind="${hint.kind}"). Bound: [${bound.join(', ')}]`,
+    );
+  }
+}
+
+function readPath(
+  obj: Readonly<Record<string, unknown>>,
+  path: string,
+): unknown {
+  if (path === '') {return obj;}
+  const segments = path.split('.');
+  let cursor: unknown = obj;
+  for (const seg of segments) {
+    if (!cursor || typeof cursor !== 'object') {return undefined;}
+    // Array-element path uses `[*]` — treat as "any element", returning
+    // the array itself so the caller iterates. The hint walker emits
+    // these for `items.x-installation-resource` shapes.
+    if (seg === '[*]') {
+      if (!Array.isArray(cursor)) {return undefined;}
+      return cursor;
+    }
+    cursor = (cursor as Record<string, unknown>)[seg];
+  }
+  return cursor;
+}