capdag 1.240.679 → 1.243.691

package/capdag.js

@@ -949,6 +949,50 @@ class CapUrn {
     return runtimeOut;
   }
 
+  /**
+   * THE effect-audit predicate: does an actually-emitted runtime output
+   * satisfy this cap's declared effect contract for the given runtime
+   * input? Every check of "did the cap emit what its effect promised"
+   * must go through this — never a hand-rolled combination of
+   * inferRuntimeOutputMedia with equality or conformance checks, so the
+   * contract has exactly one definition.
+   *
+   * The condition is deliberately asymmetric per effect:
+   * - effect=none / effect=patch compute an EXACT runtime output type,
+   *   so the emission must be tag-equivalent to the inference. A more
+   *   specific emission would still be a lie: the effect promises the
+   *   type is fully determined by the input.
+   * - effect=declared promises only the declared out=, so an emission
+   *   that is MORE specific than the declaration is legal and desirable;
+   *   the emission must conform to the declared output. A more generic
+   *   emission breaks downstream plan refinement and fails.
+   *
+   * Throws (rather than returning false) when the inference itself is
+   * impossible: the runtime input does not conform to the declared
+   * input, the effect is the unconstrained request form (?effect), or
+   * the URN state is internally inconsistent — those are upstream
+   * contract breaks, not emission mismatches.
+   *
+   * @param {MediaUrn} runtimeInput
+   * @param {MediaUrn} runtimeOutput
+   * @returns {boolean}
+   */
+  isConformantRuntimeOutput(runtimeInput, runtimeOutput) {
+    const inferred = this.inferRuntimeOutputMedia(runtimeInput);
+    switch (this.effectValue) {
+      case CapEffect.NONE:
+      case CapEffect.PATCH:
+        return runtimeOutput.isEquivalent(inferred);
+      case CapEffect.DECLARED:
+        return runtimeOutput.conformsTo(inferred);
+      default:
+        throw new CapUrnError(
+          ErrorCodes.INVALID_EFFECT_APPLICATION,
+          'Cannot audit an emission against an unconstrained effect request'
+        );
+    }
+  }
+
   _validateAdmissible() {
     const inMedia = this.inMediaUrn();
     const outMedia = this.outMediaUrn();
@@ -1561,6 +1605,17 @@ class MediaUrn {
    */
   isFilePath() { return this._hasMarkerTag('file-path'); }
 
+  /**
+   * True if this URN carries the `live` marker tag — a live-feed
+   * REFERENCE (13.2 §Reference Media): the arg value is a selector record
+   * the runtime resolves into an unbounded content stream via a registered
+   * provider, the same transport-resolution family as `media:file-path`.
+   * This is the canonical membership predicate for that family; callers
+   * must not test the `live` tag themselves.
+   * @returns {boolean}
+   */
+  isLiveFeed() { return this._hasMarkerTag('live'); }
+
   /**
    * Check if this represents a collection type.
    * Returns true if the "collection" marker tag is present.

package/capdag.test.js

@@ -2797,6 +2797,16 @@ function test551_isFilePath() {
   assert(!MediaUrn.fromString(MEDIA_IDENTITY).isFilePath(), 'MEDIA_IDENTITY should not be file-path');
 }
 
+// TEST553: is_live_feed returns true for every URN carrying the `live` marker tag (the reference-media family the runtime resolves via providers), false for everything else — including content URNs a feed delivers.
+function test553_isLiveFeed() {
+  assert(MediaUrn.fromString('media:live').isLiveFeed(), 'media:live should be live-feed');
+  assert(MediaUrn.fromString('media:live;synthetic').isLiveFeed(), 'media:live;synthetic should be live-feed');
+  assert(MediaUrn.fromString('media:audio;live;microphone').isLiveFeed(), 'microphone URN should be live-feed');
+  assert(!MediaUrn.fromString(MEDIA_STRING).isLiveFeed(), 'MEDIA_STRING should not be live-feed');
+  assert(!MediaUrn.fromString(MEDIA_FILE_PATH).isLiveFeed(), 'MEDIA_FILE_PATH should not be live-feed');
+  assert(!MediaUrn.fromString('media:audio;pcm').isLiveFeed(), 'feed CONTENT urns should not be live-feed');
+}
+
 // Mirror-specific coverage: isCollection returns true when collection marker tag is present
 // Mirror-specific coverage: N/A for JS (MEDIA_COLLECTION constants removed - no longer exists)
 function test6272_isCollection() {
@@ -3206,6 +3216,80 @@ function test127_invalidEffectNoneFailsHard() {
   );
 }
 
+// TEST8121: isConformantRuntimeOutput — effect=declared accepts a more
+// specific emission, rejects a more generic one
+function test8121_effectConformanceDeclaredAsymmetry() {
+  const cap = CapUrn.fromString('cap:extract;in="media:ext=pdf";out="media:record"');
+  const input = MediaUrn.fromString('media:ext=pdf');
+
+  assert(
+    cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:record')),
+    'emitting exactly the declared out is conformant'
+  );
+  assert(
+    cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:fmt=json;record')),
+    'a more specific emission than the declared out is conformant'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:')),
+    'a more generic emission than the declared out is a violation'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:ext=png;image')),
+    'an unrelated emission is a violation'
+  );
+}
+
+// TEST8122: isConformantRuntimeOutput — effect=none requires the emission
+// to be tag-equivalent to the runtime input; MORE specific is still a lie
+function test8122_effectConformanceNoneRequiresEquivalence() {
+  const cap = CapUrn.fromString('cap:decimate-sequence;effect=none');
+  const input = MediaUrn.fromString('media:ext=png;image');
+
+  assert(
+    cap.isConformantRuntimeOutput(input, input),
+    'emitting exactly the runtime input type is conformant'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:ext=png;image;width=64')),
+    'effect=none promises the output type IS the input type; more specific is a lie'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:image')),
+    'a more generic emission is a violation'
+  );
+
+  const strict = CapUrn.fromString('cap:effect=none;in="media:image";out="media:image"');
+  const nonImage = MediaUrn.fromString('media:ext=pdf');
+  assertThrows(
+    () => strict.isConformantRuntimeOutput(nonImage, nonImage),
+    ErrorCodes.INVALID_EFFECT_APPLICATION,
+    'a nonconforming runtime input is an upstream contract break, surfaced as an error'
+  );
+}
+
+// TEST8123: isConformantRuntimeOutput — effect=patch requires exactly the
+// delta-patched input type
+function test8123_effectConformancePatchRequiresPatchedInput() {
+  const cap = CapUrn.fromString(
+    'cap:convert;effect=patch;in="media:ext=jpeg;image";out="media:ext=png;image"'
+  );
+  const input = MediaUrn.fromString('media:ext=jpeg;image;width=64');
+
+  assert(
+    cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:ext=png;image;width=64')),
+    'the delta-patched input type (preserved tags intact) is conformant'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, MediaUrn.fromString('media:ext=png;image')),
+    'dropping the preserved width tag violates the patch promise'
+  );
+  assert(
+    !cap.isConformantRuntimeOutput(input, input),
+    'emitting the unpatched input type is a violation'
+  );
+}
+
 // TEST128: omitted effect means declared; unconstrained effect must be explicit
 function test128_effectDispatchRequiresExplicitWildcard() {
   const noneCandidate = CapUrn.fromString('cap:effect=none');
@@ -7234,6 +7318,7 @@ async function runTests() {
   runTest('TEST1315: is_numeric', test549_isNumeric);
   runTest('TEST1298: is_bool', test550_isBool);
   runTest('TEST1299: is_file_path', test551_isFilePath);
+  runTest('TEST553: is_live_feed', test553_isLiveFeed);
   runTest('TEST1302: predicate_constant_consistency', test558_predicateConstantConsistency);
 
   // cap_urn.rs: TEST1303-TEST1307 (CapUrn tier tests)
@@ -7270,6 +7355,9 @@ async function runTests() {
   runTest('TEST655: effect_declared_uses_declared_output', test126_effectDeclaredUsesDeclaredOutput);
   runTest('TEST656: invalid_effect_none_fails_hard', test127_invalidEffectNoneFailsHard);
   runTest('TEST657: effect_dispatch_requires_explicit_wildcard', test128_effectDispatchRequiresExplicitWildcard);
+  runTest('TEST8121: effect_conformance_declared_asymmetry', test8121_effectConformanceDeclaredAsymmetry);
+  runTest('TEST8122: effect_conformance_none_requires_equivalence', test8122_effectConformanceNoneRequiresEquivalence);
+  runTest('TEST8123: effect_conformance_patch_requires_patched_input', test8123_effectConformancePatchRequiresPatchedInput);
 
   // machine module: parser tests (mirrors parser.rs)
   console.log('\n--- machine/parser.rs ---');

package/package.json

@@ -15,6 +15,7 @@
     "capdag.test.js",
     "machine.pegjs",
     "machine-parser.js",
+    "planner.js",
     "RULES.md",
     "README.md"
   ],
@@ -40,5 +41,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "1.240.679"
+  "version": "1.243.691"
 }

package/planner.js

@@ -0,0 +1,424 @@
+// Unified configurable planner — the plan-space vocabulary for JS clients.
+//
+// Mirrors core Rust `capdag/src/planner/plan_space.rs` and the proto surface
+// (`machfab/proto/cap.proto` PlanMachines/DiscoverConvergentTargets): the knob
+// enums, the request shape with the same validation the engine applies, and
+// parsers for the proto-JSON response shapes (ts-proto `snakeToCamel=false`,
+// so wire field names are snake_case). This is what lets fabricloom represent
+// and manipulate the FULL planner state — knobs, ranked candidates, apexes —
+// both standalone (fixtures) and fed over gRPC by the desktop clients.
+//
+// Every parser fails hard on malformed input: a missing/mistyped field is a
+// wire bug to surface, never a value to default away.
+
+'use strict';
+
+// ============================================================================
+// Knob enums — string values ⇄ proto enum numbers
+// ============================================================================
+//
+// Each knob is a frozen map of canonical string values. The string values are
+// the cross-layer currency (UI state, IPC, fixtures); `toProto`/`fromProto`
+// convert to the proto enum numbers at the wire boundary.
+
+function makeKnob(name, entries) {
+  const values = Object.freeze(entries.map(([value]) => value));
+  const toProtoMap = new Map(entries);
+  const fromProtoMap = new Map(entries.map(([value, num]) => [num, value]));
+  return Object.freeze({
+    name,
+    values,
+    /** The knob's default (always the first entry — proto 0). */
+    default: entries[0][0],
+    isValid(value) {
+      return toProtoMap.has(value);
+    },
+    toProto(value) {
+      if (!toProtoMap.has(value)) {
+        throw new PlanStateError(
+          `${name} must be one of ${values.join(' | ')}, got ${JSON.stringify(value)}`
+        );
+      }
+      return toProtoMap.get(value);
+    },
+    fromProto(num) {
+      if (!fromProtoMap.has(num)) {
+        throw new PlanStateError(`unknown ${name} proto value ${JSON.stringify(num)}`);
+      }
+      return fromProtoMap.get(num);
+    },
+  });
+}
+
+class PlanStateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PlanStateError';
+  }
+}
+
+/** Axis C — whether the source legs meet. */
+const ConvergencePresence = makeKnob('convergencePresence', [
+  ['auto', 0],
+  ['converged', 1],
+  ['independent', 2],
+]);
+
+/** Axis D — where the apex sits (the meet-in-the-middle cut). */
+const ConvergenceLocation = makeKnob('convergenceLocation', [
+  ['auto', 0],
+  ['at-source', 1],
+  ['earliest', 2],
+  ['at-depth', 3],
+  ['latest', 4],
+  ['at-target', 5],
+]);
+
+/** Axis E — how the apex is realized. */
+const ConvergenceMechanism = makeKnob('convergenceMechanism', [
+  ['any', 0],
+  ['generalize', 1],
+  ['collect', 2],
+  ['merge', 3],
+]);
+
+/** Axis G — the colimit shape. */
+const ConvergenceArity = makeKnob('convergenceArity', [
+  ['auto', 0],
+  ['single', 1],
+  ['staged', 2],
+  ['partial', 3],
+]);
+
+/** Axis H — whether/how the plan fans out. */
+const DivergencePresence = makeKnob('divergencePresence', [
+  ['auto', 0],
+  ['none', 1],
+  ['broadcast', 2],
+  ['split', 3],
+]);
+
+/** Axis I — where a fan-out sits. */
+const DivergenceLocation = makeKnob('divergenceLocation', [
+  ['auto', 0],
+  ['at-source', 1],
+  ['at-depth', 2],
+  ['at-target', 3],
+]);
+
+/** Axis K — how candidates are ranked. "intent" is the magic default. */
+const RankPolicy = makeKnob('ranking', [
+  ['intent', 0],
+  ['shortest', 1],
+  ['cost', 2],
+]);
+
+/** Who sets the knobs. Both modes return a ranked list. */
+const PlanMode = makeKnob('mode', [
+  ['auto', 0],
+  ['configured', 1],
+]);
+
+// ============================================================================
+// PlanRequest — the full knob surface, validated like the engine validates
+// ============================================================================
+
+/**
+ * One source anchor: `{ mediaUrn, isSequence }`. Heterogeneous inputs are
+ * several specs with different media URNs; N same-typed files are one spec
+ * with `isSequence: true`.
+ */
+function validateSourceSpec(spec, index) {
+  if (spec === null || typeof spec !== 'object') {
+    throw new PlanStateError(`sources[${index}] must be an object`);
+  }
+  if (typeof spec.mediaUrn !== 'string' || spec.mediaUrn.length === 0) {
+    throw new PlanStateError(`sources[${index}].mediaUrn must be a non-empty string`);
+  }
+  if (typeof spec.isSequence !== 'boolean') {
+    throw new PlanStateError(`sources[${index}].isSequence must be a boolean`);
+  }
+  return { mediaUrn: spec.mediaUrn, isSequence: spec.isSequence };
+}
+
+/**
+ * The full plan request. Every field is a knob; `auto` mode fills unset knobs
+ * by intent inference engine-side. Constructing one validates the same
+ * invariants the engine enforces (at-depth requires a depth; a depth is only
+ * valid at at-depth; ≥1 source; ≥1 exact target), so a bad configuration
+ * fails at the UI boundary with the same message shape it would fail with on
+ * the wire.
+ */
+class PlanRequest {
+  constructor({
+    sources,
+    exactTargets,
+    convergencePresence = ConvergencePresence.default,
+    convergenceLocation = ConvergenceLocation.default,
+    convergenceAtDepth = null,
+    convergenceMechanism = ConvergenceMechanism.default,
+    convergenceAtType = null,
+    convergenceArity = ConvergenceArity.default,
+    divergencePresence = DivergencePresence.default,
+    divergenceLocation = DivergenceLocation.default,
+    divergenceAtDepth = null,
+    ranking = RankPolicy.default,
+    mode = PlanMode.default,
+    maxDepth = 0,
+    maxPaths = 0,
+    maxCandidates = 0,
+  }) {
+    if (!Array.isArray(sources) || sources.length === 0) {
+      throw new PlanStateError('sources must be a non-empty array');
+    }
+    this.sources = sources.map(validateSourceSpec);
+    if (!Array.isArray(exactTargets) || exactTargets.length === 0) {
+      throw new PlanStateError('exactTargets must be a non-empty array of media URNs');
+    }
+    for (const [i, target] of exactTargets.entries()) {
+      if (typeof target !== 'string' || target.length === 0) {
+        throw new PlanStateError(`exactTargets[${i}] must be a non-empty string`);
+      }
+    }
+    this.exactTargets = [...exactTargets];
+
+    for (const [knob, value] of [
+      [ConvergencePresence, convergencePresence],
+      [ConvergenceLocation, convergenceLocation],
+      [ConvergenceMechanism, convergenceMechanism],
+      [ConvergenceArity, convergenceArity],
+      [DivergencePresence, divergencePresence],
+      [DivergenceLocation, divergenceLocation],
+      [RankPolicy, ranking],
+      [PlanMode, mode],
+    ]) {
+      knob.toProto(value); // throws on an invalid value
+    }
+    this.convergencePresence = convergencePresence;
+    this.convergenceLocation = convergenceLocation;
+    this.convergenceMechanism = convergenceMechanism;
+    this.convergenceAtType = convergenceAtType;
+    this.convergenceArity = convergenceArity;
+    this.divergencePresence = divergencePresence;
+    this.divergenceLocation = divergenceLocation;
+    this.ranking = ranking;
+    this.mode = mode;
+
+    const depthAt = (value, location, field, atValue) => {
+      if (location === atValue) {
+        if (!Number.isInteger(value) || value < 1) {
+          throw new PlanStateError(`${field} must be a positive integer when the location is "${atValue}"`);
+        }
+        return value;
+      }
+      if (value !== null && value !== undefined) {
+        throw new PlanStateError(`${field} is only valid when the location is "${atValue}"`);
+      }
+      return 0;
+    };
+    this.convergenceAtDepth = depthAt(convergenceAtDepth, convergenceLocation, 'convergenceAtDepth', 'at-depth');
+    this.divergenceAtDepth = depthAt(divergenceAtDepth, divergenceLocation, 'divergenceAtDepth', 'at-depth');
+
+    for (const [field, value] of [
+      ['maxDepth', maxDepth],
+      ['maxPaths', maxPaths],
+      ['maxCandidates', maxCandidates],
+    ]) {
+      if (!Number.isInteger(value) || value < 0) {
+        throw new PlanStateError(`${field} must be a non-negative integer (0 = engine default)`);
+      }
+    }
+    this.maxDepth = maxDepth;
+    this.maxPaths = maxPaths;
+    this.maxCandidates = maxCandidates;
+    Object.freeze(this.sources);
+    Object.freeze(this.exactTargets);
+    Object.freeze(this);
+  }
+
+  /** True iff any space-constraining knob is set — the CONFIGURED trigger.
+   *  Ranking never counts: it re-orders, it doesn't constrain. */
+  get isConfigured() {
+    return (
+      this.convergencePresence !== 'auto' ||
+      this.convergenceLocation !== 'auto' ||
+      this.convergenceMechanism !== 'any' ||
+      this.convergenceArity !== 'auto' ||
+      this.convergenceAtType !== null ||
+      this.divergencePresence !== 'auto' ||
+      this.divergenceLocation !== 'auto'
+    );
+  }
+
+  /** The proto-JSON wire shape (`PlanMachinesRequest`, snake_case fields). */
+  toProtoJSON() {
+    return {
+      sources: this.sources.map((s) => ({ media_urn: s.mediaUrn, is_sequence: s.isSequence })),
+      exact_targets: [...this.exactTargets],
+      convergence: {
+        presence: ConvergencePresence.toProto(this.convergencePresence),
+        location: ConvergenceLocation.toProto(this.convergenceLocation),
+        at_depth: this.convergenceAtDepth,
+        mechanism: ConvergenceMechanism.toProto(this.convergenceMechanism),
+        at_type: this.convergenceAtType === null ? undefined : this.convergenceAtType,
+        arity: ConvergenceArity.toProto(this.convergenceArity),
+      },
+      divergence: {
+        presence: DivergencePresence.toProto(this.divergencePresence),
+        location: DivergenceLocation.toProto(this.divergenceLocation),
+        at_depth: this.divergenceAtDepth,
+      },
+      ranking: RankPolicy.toProto(this.ranking),
+      mode: PlanMode.toProto(this.isConfigured ? 'configured' : this.mode),
+      max_depth: this.maxDepth,
+      max_paths: this.maxPaths,
+      max_candidates: this.maxCandidates,
+    };
+  }
+}
+
+// ============================================================================
+// Response parsers — proto-JSON → typed plan state
+// ============================================================================
+
+function requireString(record, field, context) {
+  const value = record[field];
+  if (typeof value !== 'string') {
+    throw new PlanStateError(`${context}.${field} must be a string, got ${typeof value}`);
+  }
+  return value;
+}
+
+function requireNumber(record, field, context) {
+  const value = record[field];
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new PlanStateError(`${context}.${field} must be a number, got ${typeof value}`);
+  }
+  return value;
+}
+
+function requireBoolean(record, field, context) {
+  const value = record[field];
+  if (typeof value !== 'boolean') {
+    throw new PlanStateError(`${context}.${field} must be a boolean, got ${typeof value}`);
+  }
+  return value;
+}
+
+function requireRecord(value, context) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new PlanStateError(`${context} must be an object`);
+  }
+  return value;
+}
+
+function requireArray(value, context) {
+  if (!Array.isArray(value)) {
+    throw new PlanStateError(`${context} must be an array`);
+  }
+  return value;
+}
+
+/** `PlanApexMessage`: where legs meet, by which mechanism, at what depth. */
+function parsePlanApex(raw, context = 'apex') {
+  const record = requireRecord(raw, context);
+  return Object.freeze({
+    mediaUrn: requireString(record, 'media_urn', context),
+    mechanism: ConvergenceMechanism.fromProto(requireNumber(record, 'mechanism', context)),
+    depth: requireNumber(record, 'depth', context),
+  });
+}
+
+/** `PlanProfileMessage`: the candidate's (sources, apexes, targets) shape. */
+function parsePlanProfile(raw, context = 'profile') {
+  const record = requireRecord(raw, context);
+  return Object.freeze({
+    sourceMedia: requireArray(record.source_media, `${context}.source_media`).map(String),
+    targetMedia: requireArray(record.target_media, `${context}.target_media`).map(String),
+    apexes: requireArray(record.apexes, `${context}.apexes`).map((apex, i) =>
+      parsePlanApex(apex, `${context}.apexes[${i}]`)
+    ),
+    converged: requireBoolean(record, 'converged', context),
+    diverged: requireBoolean(record, 'diverged', context),
+  });
+}
+
+/** `PlanCostMessage`. */
+function parsePlanCost(raw, context = 'cost') {
+  const record = requireRecord(raw, context);
+  return Object.freeze({
+    capSteps: requireNumber(record, 'cap_steps', context),
+    totalSteps: requireNumber(record, 'total_steps', context),
+    maxLegDepth: requireNumber(record, 'max_leg_depth', context),
+    intentScore: requireNumber(record, 'intent_score', context),
+  });
+}
+
+/**
+ * `PlanCandidateMessage`: one ranked plan. `notation` IS the plan — canonical
+ * machine notation, parseable by `parseMachine` and executable by the engine.
+ */
+function parsePlanCandidate(raw, context = 'candidate') {
+  const record = requireRecord(raw, context);
+  return Object.freeze({
+    notation: requireString(record, 'notation', context),
+    profile: parsePlanProfile(record.profile, `${context}.profile`),
+    cost: parsePlanCost(record.cost, `${context}.cost`),
+    label: requireString(record, 'label', context),
+    rank: requireNumber(record, 'rank', context),
+  });
+}
+
+/** `PlanMachinesResponse` → candidates sorted by rank. */
+function parsePlanCandidates(raw, context = 'planMachines') {
+  const record = requireRecord(raw, context);
+  const candidates = requireArray(record.candidates, `${context}.candidates`).map(
+    (candidate, i) => parsePlanCandidate(candidate, `${context}.candidates[${i}]`)
+  );
+  return candidates.slice().sort((a, b) => a.rank - b.rank);
+}
+
+/**
+ * `ConvergentTargetMessage`: one discovered target — combined through an apex
+ * (`convergent: true`, `apex` set) or reachable by every source on its own.
+ */
+function parseConvergentTarget(raw, context = 'target') {
+  const record = requireRecord(raw, context);
+  const hasApex = record.apex !== undefined && record.apex !== null;
+  return Object.freeze({
+    mediaDef: requireString(record, 'media_def', context),
+    displayName: requireString(record, 'display_name', context),
+    minTotalSteps: requireNumber(record, 'min_total_steps', context),
+    apex: hasApex ? parsePlanApex(record.apex, `${context}.apex`) : null,
+    convergent: requireBoolean(record, 'convergent', context),
+    fileExtension: typeof record.file_extension === 'string' ? record.file_extension : '',
+  });
+}
+
+/** `DiscoverConvergentTargetsResponse` → convergent-first, then by steps. */
+function parseConvergentTargets(raw, context = 'discoverConvergentTargets') {
+  const record = requireRecord(raw, context);
+  return requireArray(record.targets, `${context}.targets`).map((target, i) =>
+    parseConvergentTarget(target, `${context}.targets[${i}]`)
+  );
+}
+
+module.exports = {
+  PlanStateError,
+  ConvergencePresence,
+  ConvergenceLocation,
+  ConvergenceMechanism,
+  ConvergenceArity,
+  DivergencePresence,
+  DivergenceLocation,
+  RankPolicy,
+  PlanMode,
+  PlanRequest,
+  parsePlanApex,
+  parsePlanProfile,
+  parsePlanCost,
+  parsePlanCandidate,
+  parsePlanCandidates,
+  parseConvergentTarget,
+  parseConvergentTargets,
+};