capdag 1.233.649 → 1.241.684

package/cap-fab-renderer.js

@@ -744,6 +744,7 @@ function validateStrandStep(step, path) {
   if (!step || typeof step !== 'object') {
     throw new Error(`CapFabRenderer: ${path} is not an object`);
   }
+  assertString(step.token_id, `${path}.token_id`);
   assertString(step.from_spec, `${path}.from_spec`);
   assertString(step.to_spec, `${path}.to_spec`);
   if (!step.step_type || typeof step.step_type !== 'object') {
@@ -774,28 +775,32 @@ function validateStrandStep(step, path) {
     if (typeof body.output_is_sequence !== 'boolean') {
       throw new Error(`CapFabRenderer: ${path}.step_type.Cap.output_is_sequence must be a boolean`);
     }
-    // `inputs` (capdag CapInput list) carries the data-flow graph: the main
-    // input plus any convergence inputs. Optional on legacy payloads, but
-    // when present it must be well-formed — the fan-in edges are drawn from
-    // it, so a malformed entry is a hard error, not a silent skip.
-    if (body.inputs !== undefined) {
-      assertArray(body.inputs, `${path}.step_type.Cap.inputs`);
-      body.inputs.forEach((input, inputIdx) => {
-        const inputPath = `${path}.step_type.Cap.inputs[${inputIdx}]`;
-        assertObject(input, inputPath);
-        assertString(input.arg_urn, `${inputPath}.arg_urn`);
-        // serde: unit variant → the string "StrandInput"; struct variant →
-        // { Step: { token_id } }. Anything else is malformed.
-        if (input.source === 'StrandInput') return;
-        if (input.source && typeof input.source === 'object' && input.source.Step) {
-          assertString(input.source.Step.token_id, `${inputPath}.source.Step.token_id`);
-          return;
-        }
-        throw new Error(
-          `CapFabRenderer: ${inputPath}.source must be "StrandInput" or { Step: { token_id } }`
-        );
-      });
+    // `inputs` is the authoritative data-flow graph: the primary input plus
+    // every convergence input, with each producer named by stable token.
+    assertArray(body.inputs, `${path}.step_type.Cap.inputs`);
+    if (body.inputs.length === 0) {
+      throw new Error(`CapFabRenderer: ${path}.step_type.Cap.inputs must include the primary input`);
     }
+    const argUrns = new Set();
+    body.inputs.forEach((input, inputIdx) => {
+      const inputPath = `${path}.step_type.Cap.inputs[${inputIdx}]`;
+      assertObject(input, inputPath);
+      assertString(input.arg_urn, `${inputPath}.arg_urn`);
+      if (argUrns.has(input.arg_urn)) {
+        throw new Error(`CapFabRenderer: ${inputPath}.arg_urn duplicates '${input.arg_urn}'`);
+      }
+      argUrns.add(input.arg_urn);
+      // serde: unit variant → the string "StrandInput"; struct variant →
+      // { Step: { token_id } }. Anything else is malformed.
+      if (input.source === 'StrandInput') return;
+      if (input.source && typeof input.source === 'object' && input.source.Step) {
+        assertString(input.source.Step.token_id, `${inputPath}.source.Step.token_id`);
+        return;
+      }
+      throw new Error(
+        `CapFabRenderer: ${inputPath}.source must be "StrandInput" or { Step: { token_id } }`
+      );
+    });
   } else {
     assertString(body.media_def, `${path}.step_type.${variant}.media_def`);
   }
@@ -808,8 +813,26 @@ function validateStrandPayload(data) {
   assertString(data.source_media_urn, 'strand mode data.source_media_urn');
   assertString(data.target_media_urn, 'strand mode data.target_media_urn');
   assertArray(data.steps, 'strand mode data.steps');
+  const tokenIds = new Set();
   data.steps.forEach((step, idx) => {
     validateStrandStep(step, `strand mode data.steps[${idx}]`);
+    if (tokenIds.has(step.token_id)) {
+      throw new Error(`CapFabRenderer strand mode: duplicate step token_id '${step.token_id}'`);
+    }
+    tokenIds.add(step.token_id);
+  });
+  data.steps.forEach((step, idx) => {
+    if (!step.step_type.Cap) return;
+    step.step_type.Cap.inputs.forEach((input, inputIdx) => {
+      if (input.source === 'StrandInput') return;
+      const producerToken = input.source.Step.token_id;
+      if (!tokenIds.has(producerToken)) {
+        throw new Error(
+          `CapFabRenderer strand mode: data.steps[${idx}].step_type.Cap.inputs[${inputIdx}]` +
+          `.source.Step.token_id '${producerToken}' does not resolve to a strand step`
+        );
+      }
+    });
   });
   if (data.media_display_names !== undefined
       && (data.media_display_names === null || typeof data.media_display_names !== 'object')) {
@@ -824,23 +847,43 @@ function validateBodyOutcome(outcome, path) {
   if (!outcome || typeof outcome !== 'object') {
     throw new Error(`CapFabRenderer: ${path} is not an object`);
   }
-  if (typeof outcome.body_index !== 'number' || !Number.isInteger(outcome.body_index) || outcome.body_index < 0) {
-    throw new Error(`CapFabRenderer: ${path}.body_index must be a non-negative integer`);
+  if (typeof outcome.body_index !== 'number' || !Number.isSafeInteger(outcome.body_index) || outcome.body_index < 0) {
+    throw new Error(`CapFabRenderer: ${path}.body_index must be a non-negative safe integer`);
+  }
+  if (!Object.prototype.hasOwnProperty.call(outcome, 'foreach_token_id')) {
+    throw new Error(
+      `CapFabRenderer: ${path}.foreach_token_id must be present as null or a stable ForEach step token`
+    );
+  }
+  if (outcome.foreach_token_id !== null
+      && (typeof outcome.foreach_token_id !== 'string' || outcome.foreach_token_id.length === 0)) {
+    throw new Error(`CapFabRenderer: ${path}.foreach_token_id must be null or a non-empty string`);
+  }
+  if (outcome.foreach_token_id === null && outcome.body_index !== 0) {
+    throw new Error(`CapFabRenderer: ${path} is linear and must use body_index 0`);
   }
   if (typeof outcome.success !== 'boolean') {
     throw new Error(`CapFabRenderer: ${path}.success must be a boolean`);
   }
   assertArray(outcome.cap_urns, `${path}.cap_urns`);
   outcome.cap_urns.forEach((u, i) => assertString(u, `${path}.cap_urns[${i}]`));
-  if (outcome.failed_cap !== undefined && outcome.failed_cap !== null
-      && (typeof outcome.failed_cap !== 'string' || outcome.failed_cap.length === 0)) {
-    throw new Error(`CapFabRenderer: ${path}.failed_cap must be a non-empty string when present`);
+  if (outcome.failed_token_id !== undefined && outcome.failed_token_id !== null
+      && (typeof outcome.failed_token_id !== 'string' || outcome.failed_token_id.length === 0)) {
+    throw new Error(`CapFabRenderer: ${path}.failed_token_id must be a non-empty string when present`);
   }
-  if (!outcome.success && outcome.failed_cap === undefined) {
-    // Failure without a failed_cap is allowed (e.g. infrastructure
-    // failure before any cap ran) but we still expect the field to be
-    // present — either null or a string. Rust's Option<String>
-    // serializes as null or the string, never missing.
+  if (!Object.prototype.hasOwnProperty.call(outcome, 'failed_token_id')) {
+    throw new Error(
+      `CapFabRenderer: ${path}.failed_token_id must be present as null or a stable step token`
+    );
+  }
+  if (!Object.prototype.hasOwnProperty.call(outcome, 'failed_arg_urn')) {
+    throw new Error(
+      `CapFabRenderer: ${path}.failed_arg_urn must be present as null or an attributed argument URN`
+    );
+  }
+  if (outcome.failed_arg_urn !== null
+      && (typeof outcome.failed_arg_urn !== 'string' || outcome.failed_arg_urn.length === 0)) {
+    throw new Error(`CapFabRenderer: ${path}.failed_arg_urn must be null or a non-empty string`);
   }
 }
 
@@ -867,8 +910,29 @@ function validateRunPayload(data) {
     media_display_names: data.media_display_names,
   }));
   assertArray(data.body_outcomes, 'run mode data.body_outcomes');
+  const bodyCoordinates = new Set();
   data.body_outcomes.forEach((o, idx) => {
     validateBodyOutcome(o, `run mode data.body_outcomes[${idx}]`);
+    if (typeof o.foreach_token_id === 'string'
+        && !data.resolved_strand.steps.some(step => (
+          step.token_id === o.foreach_token_id
+          && Object.keys(step.step_type)[0] === 'ForEach'
+        ))) {
+      throw new Error(
+        `CapFabRenderer run mode: body_outcomes[${idx}].foreach_token_id '${o.foreach_token_id}' does not resolve to a ForEach strand step`
+      );
+    }
+    if (typeof o.failed_token_id === 'string'
+        && !data.resolved_strand.steps.some(step => step.token_id === o.failed_token_id)) {
+      throw new Error(
+        `CapFabRenderer run mode: body_outcomes[${idx}].failed_token_id '${o.failed_token_id}' does not resolve to a strand step`
+      );
+    }
+    const coordinate = `${o.foreach_token_id === null ? 'linear' : o.foreach_token_id}:${o.body_index}`;
+    if (bodyCoordinates.has(coordinate)) {
+      throw new Error(`CapFabRenderer run mode: duplicate body coordinate '${coordinate}'`);
+    }
+    bodyCoordinates.add(coordinate);
   });
   if (typeof data.visible_success_count !== 'number' || data.visible_success_count < 0) {
     throw new Error('CapFabRenderer run mode: data.visible_success_count must be a non-negative number');
@@ -1383,7 +1447,7 @@ function buildStrandGraphData(data) {
       // ORDER is not — the realizer emits edges greedily in dependency
       // order, so `prevNodeId` (the previously-emitted step) need not be
       // one of this cap's inputs at all.
-      const capInputs = Array.isArray(body.inputs) ? body.inputs : [];
+      const capInputs = body.inputs;
       const producerNodeIds = [];
       for (const input of capInputs) {
         const src = input && input.source;
@@ -1392,16 +1456,22 @@ function buildStrandGraphData(data) {
           continue;
         }
         const producerToken = src && typeof src === 'object' && src.Step && src.Step.token_id;
-        if (typeof producerToken !== 'string' || producerToken.length === 0) continue;
+        if (typeof producerToken !== 'string' || producerToken.length === 0) {
+          throw new Error(`CapFabRenderer strand: cap step '${step.token_id}' has an invalid producer token`);
+        }
         const producerNodeId = tokenToNodeId.get(producerToken);
-        if (producerNodeId) producerNodeIds.push(producerNodeId);
+        if (!producerNodeId) {
+          throw new Error(
+            `CapFabRenderer strand: cap step '${step.token_id}' references unknown producer '${producerToken}'`
+          );
+        }
+        producerNodeIds.push(producerNodeId);
       }
 
       // Pick the source of the single labeled "backbone" edge (the one
-      // carrying the cap title + cardinality). Inside a ForEach body — or
-      // when the cap declares no inputs — keep the linear `prevNodeId`
-      // thread so the ForEach boundary handling and its (1→n) entry marker
-      // are preserved exactly. Otherwise anchor the backbone on a REAL
+      // carrying the cap title + cardinality). Inside a ForEach body, keep
+      // the linear `prevNodeId` thread so the boundary handling and its
+      // (1→n) entry marker are preserved exactly. Otherwise anchor it on a REAL
       // input: `prevNodeId` if it is genuinely one, else the first actual
       // producer — so a non-input step ordered just before this cap can
       // never become a spurious backbone edge.
@@ -1803,14 +1873,12 @@ function buildExternalInputRunGraphData(
   if (inputRuns.length <= 1 || allOutcomes.length === 0) return null;
 
   const capSteps = data.resolved_strand.steps
-    .filter(step => Object.keys(step.step_type)[0] === 'Cap')
-    .map(step => step.step_type.Cap);
+    .filter(step => Object.keys(step.step_type)[0] === 'Cap');
   if (capSteps.length === 0) {
     throw new Error('CapFabRenderer run mode: external multi-input runs require at least one Cap step in resolved_strand.');
   }
 
   const visibleOutcomes = visibleSuccess.concat(visibleFailure);
-  const CapUrn = requireHostDependency('CapUrn');
   const sourceCanonical = canonicalMediaUrn(data.resolved_strand.source_media_urn);
   const targetCanonical = canonicalMediaUrn(data.resolved_strand.target_media_urn);
   const anchorNodeId = 'external-input-anchor';
@@ -1874,12 +1942,10 @@ function buildExternalInputRunGraphData(
 
     let traceEnd = capSteps.length;
     if (!success) {
-      if (typeof outcome.failed_cap === 'string' && outcome.failed_cap.length > 0) {
-        const failedCap = CapUrn.fromString(outcome.failed_cap);
+      if (typeof outcome.failed_token_id === 'string' && outcome.failed_token_id.length > 0) {
         traceEnd = 0;
         for (let i = 0; i < capSteps.length; i++) {
-          const candidate = CapUrn.fromString(capSteps[i].cap_urn);
-          if (candidate.isEquivalent(failedCap)) {
+          if (capSteps[i].token_id === outcome.failed_token_id) {
             traceEnd = i + 1;
             break;
           }
@@ -1891,8 +1957,13 @@ function buildExternalInputRunGraphData(
 
     let prevNodeId = sourceNodeId;
     for (let i = 0; i < traceEnd; i++) {
-      const cap = capSteps[i];
-      const targetMedia = canonicalMediaUrn(i === capSteps.length - 1 ? data.resolved_strand.target_media_urn : data.resolved_strand.steps.filter(step => Object.keys(step.step_type)[0] === 'Cap')[i].to_spec);
+      const capStep = capSteps[i];
+      const cap = capStep.step_type.Cap;
+      const targetMedia = canonicalMediaUrn(
+        i === capSteps.length - 1
+          ? data.resolved_strand.target_media_urn
+          : capStep.to_spec
+      );
       const isLastExecutedStep = i === traceEnd - 1;
       const outputs = success ? runDef.outputs : [];
 
@@ -2288,19 +2359,13 @@ function buildRunGraphData(data) {
     const edgeClass = success ? 'body-success' : 'body-failure';
     const colorVar = success ? '--graph-body-edge-success' : '--graph-body-edge-failure';
 
-    // Trace end: failures stop at `failed_cap`. `CapUrn.isEquivalent`
-    // is used for the match — never string equality.
-    let traceEnd = bodyCapSteps.length;
-    if (!success && typeof outcome.failed_cap === 'string' && outcome.failed_cap.length > 0) {
-      const CapUrn = requireHostDependency('CapUrn');
-      const target = CapUrn.fromString(outcome.failed_cap);
-      for (let i = 0; i < bodyCapSteps.length; i++) {
-        const candidate = CapUrn.fromString(bodyCapSteps[i].step.step_type.Cap.cap_urn);
-        if (candidate.isEquivalent(target)) {
-          traceEnd = i + 1;
-          break;
-        }
-      }
+    // Trace end: failures stop at the exact stable step token.
+    let traceEnd = success ? bodyCapSteps.length : 0;
+    if (!success && typeof outcome.failed_token_id === 'string' && outcome.failed_token_id.length > 0) {
+      const failedIndex = bodyCapSteps.findIndex(
+        bodyStep => bodyStep.step.token_id === outcome.failed_token_id
+      );
+      if (failedIndex >= 0) traceEnd = failedIndex + 1;
     }
 
     const bodyKey = `body-${outcome.body_index}`;

package/capdag.js

@@ -615,7 +615,7 @@ class CapUrn {
       }
     }
 
-    // Output direction: provider output must conform to requested output.
+    // Output direction: candidate output must conform to requested output.
     // `media:` on the pattern side is wildcard top and skips the check.
     if (this.outSpec !== 'media:' && this.outSpec !== '*') {
       const capOut = MediaUrn.fromString(this.outSpec);
@@ -851,7 +851,7 @@ class CapUrn {
   }
 
   /**
-   * Check if this provider can dispatch the given request.
+   * Check if this candidate can dispatch the given request.
    *
    * @param {CapUrn} request
    * @returns {boolean}
@@ -1338,7 +1338,7 @@ const MEDIA_EMBEDDING_VECTOR = 'media:embedding-vector;enc=utf-8;record';
 // and `file-type=txt` (binds the URN to the `.txt` extension).
 const MEDIA_IMAGE_DESCRIPTION = 'media:enc=utf-8;ext=txt;image-description;plain-text';
 // Media URN for finalised plain text — the canonical input/output of cap:save-as-txt.
-// Producers of user-facing prose (LLM text-generation, OCR's extracted text,
+// Producers of user-facing prose (LLM text-generation, OCR's digitized text,
 // summarisation) declare this URN as their `out` so the planner restricts the .txt
 // persistence path to those caps. See fabric/media/plain-text.toml.
 const MEDIA_PLAIN_TEXT = 'media:enc=utf-8;ext=txt;plain-text';
@@ -2481,6 +2481,46 @@ class CapArg {
     return stdinSource ? stdinSource.stdin : null;
   }
 
+  /**
+   * The media URN the runtime demuxes this arg's input stream by: its
+   * stdin source URN if it declares one, otherwise its declared slot
+   * media URN. A cap need not declare any stdin source at all — a
+   * producer-fed arg may be delivered by its declared URN — so this
+   * never assumes a stdin source exists.
+   * Mirrors Rust: CapArg::stream_urn()
+   * @returns {string} The stream media URN
+   */
+  streamUrn() {
+    const stdinSource = this.sources.find(s => s.stdin !== null);
+    return stdinSource ? stdinSource.stdin : this.media_urn;
+  }
+
+  /**
+   * Whether this arg is the cap's MAIN input relative to `inSpec` (the cap
+   * URN's `in=` value): it declares a stdin source whose URN is `in=`. The
+   * main input is always the value piped in on stdin (like a Unix command's
+   * stdin), so the main arg always declares a stdin source carrying `in=`.
+   * Its DECLARED slot URN may differ from that stdin URN (e.g. a `file-path`
+   * slot whose piped content is a `pdf-stream`) — the stdin URN, not the
+   * slot URN, is `in=`. The main input may ALSO be delivered by
+   * position/cli-flag, but stdin is the defining route. Compared by
+   * tagged-URN equivalence, never as strings.
+   * Mirrors Rust: CapArg::is_main_input(&in_spec)
+   * @param {MediaUrn|string} inSpec - The cap URN's in= spec (parsed if given as string)
+   * @returns {boolean} True if this arg is the cap's main input
+   */
+  isMainInput(inSpec) {
+    const spec = inSpec instanceof MediaUrn ? inSpec : MediaUrn.fromString(inSpec);
+    return this.sources.some(s => {
+      if (s.stdin === null) return false;
+      try {
+        return MediaUrn.fromString(s.stdin).isEquivalent(spec);
+      } catch (_) {
+        return false;
+      }
+    });
+  }
+
   /**
    * Check if this argument has a position source
    * @returns {boolean} True if has position source
@@ -2920,7 +2960,7 @@ class CapGroup {
 }
 
 /**
- * Unified cap-based manifest for components (providers and cartridges).
+ * Unified cap-based manifest for components (cartridges).
  *
  * `(registry_url, channel, name, version)` is the cartridge's full
  * identity — each (registry, channel) pair is an independent namespace.
@@ -5286,7 +5326,7 @@ const CartridgeAttachmentErrorKind = Object.freeze({
   QUARANTINED: 'quarantined',
   // On-disk install context disagrees with the cartridge.json the cartridge
   // declares — the slug folder doesn't match slug_for(registry_url), the
-  // channel folder doesn't match the manifest's channel, or a bundled-provider
+  // channel folder doesn't match the manifest's channel, or a bundled-cartridge
   // integrity proof failed. Structurally well-formed but cannot be trusted
   // because its placement on disk does not match what it claims to be.
   BAD_INSTALLATION: 'bad_installation',
@@ -5817,49 +5857,49 @@ function hashCartridgeDirectory(dir) {
 }
 
 // ---------------------------------------------------------------------------
-// Bundled-provider integrity (non-macOS).
+// Bundled-cartridge integrity (non-macOS).
 // ---------------------------------------------------------------------------
 //
-// Mirrors capdag::cartridge_discovery::verify_bundled_provider_hash and the
-// BUNDLED_PROVIDER_HASHES const codegen'd by build.rs. Under a plain build —
-// and in this mirror, which bundles no providers — the set is empty, so any
+// Mirrors capdag::cartridge_discovery::verify_bundled_cartridge_hash and the
+// BUNDLED_CARTRIDGE_HASHES const codegen'd by build.rs. Under a plain build —
+// and in this mirror, which bundles no cartridges — the set is empty, so any
 // `installed_from: bundle` cartridge has no baked hash and is rejected.
-const BUNDLED_PROVIDER_HASHES = Object.freeze([]); // [name, version, hash] triples
+const BUNDLED_CARTRIDGE_HASHES = Object.freeze([]); // [name, version, hash] triples
 
 /**
- * Look up the baked expected directory hash for a bundled provider, or null if
+ * Look up the baked expected directory hash for a bundled cartridge, or null if
  * (name, version) was not recorded at build time.
  * @returns {string|null}
  */
-function bundledProviderExpectedHash(name, version) {
-  for (const [n, v, h] of BUNDLED_PROVIDER_HASHES) {
+function bundledCartridgeExpectedHash(name, version) {
+  for (const [n, v, h] of BUNDLED_CARTRIDGE_HASHES) {
     if (n === name && v === version) return h;
   }
   return null;
 }
 
 /**
- * Verify a bundled provider's on-disk content against the hash baked into this
+ * Verify a bundled cartridge's on-disk content against the hash baked into this
  * build. Returns null on success, or an error-reason string. Mirrors
- * verify_bundled_provider_hash. Non-macOS only: macOS bundled-provider
+ * verify_bundled_cartridge_hash. Non-macOS only: macOS bundled-cartridge
  * integrity is the OS code-signature, so the engine there neither bakes nor
  * checks these hashes.
  *
  * @returns {string|null} null on OK, else the failure reason.
  */
-function verifyBundledProviderHash(name, version, versionDir) {
-  const expected = bundledProviderExpectedHash(name, version);
+function verifyBundledCartridgeHash(name, version, versionDir) {
+  const expected = bundledCartridgeExpectedHash(name, version);
   if (expected === null) {
-    return `no baked hash for bundled provider ${name} ${version} — this build did not record it (MFR_BUNDLED_PROVIDER_HASHES)`;
+    return `no baked hash for bundled cartridge ${name} ${version} — this build did not record it (MFR_BUNDLED_CARTRIDGE_HASHES)`;
   }
   let actual;
   try {
     actual = hashCartridgeDirectory(versionDir);
   } catch (e) {
-    return `failed to hash bundled provider directory: ${e.message}`;
+    return `failed to hash bundled cartridge directory: ${e.message}`;
   }
   if (actual === expected) return null;
-  return `content hash mismatch — baked ${expected}, on-disk ${actual}; the shipped provider differs from what this build was compiled to ship`;
+  return `content hash mismatch — baked ${expected}, on-disk ${actual}; the shipped cartridge differs from what this build was compiled to ship`;
 }
 
 /**
@@ -5920,7 +5960,7 @@ function unixSecondsNow() {
 }
 
 // Default protocol limits / version, mirroring capdag::bifaci::frame.
-const BIFACI_PROTOCOL_VERSION = 3;
+const BIFACI_PROTOCOL_VERSION = 4;
 const BIFACI_DEFAULT_MAX_FRAME = 3670016;
 const BIFACI_DEFAULT_MAX_CHUNK = 262144;
 const BIFACI_DEFAULT_MAX_REORDER_BUFFER = 64;
@@ -6055,6 +6095,7 @@ function encodeHelloFrame() {
       ['max_reorder_buffer', BIFACI_DEFAULT_MAX_REORDER_BUFFER],
       ['initial_credit', BIFACI_DEFAULT_INITIAL_CREDIT],
       ['version', BIFACI_PROTOCOL_VERSION],
+      ['handler_capacity', 0],
     ],
   };
   const frame = {
@@ -6154,8 +6195,27 @@ function probeCartridgeCapGroups(entryPath) {
         finish(new Error(`cartridge ${entryPath} HELLO failed: expected HELLO, got frame_type ${frameType}`));
         return;
       }
+      const version = decoded.get(BIFACI_KEY_VERSION);
+      if (version !== BIFACI_PROTOCOL_VERSION) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: protocol version ${version} does not match required version ${BIFACI_PROTOCOL_VERSION}`));
+        return;
+      }
       const meta = decoded.get(BIFACI_KEY_META);
-      const manifestVal = meta instanceof Map ? meta.get('manifest') : undefined;
+      if (!(meta instanceof Map)) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: HELLO meta must be a map`));
+        return;
+      }
+      const metaVersion = meta.get('version');
+      if (metaVersion !== BIFACI_PROTOCOL_VERSION) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: meta.version ${metaVersion} does not match required version ${BIFACI_PROTOCOL_VERSION}`));
+        return;
+      }
+      const handlerCapacity = meta.get('handler_capacity');
+      if (!Number.isSafeInteger(handlerCapacity) || handlerCapacity < 0) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: missing required non-negative handler_capacity`));
+        return;
+      }
+      const manifestVal = meta.get('manifest');
       if (!manifestVal || manifestVal.__bytes === undefined) {
         finish(new Error(`cartridge ${entryPath} HELLO failed: Cartridge HELLO missing required manifest`));
         return;
@@ -6370,7 +6430,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
       continue;
     }
 
-    // Bundled-provider integrity. A cartridge marked installed_from=bundle is
+    // Bundled-cartridge integrity. A cartridge marked installed_from=bundle is
     // shipped INSIDE this build and has no upstream registry to verify against,
     // so it needs its own integrity proof. Platform-split: on macOS the OS
     // code-signature is the guard (baked-hash verification intentionally
@@ -6378,7 +6438,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
     // value, else BadInstallation.
     if (cj.installedFrom === CartridgeInstallSource.BUNDLE) {
       if (process.platform !== 'darwin') {
-        const reason = verifyBundledProviderHash(cj.name, cj.version, versionDir);
+        const reason = verifyBundledCartridgeHash(cj.name, cj.version, versionDir);
         if (reason !== null) {
           discovered.push(DiscoveredCartridge.incompatible({
             version_dir: versionDir,
@@ -6388,7 +6448,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
             version: cj.version,
             error: new CartridgeAttachmentError(
               CartridgeAttachmentErrorKind.BAD_INSTALLATION,
-              `bundled provider integrity check failed: ${reason}`,
+              `bundled cartridge integrity check failed: ${reason}`,
               detectedAt
             ),
           }));
@@ -8148,8 +8208,8 @@ module.exports = {
   CartridgeJsonError,
   CartridgeJson,
   hashCartridgeDirectory,
-  BUNDLED_PROVIDER_HASHES,
-  verifyBundledProviderHash,
+  BUNDLED_CARTRIDGE_HASHES,
+  verifyBundledCartridgeHash,
   DiscoveryIdentity,
   DiscoveredCartridge,
   probeCartridgeCapGroups,