capdag 1.199.512 → 1.205.540

package/capdag.js

@@ -1180,44 +1180,42 @@ const MediaDefErrorCodes = {
  * - `record` marker: presence = has internal fields, absence = opaque (default)
  *
  * Examples:
- * - `media:pdf` → scalar, opaque (no markers)
- * - `media:textable;list` → list, opaque (has list marker)
- * - `media:json;textable;record` → scalar, record (has record marker)
- * - `media:json;list;record;textable` → list of records (has both markers)
+ * - `media:ext=pdf` → scalar, opaque (no markers)
+ * - `media:enc=utf-8;list` → list, opaque (has list marker)
+ * - `media:fmt=json;record` → scalar, record (has record marker)
+ * - `media:fmt=json;list;record` → list of records (has both markers)
  */
 
 // Primitive types - URNs must match base.toml definitions
 // Media URN for void (no input/output) - no coercion tags
 const MEDIA_VOID = 'media:void';
-// Media URN for string type - textable (can become text), scalar by default (no list marker)
-const MEDIA_STRING = 'media:textable';
-// Media URN for integer type - textable, numeric (math ops valid), scalar by default
-const MEDIA_INTEGER = 'media:integer;textable;numeric';
-// Media URN for number type - textable, numeric, scalar by default
-const MEDIA_NUMBER = 'media:textable;numeric';
+// Media URN for string type — bare UTF-8 text (enc=utf-8), scalar by default (no list marker)
+const MEDIA_STRING = 'media:enc=utf-8';
+// Media URN for integer type — numeric (math ops valid), scalar by default
+const MEDIA_INTEGER = 'media:integer;numeric';
+// Media URN for number type — numeric, scalar by default
+const MEDIA_NUMBER = 'media:numeric';
 // Media URN for boolean type - uses "bool" not "boolean" per base.toml
-const MEDIA_BOOLEAN = 'media:bool;textable';
-// Media URN for a generic record/object type - has internal key-value structure but NOT textable
-// Use MEDIA_JSON for textable JSON objects.
+const MEDIA_BOOLEAN = 'media:bool;enc=utf-8';
+// Media URN for a generic record/object type - has internal key-value structure,
+// no content-format claim. Use MEDIA_JSON for JSON-serialized objects.
 const MEDIA_OBJECT = 'media:record';
-// Media URN for binary data - the most general media type (no constraints)
+// Media URN for the top type - the most general media type (no constraints)
 const MEDIA_IDENTITY = 'media:';
 
 // List types - URNs must match base.toml definitions
 // Media URN for generic list type
 const MEDIA_LIST = 'media:list';
-// Media URN for textable list type
-const MEDIA_TEXTABLE_LIST = 'media:list;textable';
-// Media URN for string list type - textable with list marker
-const MEDIA_STRING_LIST = 'media:list;textable';
-// Media URN for integer list type - textable, numeric with list marker
-const MEDIA_INTEGER_LIST = 'media:integer;list;textable;numeric';
-// Media URN for number list type - textable, numeric with list marker
-const MEDIA_NUMBER_LIST = 'media:list;numeric;textable';
+// Media URN for string list type — bare UTF-8 text with list marker
+const MEDIA_STRING_LIST = 'media:enc=utf-8;list';
+// Media URN for integer list type — numeric with list marker
+const MEDIA_INTEGER_LIST = 'media:integer;list;numeric';
+// Media URN for number list type — numeric with list marker
+const MEDIA_NUMBER_LIST = 'media:list;numeric';
 // Media URN for boolean list type - uses "bool" with list marker
-const MEDIA_BOOLEAN_LIST = 'media:bool;list;textable';
-// Media URN for object list type - list of records (NOT textable)
-// Use a specific format like JSON array for textable object lists.
+const MEDIA_BOOLEAN_LIST = 'media:bool;enc=utf-8;list';
+// Media URN for object list type - list of records (no content-format claim).
+// Use a specific format like JSON array for serialized object lists.
 const MEDIA_OBJECT_LIST = 'media:list;record';
 
 // Semantic media types for specialized content
@@ -1274,104 +1272,104 @@ const MEDIA_EPUB = 'media:ext=epub';
 
 // Text format types (PRIMARY naming - type IS the format)
 // Media URN for Markdown text
-const MEDIA_MD = 'media:ext=md;textable';
+const MEDIA_MD = 'media:enc=utf-8;ext=md';
 // Media URN for plain text
-const MEDIA_TXT = 'media:ext=txt;textable';
+const MEDIA_TXT = 'media:enc=utf-8;ext=txt';
 // Media URN for reStructuredText
-const MEDIA_RST = 'media:ext=rst;textable';
+const MEDIA_RST = 'media:enc=utf-8;ext=rst';
 // Media URN for log files
-const MEDIA_LOG = 'media:ext=log;textable';
+const MEDIA_LOG = 'media:enc=utf-8;ext=log';
 // Media URN for HTML documents
-const MEDIA_HTML = 'media:ext=html;textable';
+const MEDIA_HTML = 'media:enc=utf-8;ext=html';
 // Media URN for XML documents
-const MEDIA_XML = 'media:ext=xml;textable';
+const MEDIA_XML = 'media:enc=utf-8;ext=xml';
 // Media URN for JSON data - has record marker (structured key-value)
-const MEDIA_JSON = 'media:json;record;textable';
+const MEDIA_JSON = 'media:fmt=json;record';
 // Media URN for JSON with schema constraint (input for structured queries)
-const MEDIA_JSON_SCHEMA = 'media:json;json-schema;record;textable';
+const MEDIA_JSON_SCHEMA = 'media:fmt=json;json-schema;record';
 // Media URN for YAML data - has record marker (structured key-value)
-const MEDIA_YAML = 'media:record;textable;yaml';
+const MEDIA_YAML = 'media:fmt=yaml;record';
 
 // Format-specific variants for JSON, YAML, CSV
-const MEDIA_JSON_VALUE = 'media:json;textable';
-const MEDIA_JSON_RECORD = 'media:json;record;textable';
-const MEDIA_JSON_LIST = 'media:json;list;textable';
-const MEDIA_JSON_LIST_RECORD = 'media:json;list;record;textable';
-const MEDIA_YAML_VALUE = 'media:textable;yaml';
-const MEDIA_YAML_RECORD = 'media:record;textable;yaml';
-const MEDIA_YAML_LIST = 'media:list;textable;yaml';
-const MEDIA_YAML_LIST_RECORD = 'media:list;record;textable;yaml';
-const MEDIA_CSV = 'media:ext=csv;list;record;textable';
-const MEDIA_CSV_LIST = 'media:ext=csv;list;record;textable';
+const MEDIA_JSON_VALUE = 'media:fmt=json';
+const MEDIA_JSON_RECORD = 'media:fmt=json;record';
+const MEDIA_JSON_LIST = 'media:fmt=json;list';
+const MEDIA_JSON_LIST_RECORD = 'media:fmt=json;list;record';
+const MEDIA_YAML_VALUE = 'media:fmt=yaml';
+const MEDIA_YAML_RECORD = 'media:fmt=yaml;record';
+const MEDIA_YAML_LIST = 'media:fmt=yaml;list';
+const MEDIA_YAML_LIST_RECORD = 'media:fmt=yaml;list;record';
+const MEDIA_CSV = 'media:fmt=csv;list;record';
+const MEDIA_CSV_LIST = 'media:fmt=csv;list;record';
 
 // File path type — for arguments that represent filesystem paths.
 // There is a single media URN; cardinality (single file vs many files)
 // is carried on the wire via is_sequence, not via URN tags.
-const MEDIA_FILE_PATH = 'media:file-path;textable';
+const MEDIA_FILE_PATH = 'media:enc=utf-8;file-path';
 
 // Semantic text input types - distinguished by their purpose/context
 // Media URN for model spec (provider:model format, HuggingFace name, etc.) - scalar by default
-const MEDIA_MODEL_SPEC = 'media:model-spec;textable';
+const MEDIA_MODEL_SPEC = 'media:enc=utf-8;model-spec';
 // Media URN for MLX model path - scalar by default
-const MEDIA_MLX_MODEL_PATH = 'media:mlx-model-path;textable';
+const MEDIA_MLX_MODEL_PATH = 'media:enc=utf-8;mlx-model-path';
 // Media URN for model repository (input for list-models) - has record marker
-const MEDIA_MODEL_REPO = 'media:model-repo;record;textable';
+const MEDIA_MODEL_REPO = 'media:enc=utf-8;model-repo;record';
 
 // CAPDAG output types - record marker for structured JSON objects, list marker for arrays
 // Media URN for model dimension output - scalar by default (no list marker)
-const MEDIA_MODEL_DIM = 'media:integer;model-dim;numeric;textable';
+const MEDIA_MODEL_DIM = 'media:integer;model-dim;numeric';
 // Media URN for model download output - has record marker
-const MEDIA_DOWNLOAD_OUTPUT = 'media:download-result;record;textable';
+const MEDIA_DOWNLOAD_OUTPUT = 'media:download-result;enc=utf-8;record';
 // Media URN for model list output - has record marker
-const MEDIA_LIST_OUTPUT = 'media:model-list;record;textable';
+const MEDIA_LIST_OUTPUT = 'media:enc=utf-8;model-list;record';
 // Media URN for model status output - has record marker
-const MEDIA_STATUS_OUTPUT = 'media:model-status;record;textable';
+const MEDIA_STATUS_OUTPUT = 'media:enc=utf-8;model-status;record';
 // Media URN for model contents output - has record marker
-const MEDIA_CONTENTS_OUTPUT = 'media:model-contents;record;textable';
+const MEDIA_CONTENTS_OUTPUT = 'media:enc=utf-8;model-contents;record';
 // Media URN for model availability output - has record marker
-const MEDIA_AVAILABILITY_OUTPUT = 'media:model-availability;record;textable';
+const MEDIA_AVAILABILITY_OUTPUT = 'media:enc=utf-8;model-availability;record';
 // Media URN for model path output - has record marker
-const MEDIA_PATH_OUTPUT = 'media:model-path;record;textable';
+const MEDIA_PATH_OUTPUT = 'media:enc=utf-8;model-path;record';
 // Media URN for embedding vector output - has record marker
-const MEDIA_EMBEDDING_VECTOR = 'media:embedding-vector;record;textable';
-// Media URN for vision inference output — a concrete textable terminal.
+const MEDIA_EMBEDDING_VECTOR = 'media:embedding-vector;enc=utf-8;record';
+// Media URN for vision inference output — a concrete plain-text terminal.
 // Carries `image-description` (the vision-specific marker), `plain-text` (the
 // finalised-text marker that opts into cap:save-as-txt's persistence path),
 // and `file-type=txt` (binds the URN to the `.txt` extension).
-const MEDIA_IMAGE_DESCRIPTION = 'media:ext=txt;image-description;plain-text;textable';
+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,
 // 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:ext=txt;plain-text;textable';
+const MEDIA_PLAIN_TEXT = 'media:enc=utf-8;ext=txt;plain-text';
 // Media URN for transcription output - has record marker
-const MEDIA_TRANSCRIPTION_OUTPUT = 'media:record;textable;transcription';
-// Media URN for decision output - JSON record with textable
-const MEDIA_DECISION = 'media:decision;json;record;textable';
-// Media URN for textable page output
-const MEDIA_TEXTABLE_PAGE = 'media:ext=txt;page;plain-text;textable';
-// Media URN for Hugging Face API token (secret, textable)
-const MEDIA_HF_TOKEN = 'media:hf-token;secret;textable';
+const MEDIA_TRANSCRIPTION_OUTPUT = 'media:enc=utf-8;record;transcription';
+// Media URN for decision output - JSON record
+const MEDIA_DECISION = 'media:decision;fmt=json;record';
+// Media URN for a single page of finalised plain text extracted from a document
+const MEDIA_TEXTABLE_PAGE = 'media:enc=utf-8;ext=txt;page;plain-text';
+// Media URN for Hugging Face API token (secret)
+const MEDIA_HF_TOKEN = 'media:enc=utf-8;hf-token;secret';
 // Media URN for a list of model architectures — JSON record
-const MEDIA_MODEL_ARCH_LIST = 'media:model-arch-list;json;record;textable';
+const MEDIA_MODEL_ARCH_LIST = 'media:fmt=json;model-arch-list;record';
 // Media URN for a model search request — JSON record
-const MEDIA_MODEL_SEARCH_REQUEST = 'media:model-search-request;json;record;textable';
+const MEDIA_MODEL_SEARCH_REQUEST = 'media:fmt=json;model-search-request;record';
 // Media URN for a model search response — JSON record
-const MEDIA_MODEL_SEARCH_RESPONSE = 'media:model-search-response;json;record;textable';
+const MEDIA_MODEL_SEARCH_RESPONSE = 'media:fmt=json;model-search-response;record';
 // Media URN for model filter resolution — JSON record
-const MEDIA_MODEL_FILTER_RESOLUTION = 'media:model-filter-resolution;json;record;textable';
+const MEDIA_MODEL_FILTER_RESOLUTION = 'media:fmt=json;model-filter-resolution;record';
 // Collection types
 const MEDIA_COLLECTION = 'media:collection;record';
 const MEDIA_COLLECTION_LIST = 'media:collection;list;record';
 // Media URN for adapter selection output - JSON record
-const MEDIA_ADAPTER_SELECTION = 'media:adapter-selection;json;record';
+const MEDIA_ADAPTER_SELECTION = 'media:adapter-selection;fmt=json;record';
 // Fabric registry lookup wire types (consumed/produced by cap:lookup-cap;fabric
 // and cap:lookup-media-def;fabric, both implemented by fetchcartridge).
-const MEDIA_CAP_URN = 'media:cap-urn;textable';
-const MEDIA_MEDIA_URN = 'media:media-urn;textable';
-const MEDIA_FABRIC_DEFVER = 'media:defver;textable';
-const MEDIA_CAP_DEFINITION = 'media:cap-definition;json;record;textable';
-const MEDIA_MEDIA_DEFINITION = 'media:media-definition;json;record;textable';
+const MEDIA_CAP_URN = 'media:cap-urn;enc=utf-8';
+const MEDIA_MEDIA_URN = 'media:enc=utf-8;media-urn';
+const MEDIA_FABRIC_DEFVER = 'media:defver;enc=utf-8';
+const MEDIA_CAP_DEFINITION = 'media:cap-definition;fmt=json;record';
+const MEDIA_MEDIA_DEFINITION = 'media:fmt=json;media-definition;record';
 
 // =============================================================================
 // STANDARD CAP URN CONSTANTS
@@ -1383,13 +1381,13 @@ const CAP_IDENTITY = 'cap:effect=none';
 
 // Adapter-selection capability. Default implementation returns empty END (no match).
 // Cartridges that inspect file content override this with a handler that returns {"media_urns": [...]}.
-const CAP_ADAPTER_SELECTION = 'cap:in="media:";out="media:adapter-selection;json;record"';
+const CAP_ADAPTER_SELECTION = 'cap:in="media:";out="media:adapter-selection;fmt=json;record"';
 
 // Fabric registry lookup caps. Implemented by fetchcartridge.
 // CAP_LOOKUP_CAP_FABRIC resolves a canonical cap URN to its full flattened
 // cap definition; CAP_LOOKUP_MEDIA_DEF_FABRIC does the same for media defs.
-const CAP_LOOKUP_CAP_FABRIC = 'cap:in="media:cap-urn;textable";fabric;lookup-cap;out="media:cap-definition;json;record;textable"';
-const CAP_LOOKUP_MEDIA_DEF_FABRIC = 'cap:in="media:media-urn;textable";fabric;lookup-media-def;out="media:media-definition;json;record;textable"';
+const CAP_LOOKUP_CAP_FABRIC = 'cap:in="media:cap-urn;enc=utf-8";fabric;lookup-cap;out="media:cap-definition;fmt=json;record"';
+const CAP_LOOKUP_MEDIA_DEF_FABRIC = 'cap:in="media:enc=utf-8;media-urn";fabric;lookup-media-def;out="media:fmt=json;media-definition;record"';
 
 // =============================================================================
 // MEDIA URN CLASS
@@ -1446,7 +1444,7 @@ class MediaUrn {
 
   /**
    * Parse a media URN string. Validates the prefix is 'media'.
-   * @param {string} str - The media URN string (e.g., "media:pdf")
+   * @param {string} str - The media URN string (e.g., "media:ext=pdf")
    * @returns {MediaUrn}
    * @throws {MediaUrnError} If prefix is not 'media'
    */
@@ -1455,9 +1453,6 @@ class MediaUrn {
     return new MediaUrn(urn);
   }
 
-  /** @returns {boolean} True if the "textable" marker tag is NOT present (binary = not textable) */
-  isBinary() { return this._urn.getTag('textable') === undefined; }
-
   // =========================================================================
   // CARDINALITY (list marker)
   // =========================================================================
@@ -1512,11 +1507,8 @@ class MediaUrn {
     return value === '*';
   }
 
-  /** @returns {boolean} True if the "json" marker tag is present */
-  isJson() { return this._urn.getTag('json') !== undefined; }
-
-  /** @returns {boolean} True if the "textable" marker tag is present */
-  isText() { return this._urn.getTag('textable') !== undefined; }
+  /** @returns {boolean} True if the content format is JSON (`fmt=json`) */
+  isJson() { return this._urn.getTag('fmt') === 'json'; }
 
   /** @returns {boolean} True if the "void" marker tag is present —
    *  the **unit type** in the type-theoretic reading. media:void is
@@ -1546,19 +1538,19 @@ class MediaUrn {
   isBool() { return this._urn.getTag('bool') !== undefined; }
 
   /**
-   * Returns true if this media URN describes YAML representation.
+   * Returns true if this value's content format is YAML (`fmt=yaml`).
    * @returns {boolean}
    */
   isYaml() {
-    return this._hasMarkerTag('yaml');
+    return this._urn.getTag('fmt') === 'yaml';
   }
 
   /**
-   * Returns true if this media URN describes CSV representation.
+   * Returns true if this value's content format is CSV (`fmt=csv`).
    * @returns {boolean}
    */
   isCsv() {
-    return this._hasMarkerTag('csv');
+    return this._urn.getTag('fmt') === 'csv';
   }
 
   /**
@@ -1788,6 +1780,44 @@ function getProfileURL(profileName) {
   return `${getSchemaBaseURL()}/${profileName}`;
 }
 
+/**
+ * Validate a build-time `MFR_CARTRIDGE_REGISTRY_URL` value and reduce it to
+ * the registry identity the build is published against.
+ *
+ * Mirrors capdag::bifaci::manifest::registry_url_from_build_env. The Rust
+ * version is a compile-time `const fn` fed `option_env!(...)`; in JS the
+ * equivalent input is the raw env value at process start
+ * (`process.env.MFR_CARTRIDGE_REGISTRY_URL`), where an absent variable is
+ * `undefined`.
+ *
+ * Valid states:
+ * - `null`/`undefined` => dev build; registry identity is absent and the
+ *   build must use the on-disk `dev/` slot. Returns `null`.
+ * - a non-empty string => published-registry build. Returned verbatim.
+ *
+ * Invalid state:
+ * - the empty string => the caller exported the variable with an empty value.
+ *   This is neither a dev build nor a valid registry identity, and it MUST
+ *   fail hard (throw) so the build can never silently hash the empty string
+ *   into a fake registry slug. The Rust port panics here; the JS port throws
+ *   with the same message — no fallback.
+ *
+ * @param {string|null|undefined} raw - The raw build-env value.
+ * @returns {string|null} `null` for a dev build, or the verbatim non-empty URL.
+ * @throws {Error} when `raw` is the empty string.
+ */
+function registryUrlFromBuildEnv(raw) {
+  if (raw === null || raw === undefined) {
+    return null;
+  }
+  if (raw === '') {
+    throw new Error(
+      'MFR_CARTRIDGE_REGISTRY_URL must be unset for dev builds or set to a non-empty registry URL for published builds; empty string is invalid'
+    );
+  }
+  return raw;
+}
+
 // =============================================================================
 // MEDIA URN TAG UTILITIES
 // =============================================================================
@@ -1843,10 +1873,10 @@ class MediaDef {
     return this._parsedMediaUrn;
   }
 
-  /** @returns {boolean} True if binary (textable marker tag absent) */
+  /** @returns {boolean} True if binary (no `enc` encoding tag — not text-representable) */
   isBinary() {
     const mu = this.parsedMediaUrn();
-    return mu ? mu.isBinary() : false;
+    return mu ? mu.getTag('enc') === undefined : false;
   }
 
   /** @returns {boolean} True if record structure (has record marker) */
@@ -1879,10 +1909,10 @@ class MediaDef {
     return mu ? mu.isJson() : false;
   }
 
-  /** @returns {boolean} True if text (textable tag present) */
+  /** @returns {boolean} True if text-representable (has `enc` encoding tag) */
   isText() {
     const mu = this.parsedMediaUrn();
-    return mu ? mu.isText() : false;
+    return mu ? mu.getTag('enc') !== undefined : false;
   }
 
   /** @returns {boolean} True if image (image tag present) */
@@ -1967,7 +1997,7 @@ class MediaDef {
  * Resolution: Look up mediaUrn in mediaDefs array (by urn field), FAIL HARD if not found.
  * There is no built-in resolution - all media URNs must be in mediaDefs.
  *
- * @param {string} mediaUrn - The media URN (e.g., "media:textable")
+ * @param {string} mediaUrn - The media URN (e.g., "media:enc=utf-8")
  * @param {Array} mediaDefs - The mediaDefs array (each item has urn, media_type, title, etc.)
  * @returns {MediaDef} The resolved MediaDef
  * @throws {MediaDefError} If media URN cannot be resolved
@@ -2058,7 +2088,7 @@ function buildExtensionIndex(mediaDefs) {
  *
  * @example
  * const urns = mediaUrnsForExtension('pdf', mediaDefs);
- * // May return ['media:pdf']
+ * // May return ['media:ext=pdf']
  */
 function mediaUrnsForExtension(extension, mediaDefs) {
   const index = buildExtensionIndex(mediaDefs);
@@ -3808,7 +3838,7 @@ class CapResult {
 class CapArgumentValue {
   /**
    * Create a new CapArgumentValue
-   * @param {string} mediaUrn - Semantic identifier, e.g., "media:model-spec;textable"
+   * @param {string} mediaUrn - Semantic identifier, e.g., "media:enc=utf-8;model-spec"
    * @param {Uint8Array|Buffer} value - Value bytes (UTF-8 for text, raw for binary)
    */
   constructor(mediaUrn, value) {
@@ -4358,6 +4388,126 @@ function isRegistrySlug(s) {
       && /^[0-9a-f]+$/.test(s);
 }
 
+// =============================================================================
+// Host-compatibility resolution for registry cartridges
+// =============================================================================
+//
+// Mirrors capdag::bifaci::cartridge_repo: host_platform(), CompatStatus,
+// CartridgeBuild::primary_package and CartridgeInfo::resolve_for_host.
+
+/**
+ * The platform string ({os}-{arch}) of the runtime that calls this, in the
+ * exact form the registry uses (`darwin-arm64`, `darwin-x86_64`,
+ * `linux-x86_64`, `windows-x86_64`). Single source of truth: every consumer
+ * that needs "what am I running on?" calls this rather than re-deriving the
+ * os/arch mapping.
+ *
+ * Mirrors capdag::bifaci::cartridge_repo::host_platform. The Rust version
+ * derives os/arch from `cfg!`/`std::env::consts` at compile time; the Node
+ * equivalent reads `process.platform`/`process.arch` at runtime — the engine
+ * binary literally runs on this platform, so this is the authoritative host
+ * string for compatibility resolution. Node's `darwin`/`linux`/`win32` map to
+ * the registry's `darwin`/`linux`/`windows`; Node's `arm64`/`x64` map to the
+ * registry's `arm64`/`x86_64`. Any platform/arch Node reports that has no
+ * mapping passes through unchanged, exactly as the Rust fallback does.
+ *
+ * @returns {string} The normalized `{os}-{arch}` host platform string.
+ */
+function hostPlatform() {
+  const rawOs = process.platform;
+  let os;
+  if (rawOs === 'darwin') {
+    os = 'darwin';
+  } else if (rawOs === 'linux') {
+    os = 'linux';
+  } else if (rawOs === 'win32') {
+    os = 'windows';
+  } else {
+    os = rawOs;
+  }
+  const rawArch = process.arch;
+  let arch;
+  if (rawArch === 'arm64') {
+    arch = 'arm64';
+  } else if (rawArch === 'x64') {
+    arch = 'x86_64';
+  } else {
+    arch = rawArch;
+  }
+  return `${os}-${arch}`;
+}
+
+/**
+ * Host-compatibility status of a registry cartridge, resolved against a
+ * specific host platform string. Mirrors Rust CompatStatus.
+ */
+const CompatStatus = Object.freeze({
+  // The latest version has a build for this host platform — install as-is.
+  COMPATIBLE: 'compatible',
+  // The latest version has no host build, but an older version does;
+  // resolvedVersion names that older version. Install it, mark outdated.
+  COMPATIBLE_OUTDATED: 'compatible_outdated',
+  // No version has a build for this host platform. Nothing to install.
+  INCOMPATIBLE: 'incompatible',
+});
+
+/**
+ * The installer package the host should use for a build, preferring the
+ * platform's native format. Falls back to the legacy singular `package` when
+ * `packages[]` is empty (pre-dual-write manifests). Returns `null` only when
+ * the build ships no installer at all.
+ *
+ * Mirrors CartridgeBuild::primary_package. Builds in the JS model are plain
+ * objects (`{platform, packages?, package?}`), so this is a free function
+ * taking the build object rather than a method.
+ *
+ * @param {Object} build - A platform build object with `platform`, optional
+ *   `packages` array and optional legacy `package`.
+ * @returns {Object|null} The chosen distribution-info object, or null.
+ */
+function primaryPackage(build) {
+  const os = String(build.platform || '').split('-')[0];
+  let preference;
+  switch (os) {
+    case 'darwin': preference = ['pkg']; break;
+    case 'linux': preference = ['deb', 'rpm']; break;
+    case 'windows': preference = ['msi', 'exe']; break;
+    default: preference = []; break;
+  }
+  const packages = Array.isArray(build.packages) ? build.packages : [];
+  for (const format of preference) {
+    const pkg = packages.find(p => p.format === format);
+    if (pkg) return pkg;
+  }
+  if (packages.length > 0) return packages[0];
+  return build.package || null;
+}
+
+/**
+ * The resolved verdict the engine attaches to an available cartridge: which
+ * version/package the host should install (if any) and a human reason when it
+ * is not the latest-and-greatest. Mirrors CartridgeCompatibilityResolution.
+ */
+class CartridgeCompatibilityResolution {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.status - A CompatStatus value.
+   * @param {string} opts.hostPlatform - The host platform this was resolved for.
+   * @param {string|null} [opts.resolvedVersion] - Newest version with a host
+   *   build (null when Incompatible).
+   * @param {Object|null} [opts.resolvedPackage] - Host-preferred installer
+   *   package within resolvedVersion (null when Incompatible).
+   * @param {string|null} [opts.reason] - Explanation when status is not Compatible.
+   */
+  constructor({ status, hostPlatform, resolvedVersion = null, resolvedPackage = null, reason = null }) {
+    this.status = status;
+    this.hostPlatform = hostPlatform;
+    this.resolvedVersion = resolvedVersion;
+    this.resolvedPackage = resolvedPackage;
+    this.reason = reason;
+  }
+}
+
 /**
  * Cartridge information from registry
  */
@@ -4440,6 +4590,81 @@ class CartridgeInfo {
     }
     return Array.from(platforms).sort();
   }
+
+  /**
+   * Find this cartridge's build for `hostPlatform` within a given version, if
+   * any. The host package within it is then chosen by `primaryPackage`.
+   * Mirrors CartridgeInfo::build_for_host.
+   *
+   * @param {string} version
+   * @param {string} hostPlatform
+   * @returns {Object|null}
+   */
+  buildForHost(version, hostPlatform) {
+    const versionData = this.versions[version];
+    if (!versionData) return null;
+    return (versionData.builds || []).find(b => b.platform === hostPlatform) || null;
+  }
+
+  /**
+   * Resolve which version/package this host should install, scanning versions
+   * newest-first (`availableVersions` is the authoritative newest-first
+   * ordering). The newest version with a usable host build wins:
+   *   - it IS the latest version (`this.version`) → Compatible
+   *   - it is older than the latest → CompatibleOutdated
+   *   - no version has a usable host build → Incompatible
+   *
+   * A build whose primaryPackage is null ships no installer at all; it is
+   * SKIPPED (not resolved to an un-downloadable version) and the scan
+   * continues to older versions. "Latest" is `this.version` — the same field
+   * `buildForPlatform` trusts — not `availableVersions[0]`. We do not paper
+   * over a `this.version` with no host build by silently calling it latest.
+   *
+   * Mirrors CartridgeInfo::resolve_for_host.
+   *
+   * @param {string} hostPlatform - Normally `hostPlatform()`; passed in so the
+   *   resolution is unit-testable for arbitrary hosts.
+   * @returns {CartridgeCompatibilityResolution}
+   */
+  resolveForHost(hostPlatform) {
+    const latest = this.version;
+
+    for (const ver of this.availableVersions) {
+      const build = this.buildForHost(ver, hostPlatform);
+      if (!build) continue;
+      // primaryPackage returns null only when the build ships no installer at
+      // all — a build entry with an empty packages[] and no legacy package.
+      // That is a malformed registry build; skip it rather than resolve to a
+      // version the host cannot actually download, and keep scanning older
+      // versions for a usable one.
+      const pkg = primaryPackage(build);
+      if (!pkg) continue;
+      if (ver === latest) {
+        return new CartridgeCompatibilityResolution({
+          status: CompatStatus.COMPATIBLE,
+          hostPlatform,
+          resolvedVersion: ver,
+          resolvedPackage: pkg,
+          reason: null,
+        });
+      }
+      return new CartridgeCompatibilityResolution({
+        status: CompatStatus.COMPATIBLE_OUTDATED,
+        hostPlatform,
+        resolvedVersion: ver,
+        resolvedPackage: pkg,
+        reason: `Latest ${latest} has no ${hostPlatform} build; newest compatible is ${ver}`,
+      });
+    }
+
+    return new CartridgeCompatibilityResolution({
+      status: CompatStatus.INCOMPATIBLE,
+      hostPlatform,
+      resolvedVersion: null,
+      resolvedPackage: null,
+      reason: `No installable ${hostPlatform} build available in any version`,
+    });
+  }
 }
 
 /**
@@ -5013,6 +5238,20 @@ const CartridgeAttachmentErrorKind = Object.freeze({
   IDENTITY_REJECTED: 'identity_rejected',
   ENTRY_POINT_MISSING: 'entry_point_missing',
   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
+  // 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',
+  // Operator explicitly disabled this cartridge through the host UI.
+  DISABLED: 'disabled',
+  // The cartridge declares a non-null registry_url but the host could not
+  // reach that registry to verify the cartridge is listed.
+  REGISTRY_UNREACHABLE: 'registry_unreachable',
+  // The cartridge was built against a different fabric registry manifest
+  // version than this host is pinned to.
+  FABRIC_MANIFEST_VERSION_MISMATCH: 'fabric_manifest_version_mismatch',
 });
 
 /**
@@ -5193,6 +5432,941 @@ class InstalledCartridgeRecord {
   }
 }
 
+// ============================================================================
+// Cartridge discovery — on-disk scan + identity validation + HELLO probe
+// ============================================================================
+//
+// Mirrors capdag::cartridge_discovery plus its dependencies
+// capdag::bifaci::cartridge_json (CartridgeJson, validate_registry_url_scheme,
+// hash_cartridge_directory) and the synchronous slug helper from
+// capdag::bifaci::cartridge_slug::slug_for.
+//
+// This is the single source of truth for classifying each installed cartridge
+// version directory as attachable (`directory`) or `incompatible`. Node
+// built-ins (`fs`, `path`, `crypto`, `child_process`) are required lazily
+// inside the functions so the browser bundle — which never performs disk
+// discovery — never references them.
+
+/**
+ * Synchronous on-disk slug for a registry URL. Mirrors
+ * capdag::bifaci::cartridge_slug::slug_for byte-for-byte: `null`/`undefined`
+ * (a dev cartridge) → the literal `DEV_SLUG`; otherwise the first
+ * SLUG_HEX_LEN lowercase-hex characters of sha256(url bytes).
+ *
+ * The async `slugForRegistryUrl` above uses Web Crypto for browser parity;
+ * discovery runs only under Node and needs a synchronous slug in tight
+ * per-file loops, so this uses Node's synchronous `crypto.createHash`. Both
+ * produce identical output.
+ *
+ * @param {string|null|undefined} registryUrl
+ * @returns {string}
+ */
+function slugForSync(registryUrl) {
+  if (registryUrl === null || registryUrl === undefined) {
+    return DEV_SLUG;
+  }
+  const crypto = require('crypto');
+  const hex = crypto.createHash('sha256').update(registryUrl, 'utf8').digest('hex');
+  return hex.slice(0, SLUG_HEX_LEN);
+}
+
+/**
+ * How a cartridge was installed. Pure metadata — never consulted for any host
+ * or engine routing decision. Mirrors Rust CartridgeInstallSource; the
+ * on-disk JSON uses snake_case values.
+ */
+const CartridgeInstallSource = Object.freeze({
+  REGISTRY: 'registry',
+  DEV: 'dev',
+  BUNDLE: 'bundle',
+  APP_INSTALLER: 'app_installer',
+});
+
+/**
+ * Verdict from `validateRegistryUrlScheme`. Mirrors Rust
+ * RegistryUrlSchemeResult: distinguishes OK from each rejection reason so
+ * callers can render an actionable message. `kind` is one of `ok`,
+ * `not_a_url`, `non_https`.
+ */
+const RegistryUrlSchemeResultKind = Object.freeze({
+  OK: 'ok',
+  NOT_A_URL: 'not_a_url',
+  NON_HTTPS: 'non_https',
+});
+
+/**
+ * Validate that a non-null `registry_url` uses the `https` scheme — UNLESS
+ * `devMode` is set, in which case any well-formed URL is accepted (so
+ * developers can point at `http://localhost:port` during integration
+ * testing). Mirrors capdag::bifaci::cartridge_json::validate_registry_url_scheme.
+ *
+ * Cheap parse: split once on `://`. The rule is "scheme must be the literal
+ * bytes `https`" (case-insensitive); full URL validation is the caller's job.
+ *
+ * @param {string} url
+ * @param {boolean} devMode
+ * @returns {{kind: string, url?: string, scheme?: string}}
+ */
+function validateRegistryUrlScheme(url, devMode) {
+  const idx = url.indexOf('://');
+  if (idx < 0) {
+    return { kind: RegistryUrlSchemeResultKind.NOT_A_URL, url };
+  }
+  const scheme = url.slice(0, idx);
+  const rest = url.slice(idx + 3);
+  if (rest.length === 0) {
+    return { kind: RegistryUrlSchemeResultKind.NOT_A_URL, url };
+  }
+  if (devMode) {
+    return { kind: RegistryUrlSchemeResultKind.OK };
+  }
+  if (scheme.toLowerCase() === 'https') {
+    return { kind: RegistryUrlSchemeResultKind.OK };
+  }
+  return { kind: RegistryUrlSchemeResultKind.NON_HTTPS, scheme };
+}
+
+/**
+ * Error kinds for CartridgeJson reading/validation. Mirrors the variants of
+ * Rust CartridgeJsonError. `RegistrySlugMismatch` is the three-place
+ * consistency failure that discovery maps to BAD_INSTALLATION.
+ */
+const CartridgeJsonErrorKind = Object.freeze({
+  NOT_FOUND: 'not_found',
+  READ_FAILED: 'read_failed',
+  INVALID_JSON: 'invalid_json',
+  ENTRY_POINT_MISSING: 'entry_point_missing',
+  ENTRY_POINT_NOT_EXECUTABLE: 'entry_point_not_executable',
+  ENTRY_PATH_ESCAPE: 'entry_path_escape',
+  REGISTRY_SLUG_MISMATCH: 'registry_slug_mismatch',
+});
+
+/**
+ * Error thrown by CartridgeJson.readFromDir. Carries a structured `kind` so
+ * discovery can map a slug mismatch to BAD_INSTALLATION and everything else
+ * to MANIFEST_INVALID. Mirrors Rust CartridgeJsonError.
+ */
+class CartridgeJsonError extends Error {
+  constructor(kind, message) {
+    super(message);
+    this.name = 'CartridgeJsonError';
+    this.kind = kind;
+  }
+}
+
+/**
+ * Install-context metadata stored in `cartridge.json` inside each cartridge
+ * version directory. Mirrors capdag::bifaci::cartridge_json::CartridgeJson.
+ *
+ * Identity tuple: `(registryUrl, channel, name, version)`. `registryUrl` is
+ * required-but-nullable: a MISSING `registry_url` key is a parse error
+ * (forces the new schema across every install path); only `null` means dev.
+ */
+class CartridgeJson {
+  /**
+   * @param {Object} fields
+   */
+  constructor(fields) {
+    this.name = fields.name;
+    this.version = fields.version;
+    this.channel = fields.channel;
+    this.registryUrl = fields.registryUrl;
+    this.entry = fields.entry;
+    this.installedAt = fields.installedAt;
+    this.installedFrom = fields.installedFrom !== undefined ? fields.installedFrom : null;
+    this.sourceUrl = fields.sourceUrl || '';
+    this.packageSha256 = fields.packageSha256 || '';
+    this.packageSize = fields.packageSize || 0;
+    this.fabricManifestVersion = fields.fabricManifestVersion || 0;
+  }
+
+  /**
+   * Parse a cartridge.json object. Enforces the "required-but-nullable"
+   * contract on `registry_url` — the JSON key MUST be present (missing key is
+   * a parse error); the value MAY be null (dev) or a string (registry). Stock
+   * JSON parsing would collapse absent and explicit-null, so the presence
+   * check is explicit, mirroring the Rust manual deserializer.
+   *
+   * @param {Object} obj - The parsed JSON object.
+   * @returns {CartridgeJson}
+   * @throws {CartridgeJsonError} with kind INVALID_JSON on any schema violation.
+   */
+  static fromObject(obj) {
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, 'cartridge.json must be a JSON object');
+    }
+    if (!Object.prototype.hasOwnProperty.call(obj, 'registry_url')) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, 'cartridge.json missing required field: registry_url');
+    }
+    for (const required of ['name', 'version', 'channel', 'entry', 'installed_at']) {
+      if (typeof obj[required] !== 'string') {
+        throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, `cartridge.json missing required string field: ${required}`);
+      }
+    }
+    if (obj.channel !== CartridgeChannel.Release && obj.channel !== CartridgeChannel.Nightly) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, `cartridge.json invalid channel: ${obj.channel}`);
+    }
+    const reg = obj.registry_url;
+    if (reg !== null && typeof reg !== 'string') {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, 'cartridge.json registry_url must be null or a string');
+    }
+    let installedFrom = null;
+    if (obj.installed_from !== undefined && obj.installed_from !== null) {
+      const valid = Object.values(CartridgeInstallSource);
+      if (!valid.includes(obj.installed_from)) {
+        throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, `cartridge.json unknown installed_from: ${obj.installed_from}`);
+      }
+      installedFrom = obj.installed_from;
+    }
+    return new CartridgeJson({
+      name: obj.name,
+      version: obj.version,
+      channel: obj.channel,
+      registryUrl: reg,
+      entry: obj.entry,
+      installedAt: obj.installed_at,
+      installedFrom,
+      sourceUrl: typeof obj.source_url === 'string' ? obj.source_url : '',
+      packageSha256: typeof obj.package_sha256 === 'string' ? obj.package_sha256 : '',
+      packageSize: typeof obj.package_size === 'number' ? obj.package_size : 0,
+      fabricManifestVersion: typeof obj.fabric_manifest_version === 'number' ? obj.fabric_manifest_version : 0,
+    });
+  }
+
+  /**
+   * Read and validate a `cartridge.json` from a version directory, enforcing
+   * the three-place rule against `expectedSlug` (the slug folder the host
+   * walked through). Mirrors CartridgeJson::read_from_dir.
+   *
+   * Validates: file exists and is valid JSON; the declared registry_url
+   * hashes to `expectedSlug` (else RegistrySlugMismatch); the entry point
+   * exists, does not escape the version directory, and is executable.
+   *
+   * @param {string} versionDir - Absolute path to the version directory.
+   * @param {string} expectedSlug - The on-disk slug folder name.
+   * @returns {CartridgeJson}
+   * @throws {CartridgeJsonError}
+   */
+  static readFromDir(versionDir, expectedSlug) {
+    const fs = require('fs');
+    const path = require('path');
+    const jsonPath = path.join(versionDir, 'cartridge.json');
+
+    if (!fs.existsSync(jsonPath)) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.NOT_FOUND, `cartridge.json not found at ${jsonPath}`);
+    }
+
+    let contents;
+    try {
+      contents = fs.readFileSync(jsonPath, 'utf8');
+    } catch (e) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.READ_FAILED, `failed to read cartridge.json at ${jsonPath}: ${e.message}`);
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(contents);
+    } catch (e) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, `invalid cartridge.json at ${jsonPath}: ${e.message}`);
+    }
+    const cj = CartridgeJson.fromObject(parsed);
+
+    // Three-place consistency rule (places 1 + 2): the folder slug must match
+    // the slug derived from the provenance's registry_url. None+`dev` and
+    // Some(url)+slug(url) are the only valid pairings.
+    const derivedSlug = slugForSync(cj.registryUrl);
+    if (derivedSlug !== expectedSlug) {
+      throw new CartridgeJsonError(
+        CartridgeJsonErrorKind.REGISTRY_SLUG_MISMATCH,
+        `cartridge.json at ${jsonPath}: registry slug mismatch — registry_url=${JSON.stringify(cj.registryUrl)} ` +
+        `hashes to slug='${derivedSlug}' but the directory tree placed it under '${expectedSlug}'`
+      );
+    }
+
+    // Validate entry point exists.
+    const entryPath = path.join(versionDir, cj.entry);
+    if (!fs.existsSync(entryPath)) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.ENTRY_POINT_MISSING, `cartridge.json at ${jsonPath}: entry point '${cj.entry}' does not exist`);
+    }
+
+    // Validate entry path does not escape version directory.
+    let canonicalDir;
+    let canonicalEntry;
+    try { canonicalDir = fs.realpathSync(versionDir); } catch (_e) { canonicalDir = path.resolve(versionDir); }
+    try { canonicalEntry = fs.realpathSync(entryPath); } catch (_e) { canonicalEntry = path.resolve(entryPath); }
+    const dirWithSep = canonicalDir.endsWith(path.sep) ? canonicalDir : canonicalDir + path.sep;
+    if (canonicalEntry !== canonicalDir && !canonicalEntry.startsWith(dirWithSep)) {
+      throw new CartridgeJsonError(CartridgeJsonErrorKind.ENTRY_PATH_ESCAPE, `cartridge.json at ${jsonPath}: entry path '${cj.entry}' escapes version directory`);
+    }
+
+    // Validate entry point is executable (unix permission bits).
+    if (process.platform !== 'win32') {
+      let mode;
+      try {
+        mode = fs.statSync(entryPath).mode;
+      } catch (e) {
+        throw new CartridgeJsonError(CartridgeJsonErrorKind.READ_FAILED, `failed to read cartridge.json at ${jsonPath}: ${e.message}`);
+      }
+      if ((mode & 0o111) === 0) {
+        throw new CartridgeJsonError(CartridgeJsonErrorKind.ENTRY_POINT_NOT_EXECUTABLE, `cartridge.json at ${jsonPath}: entry point '${cj.entry}' is not executable`);
+      }
+    }
+
+    return cj;
+  }
+
+  /** True when installed as a dev build (no registry URL). */
+  isDevInstall() {
+    return this.registryUrl === null || this.registryUrl === undefined;
+  }
+
+  /** The on-disk slug this provenance must live under. */
+  registrySlug() {
+    return slugForSync(this.registryUrl);
+  }
+
+  /**
+   * Resolve the absolute path to the entry point binary.
+   * @param {string} versionDir
+   * @returns {string}
+   */
+  resolveEntryPoint(versionDir) {
+    const path = require('path');
+    return path.join(versionDir, this.entry);
+  }
+}
+
+/**
+ * Compute a deterministic SHA256 hash of a directory tree. Walks all files
+ * recursively, sorts them by relative path, then hashes each file's relative
+ * path (UTF-8 bytes) followed by its contents — a stable identity hash
+ * regardless of filesystem ordering. `cartridge.json` itself is excluded (it
+ * holds install-time metadata that varies between installs of identical
+ * content). Mirrors capdag::bifaci::cartridge_json::hash_cartridge_directory.
+ *
+ * @param {string} dir - Absolute path to the directory.
+ * @returns {string} Lowercase hex SHA256.
+ */
+function hashCartridgeDirectory(dir) {
+  const fs = require('fs');
+  const path = require('path');
+  const crypto = require('crypto');
+
+  const files = [];
+  const collect = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        collect(full);
+      } else if (entry.isFile() || entry.isSymbolicLink()) {
+        let relative = path.relative(dir, full);
+        // Normalize to the same separator the Rust to_string_lossy yields on
+        // the platform — on POSIX both use '/'. Windows separators differ but
+        // the cartridge tree is POSIX in practice; keep relative verbatim.
+        if (relative === 'cartridge.json') continue;
+        files.push([relative, full]);
+      }
+    }
+  };
+  collect(dir);
+  files.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+
+  const hasher = crypto.createHash('sha256');
+  for (const [relativePath, fullPath] of files) {
+    hasher.update(Buffer.from(relativePath, 'utf8'));
+    hasher.update(fs.readFileSync(fullPath));
+  }
+  return hasher.digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Bundled-provider 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
+// `installed_from: bundle` cartridge has no baked hash and is rejected.
+const BUNDLED_PROVIDER_HASHES = Object.freeze([]); // [name, version, hash] triples
+
+/**
+ * Look up the baked expected directory hash for a bundled provider, 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) {
+    if (n === name && v === version) return h;
+  }
+  return null;
+}
+
+/**
+ * Verify a bundled provider'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
+ * 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);
+  if (expected === null) {
+    return `no baked hash for bundled provider ${name} ${version} — this build did not record it (MFR_BUNDLED_PROVIDER_HASHES)`;
+  }
+  let actual;
+  try {
+    actual = hashCartridgeDirectory(versionDir);
+  } catch (e) {
+    return `failed to hash bundled provider 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`;
+}
+
+/**
+ * The identity a host accepts cartridges for. A cartridge whose cartridge.json
+ * diverges from this on channel, registry URL, registry scheme, or fabric
+ * manifest version is surfaced as incompatible — never hosted. Mirrors Rust
+ * DiscoveryIdentity.
+ */
+class DiscoveryIdentity {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.channel - A CartridgeChannel value.
+   * @param {string|null} opts.registryUrl - Some(url) for release/nightly
+   *   hosts, null for dev hosts.
+   * @param {number} opts.fabricManifestVersion
+   */
+  constructor({ channel, registryUrl, fabricManifestVersion }) {
+    if (channel !== CartridgeChannel.Release && channel !== CartridgeChannel.Nightly) {
+      throw new Error(`DiscoveryIdentity: invalid channel '${channel}'`);
+    }
+    this.channel = channel;
+    this.registryUrl = registryUrl !== undefined ? registryUrl : null;
+    this.fabricManifestVersion = fabricManifestVersion;
+  }
+
+  /** This host's own baked-registry slug (`dev` when registryUrl is null). */
+  slug() {
+    return slugForSync(this.registryUrl);
+  }
+}
+
+/**
+ * A discovered cartridge version directory, classified. Mirrors Rust
+ * DiscoveredCartridge — a tagged union with `kind` of `directory` (passed all
+ * checks and its HELLO probe succeeded) or `incompatible` (found on disk but
+ * failed a check; carries a structured `error`).
+ */
+class DiscoveredCartridge {
+  constructor(kind, fields) {
+    this.kind = kind; // 'directory' | 'incompatible'
+    Object.assign(this, fields);
+  }
+  static directory(fields) { return new DiscoveredCartridge('directory', fields); }
+  static incompatible(fields) { return new DiscoveredCartridge('incompatible', fields); }
+}
+
+/** Current wall-clock time as Unix seconds. A pre-epoch clock returns 0. */
+function unixSecondsNow() {
+  const s = Math.floor(Date.now() / 1000);
+  return s >= 0 ? s : 0;
+}
+
+// Default protocol limits / version, mirroring capdag::bifaci::frame.
+const BIFACI_PROTOCOL_VERSION = 2;
+const BIFACI_DEFAULT_MAX_FRAME = 3670016;
+const BIFACI_DEFAULT_MAX_CHUNK = 262144;
+const BIFACI_DEFAULT_MAX_REORDER_BUFFER = 64;
+const BIFACI_FRAME_TYPE_HELLO = 0;
+// Frame CBOR integer keys (capdag::bifaci::frame::keys).
+const BIFACI_KEY_VERSION = 0;
+const BIFACI_KEY_FRAME_TYPE = 1;
+const BIFACI_KEY_ID = 2;
+const BIFACI_KEY_SEQ = 3;
+const BIFACI_KEY_META = 5;
+
+/**
+ * Minimal CBOR encoder covering the value shapes the bifaci HELLO frame uses:
+ * unsigned/negative integers, byte strings, text strings, booleans, and maps.
+ * Faithful to RFC 8949 major-type encoding so the bytes are wire-compatible
+ * with the Rust `ciborium` encoder. Map keys are emitted in the order given.
+ *
+ * @param {*} value - One of: number (integer), {__bytes: Buffer}, string,
+ *   boolean, or {__map: [[key, val], ...]}.
+ * @returns {Buffer}
+ */
+function cborEncode(value) {
+  const out = [];
+  const pushTypeLen = (major, n) => {
+    const mt = major << 5;
+    if (n < 24) {
+      out.push(mt | n);
+    } else if (n < 0x100) {
+      out.push(mt | 24, n);
+    } else if (n < 0x10000) {
+      out.push(mt | 25, (n >> 8) & 0xff, n & 0xff);
+    } else if (n < 0x100000000) {
+      out.push(mt | 26, (n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff);
+    } else {
+      // 64-bit: split into high/low 32-bit halves.
+      const hi = Math.floor(n / 0x100000000);
+      const lo = n >>> 0;
+      out.push(mt | 27,
+        (hi >>> 24) & 0xff, (hi >>> 16) & 0xff, (hi >>> 8) & 0xff, hi & 0xff,
+        (lo >>> 24) & 0xff, (lo >>> 16) & 0xff, (lo >>> 8) & 0xff, lo & 0xff);
+    }
+  };
+  const enc = (v) => {
+    if (typeof v === 'number') {
+      if (!Number.isInteger(v)) throw new Error('cborEncode: only integers supported');
+      if (v >= 0) pushTypeLen(0, v);
+      else pushTypeLen(1, -v - 1);
+    } else if (typeof v === 'boolean') {
+      out.push(v ? 0xf5 : 0xf4);
+    } else if (typeof v === 'string') {
+      const buf = Buffer.from(v, 'utf8');
+      pushTypeLen(3, buf.length);
+      for (const b of buf) out.push(b);
+    } else if (v && v.__bytes !== undefined) {
+      const buf = Buffer.isBuffer(v.__bytes) ? v.__bytes : Buffer.from(v.__bytes);
+      pushTypeLen(2, buf.length);
+      for (const b of buf) out.push(b);
+    } else if (v && v.__map !== undefined) {
+      pushTypeLen(5, v.__map.length);
+      for (const [k, val] of v.__map) { enc(k); enc(val); }
+    } else {
+      throw new Error('cborEncode: unsupported value');
+    }
+  };
+  enc(value);
+  return Buffer.from(out);
+}
+
+/**
+ * Minimal CBOR decoder returning a JS view of the value. Integers → number,
+ * byte strings → {__bytes: Buffer}, text → string, bool → boolean, maps →
+ * Map. Sufficient to parse a bifaci HELLO response frame. Throws on
+ * unsupported/truncated input. Returns {value, offset}.
+ */
+function cborDecodeAt(buf, pos) {
+  if (pos >= buf.length) throw new Error('cbor: unexpected end');
+  const ib = buf[pos++];
+  const major = ib >> 5;
+  const minor = ib & 0x1f;
+  const readLen = () => {
+    if (minor < 24) return minor;
+    if (minor === 24) { return buf[pos++]; }
+    if (minor === 25) { const n = (buf[pos] << 8) | buf[pos + 1]; pos += 2; return n; }
+    if (minor === 26) { const n = (buf[pos] * 0x1000000) + (buf[pos + 1] << 16) + (buf[pos + 2] << 8) + buf[pos + 3]; pos += 4; return n; }
+    if (minor === 27) {
+      let n = 0;
+      for (let i = 0; i < 8; i++) { n = n * 256 + buf[pos++]; }
+      return n;
+    }
+    throw new Error('cbor: bad length encoding');
+  };
+  switch (major) {
+    case 0: { const n = readLen(); return { value: n, offset: pos }; }
+    case 1: { const n = readLen(); return { value: -1 - n, offset: pos }; }
+    case 2: { const len = readLen(); const b = buf.slice(pos, pos + len); pos += len; return { value: { __bytes: b }, offset: pos }; }
+    case 3: { const len = readLen(); const s = buf.slice(pos, pos + len).toString('utf8'); pos += len; return { value: s, offset: pos }; }
+    case 5: {
+      const len = readLen();
+      const m = new Map();
+      for (let i = 0; i < len; i++) {
+        const k = cborDecodeAt(buf, pos); pos = k.offset;
+        const v = cborDecodeAt(buf, pos); pos = v.offset;
+        m.set(k.value, v.value);
+      }
+      return { value: m, offset: pos };
+    }
+    case 7: {
+      if (minor === 20) return { value: false, offset: pos };
+      if (minor === 21) return { value: true, offset: pos };
+      if (minor === 22) return { value: null, offset: pos };
+      throw new Error('cbor: unsupported simple value');
+    }
+    default:
+      throw new Error(`cbor: unsupported major type ${major}`);
+  }
+}
+
+/**
+ * Encode the engine-side HELLO frame as a length-prefixed CBOR frame, exactly
+ * as capdag::bifaci::io::write_frame does: a 4-byte big-endian length prefix
+ * followed by the CBOR-encoded frame map. Mirrors Frame::hello with default
+ * Limits.
+ *
+ * @returns {Buffer}
+ */
+function encodeHelloFrame() {
+  const meta = {
+    __map: [
+      ['max_frame', BIFACI_DEFAULT_MAX_FRAME],
+      ['max_chunk', BIFACI_DEFAULT_MAX_CHUNK],
+      ['max_reorder_buffer', BIFACI_DEFAULT_MAX_REORDER_BUFFER],
+      ['version', BIFACI_PROTOCOL_VERSION],
+    ],
+  };
+  const frame = {
+    __map: [
+      [BIFACI_KEY_VERSION, BIFACI_PROTOCOL_VERSION],
+      [BIFACI_KEY_FRAME_TYPE, BIFACI_FRAME_TYPE_HELLO],
+      [BIFACI_KEY_ID, 0],
+      [BIFACI_KEY_SEQ, 0],
+      [BIFACI_KEY_META, meta],
+    ],
+  };
+  const body = cborEncode(frame);
+  const prefix = Buffer.alloc(4);
+  prefix.writeUInt32BE(body.length, 0);
+  return Buffer.concat([prefix, body]);
+}
+
+/**
+ * Probe a cartridge binary for its capability surface. Spawns the binary,
+ * performs the bifaci HELLO handshake (engine sends first), parses the
+ * manifest from the cartridge's HELLO response, then kills the process. A
+ * binary that fails to spawn, fails HELLO, or returns an unparseable manifest
+ * is an error — the caller surfaces it as HandshakeFailed.
+ *
+ * Mirrors capdag::cartridge_discovery::probe_cartridge_cap_groups. The handshake
+ * is the real length-prefixed CBOR frame exchange (capdag::bifaci::io); a
+ * non-bifaci binary closes its pipes without emitting a HELLO frame, so the
+ * read of the length-prefixed response hits EOF and the probe fails — exactly
+ * as it must.
+ *
+ * @param {string} entryPath - Absolute path to the entry binary.
+ * @returns {Promise<Array<Object>>} The manifest's cap_groups.
+ * @throws {Error} when the handshake/probe fails.
+ */
+function probeCartridgeCapGroups(entryPath) {
+  const { spawn } = require('child_process');
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(entryPath, [], { stdio: ['pipe', 'pipe', 'inherit'] });
+    } catch (e) {
+      reject(new Error(`Failed to spawn cartridge ${entryPath}: ${e.message}`));
+      return;
+    }
+
+    let settled = false;
+    let buf = Buffer.alloc(0);
+    let timer = null;
+
+    const finish = (err, value) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      try { child.kill('SIGKILL'); } catch (_e) { /* already gone */ }
+      if (err) reject(err); else resolve(value);
+    };
+
+    child.on('error', (e) => finish(new Error(`cartridge ${entryPath} spawn error: ${e.message}`)));
+    child.on('close', () => finish(new Error(`cartridge ${entryPath} HELLO failed: connection closed before receiving HELLO`)));
+
+    timer = setTimeout(() => finish(new Error(`cartridge ${entryPath} HELLO failed: timeout`)), 5000);
+
+    // Send our HELLO first (host side).
+    try {
+      child.stdin.write(encodeHelloFrame());
+    } catch (e) {
+      finish(new Error(`cartridge ${entryPath} HELLO failed: ${e.message}`));
+      return;
+    }
+
+    const tryParse = () => {
+      if (buf.length < 4) return;
+      const len = buf.readUInt32BE(0);
+      if (buf.length < 4 + len) return;
+      const body = buf.slice(4, 4 + len);
+      let decoded;
+      try {
+        decoded = cborDecodeAt(body, 0).value;
+      } catch (e) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: ${e.message}`));
+        return;
+      }
+      if (!(decoded instanceof Map)) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: expected frame map`));
+        return;
+      }
+      const frameType = decoded.get(BIFACI_KEY_FRAME_TYPE);
+      if (frameType !== BIFACI_FRAME_TYPE_HELLO) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: expected HELLO, got frame_type ${frameType}`));
+        return;
+      }
+      const meta = decoded.get(BIFACI_KEY_META);
+      const manifestVal = meta instanceof Map ? meta.get('manifest') : undefined;
+      if (!manifestVal || manifestVal.__bytes === undefined) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: Cartridge HELLO missing required manifest`));
+        return;
+      }
+      let manifest;
+      try {
+        manifest = JSON.parse(Buffer.from(manifestVal.__bytes).toString('utf8'));
+      } catch (e) {
+        finish(new Error(`cartridge ${entryPath} invalid manifest: ${e.message}`));
+        return;
+      }
+      finish(null, Array.isArray(manifest.cap_groups) ? manifest.cap_groups : []);
+    };
+
+    child.stdout.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      tryParse();
+    });
+  });
+}
+
+/**
+ * Discover every cartridge under `{cartridgesRoot}/{slug}/{channel}/`. Scans
+ * EVERY slug folder present on disk (full parity) — the host's baked
+ * `identity.registryUrl` does NOT restrict which slugs are scanned; each
+ * cartridge is validated in place against the slug folder it sits under (the
+ * three-place rule in `CartridgeJson.readFromDir`). The channel folder IS
+ * pinned to the host's channel. An empty/absent scan root yields an empty
+ * roster; a real IO failure reading an existing root is an error.
+ *
+ * Mirrors capdag::cartridge_discovery::discover_cartridges.
+ *
+ * @param {string} cartridgesRoot
+ * @param {DiscoveryIdentity} identity
+ * @returns {Promise<Array<DiscoveredCartridge>>}
+ */
+async function discoverCartridges(cartridgesRoot, identity) {
+  const fs = require('fs');
+  const path = require('path');
+  const discovered = [];
+
+  let rootStat;
+  try { rootStat = fs.statSync(cartridgesRoot); } catch (_e) { return discovered; }
+  if (!rootStat.isDirectory()) return discovered;
+
+  let slugEntries;
+  try {
+    slugEntries = fs.readdirSync(cartridgesRoot, { withFileTypes: true });
+  } catch (e) {
+    throw new Error(`read_dir(${cartridgesRoot}): ${e.message}`);
+  }
+
+  for (const slugEntry of slugEntries) {
+    const slugDir = path.join(cartridgesRoot, slugEntry.name);
+    if (!slugEntry.isDirectory()) {
+      // Unmanaged file in cartridges root — only registry-slug / dev
+      // directories belong here. Skipped (logged in the reference).
+      continue;
+    }
+    const expectedSlug = slugEntry.name;
+    const scanRoot = path.join(slugDir, identity.channel);
+    let scanStat;
+    try { scanStat = fs.statSync(scanRoot); } catch (_e) { continue; }
+    if (!scanStat.isDirectory()) continue;
+    await scanChannelRoot(scanRoot, expectedSlug, identity, discovered);
+  }
+
+  return discovered;
+}
+
+/**
+ * Scan one `{slug}/{channel}/` root: classify each cartridge name directory's
+ * newest version against the host identity and the slug folder it sits under.
+ * Mirrors capdag::cartridge_discovery::scan_channel_root.
+ */
+async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
+  const fs = require('fs');
+  const path = require('path');
+
+  let nameEntries;
+  try {
+    nameEntries = fs.readdirSync(scanRoot, { withFileTypes: true });
+  } catch (e) {
+    throw new Error(`read_dir(${scanRoot}): ${e.message}`);
+  }
+
+  for (const entry of nameEntries) {
+    const nameDir = path.join(scanRoot, entry.name);
+    if (!entry.isDirectory()) continue;
+
+    let subEntries;
+    try {
+      subEntries = fs.readdirSync(nameDir, { withFileTypes: true });
+    } catch (_e) {
+      continue;
+    }
+
+    const versionDirs = [];
+    for (const sub of subEntries) {
+      if (sub.isDirectory()) versionDirs.push(path.join(nameDir, sub.name));
+    }
+    if (versionDirs.length === 0) continue;
+
+    // Prefer the newest version (lexical-descending on the version folder name).
+    versionDirs.sort((a, b) => {
+      const va = path.basename(a);
+      const vb = path.basename(b);
+      return vb < va ? -1 : vb > va ? 1 : 0;
+    });
+    const versionDir = versionDirs[0];
+
+    const pathDerivedName = path.basename(nameDir);
+    const pathDerivedVersion = path.basename(versionDir);
+    const detectedAt = unixSecondsNow();
+
+    // read_from_dir enforces the three-place rule against the ACTUAL slug
+    // folder (expectedSlug): the cartridge's declared registry_url must hash
+    // to it. A slug mismatch is a BadInstallation; an unreadable/garbage
+    // cartridge.json is ManifestInvalid. Both surfaced, never hosted.
+    let cj;
+    try {
+      cj = CartridgeJson.readFromDir(versionDir, expectedSlug);
+    } catch (e) {
+      const kind = (e instanceof CartridgeJsonError && e.kind === CartridgeJsonErrorKind.REGISTRY_SLUG_MISMATCH)
+        ? CartridgeAttachmentErrorKind.BAD_INSTALLATION
+        : CartridgeAttachmentErrorKind.MANIFEST_INVALID;
+      discovered.push(DiscoveredCartridge.incompatible({
+        version_dir: versionDir,
+        id: pathDerivedName,
+        channel: identity.channel,
+        registry_url: identity.registryUrl,
+        version: pathDerivedVersion,
+        error: new CartridgeAttachmentError(
+          kind,
+          `cartridge.json failed to load under slug '${expectedSlug}': ${e.message}`,
+          detectedAt
+        ),
+      }));
+      continue;
+    }
+
+    if (cj.channel !== identity.channel) {
+      discovered.push(DiscoveredCartridge.incompatible({
+        version_dir: versionDir,
+        id: cj.name,
+        channel: cj.channel,
+        registry_url: cj.registryUrl,
+        version: cj.version,
+        error: new CartridgeAttachmentError(
+          CartridgeAttachmentErrorKind.BAD_INSTALLATION,
+          `Channel mismatch: cartridge declares '${cj.channel}' but host is pinned to '${identity.channel}'. Release and nightly artefacts must not mix.`,
+          detectedAt
+        ),
+      }));
+      continue;
+    }
+
+    // Scheme check is per-cartridge: a dev cartridge (null registry_url) never
+    // reaches here; a registry cartridge must use https (devMode=false).
+    if (cj.registryUrl !== null && cj.registryUrl !== undefined) {
+      const res = validateRegistryUrlScheme(cj.registryUrl, false);
+      if (res.kind === RegistryUrlSchemeResultKind.NON_HTTPS) {
+        discovered.push(DiscoveredCartridge.incompatible({
+          version_dir: versionDir,
+          id: cj.name,
+          channel: cj.channel,
+          registry_url: cj.registryUrl,
+          version: cj.version,
+          error: new CartridgeAttachmentError(
+            CartridgeAttachmentErrorKind.INCOMPATIBLE,
+            `registry_url uses '${res.scheme}' scheme, must be https in non-dev builds. Rebuild the cartridge with an https registry URL.`,
+            detectedAt
+          ),
+        }));
+        continue;
+      }
+      if (res.kind === RegistryUrlSchemeResultKind.NOT_A_URL) {
+        discovered.push(DiscoveredCartridge.incompatible({
+          version_dir: versionDir,
+          id: cj.name,
+          channel: cj.channel,
+          registry_url: cj.registryUrl,
+          version: cj.version,
+          error: new CartridgeAttachmentError(
+            CartridgeAttachmentErrorKind.INCOMPATIBLE,
+            `registry_url '${res.url}' is not a well-formed URL.`,
+            detectedAt
+          ),
+        }));
+        continue;
+      }
+    }
+
+    if (cj.fabricManifestVersion !== identity.fabricManifestVersion) {
+      discovered.push(DiscoveredCartridge.incompatible({
+        version_dir: versionDir,
+        id: cj.name,
+        channel: cj.channel,
+        registry_url: cj.registryUrl,
+        version: cj.version,
+        error: new CartridgeAttachmentError(
+          CartridgeAttachmentErrorKind.FABRIC_MANIFEST_VERSION_MISMATCH,
+          `Cartridge built against fabric manifest version ${cj.fabricManifestVersion}, but host is pinned to ${identity.fabricManifestVersion}. Rebuild the cartridge with MFR_FABRIC_MANIFEST_VERSION=${identity.fabricManifestVersion}.`,
+          detectedAt
+        ),
+      }));
+      continue;
+    }
+
+    // Bundled-provider 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
+    // skipped); on non-macOS the on-disk directory must hash to the baked
+    // value, else BadInstallation.
+    if (cj.installedFrom === CartridgeInstallSource.BUNDLE) {
+      if (process.platform !== 'darwin') {
+        const reason = verifyBundledProviderHash(cj.name, cj.version, versionDir);
+        if (reason !== null) {
+          discovered.push(DiscoveredCartridge.incompatible({
+            version_dir: versionDir,
+            id: cj.name,
+            channel: cj.channel,
+            registry_url: cj.registryUrl,
+            version: cj.version,
+            error: new CartridgeAttachmentError(
+              CartridgeAttachmentErrorKind.BAD_INSTALLATION,
+              `bundled provider integrity check failed: ${reason}`,
+              detectedAt
+            ),
+          }));
+          continue;
+        }
+      }
+    }
+
+    const entryPoint = cj.resolveEntryPoint(versionDir);
+    try {
+      const capGroups = await probeCartridgeCapGroups(entryPoint);
+      discovered.push(DiscoveredCartridge.directory({
+        entry_point: entryPoint,
+        version_dir: versionDir,
+        id: cj.name,
+        channel: cj.channel,
+        registry_url: cj.registryUrl,
+        version: cj.version,
+        cap_groups: capGroups,
+      }));
+    } catch (e) {
+      discovered.push(DiscoveredCartridge.incompatible({
+        version_dir: versionDir,
+        id: cj.name,
+        channel: cj.channel,
+        registry_url: cj.registryUrl,
+        version: cj.version,
+        error: new CartridgeAttachmentError(
+          CartridgeAttachmentErrorKind.HANDSHAKE_FAILED,
+          `HELLO handshake / cap discovery probe failed: ${e.message}`,
+          detectedAt
+        ),
+      }));
+    }
+  }
+}
+
 // ============================================================================
 // Machine Notation — compact, round-trippable DAG path identifiers
 //
@@ -6416,7 +7590,7 @@ module.exports = {
   MEDIA_OBJECT,
   // List types
   MEDIA_LIST,
-  MEDIA_TEXTABLE_LIST,
+  MEDIA_TEXTABLE_LIST: MEDIA_STRING_LIST,
   MEDIA_STRING_LIST,
   MEDIA_INTEGER_LIST,
   MEDIA_NUMBER_LIST,
@@ -6540,6 +7714,28 @@ module.exports = {
   CartridgeAttachmentError,
   CartridgeRuntimeStats,
   InstalledCartridgeRecord,
+  // Host-compatibility resolution
+  hostPlatform,
+  CompatStatus,
+  primaryPackage,
+  CartridgeCompatibilityResolution,
+  // Build-env registry identity
+  registryUrlFromBuildEnv,
+  // Cartridge discovery
+  slugForSync,
+  CartridgeInstallSource,
+  RegistryUrlSchemeResultKind,
+  validateRegistryUrlScheme,
+  CartridgeJsonErrorKind,
+  CartridgeJsonError,
+  CartridgeJson,
+  hashCartridgeDirectory,
+  BUNDLED_PROVIDER_HASHES,
+  verifyBundledProviderHash,
+  DiscoveryIdentity,
+  DiscoveredCartridge,
+  probeCartridgeCapGroups,
+  discoverCartridges,
   // Registry slug
   DEV_SLUG,
   SLUG_HEX_LEN,