capdag 1.249.12 → 1.266.66

package/README.md

@@ -1,131 +1,64 @@
-# Cap URN - JavaScript Implementation
+# CapDAG for JavaScript
 
-JavaScript implementation of Cap URN (Capability Uniform Resource Names), built on [Tagged URN](https://github.com/machinefabric/tagged-urn-js).
+This public package is CapDAG's JavaScript planning and notation mirror. Use it
+in browsers or Node.js for Tagged, Media, and Cap URNs, capability definitions,
+dispatch, Machine Notation, planning, and graph rendering.
 
-## Features
+JavaScript intentionally does not implement the cartridge runtime, host, relay,
+or Bifaci process surface. That boundary is part of the package design, not an
+unreported parity gap. Rust remains the behavioral reference for shared
+features.
 
-- **Required Direction Specifiers** - `in`/`out` tags for input/output media types
-- **Media URN Validation** - Validates direction spec values are valid Media URNs
-- **Special Pattern Values** - `*` (must-have-any), `?` (unspecified), `!` (must-not-have)
-- **Graded Specificity** - Exact values score higher than wildcards
-- **Cross-Language Compatible** - Identical behavior to Rust, Go, and Objective-C implementations
-- **Production Ready** - No fallbacks, fails hard on invalid input
-
-## Installation
+## Install the package
 
 ```bash
 npm install capdag
 ```
 
-## Quick Start
+Node.js 14 or newer is required by the package manifest.
 
-```javascript
-const { CapUrn, CapUrnBuilder, CapMatcher } = require('capdag');
+## Parse and build Cap URNs
 
-// Create from string (with required direction specifiers)
-const cap = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
-console.log(cap.toString());
+```javascript
+const { CapUrn, CapUrnBuilder } = require("capdag");
 
-// Use builder pattern
+const parsed = CapUrn.fromString(
+  'cap:disbind;in="media:ext=pdf";out="media:enc=utf-8;page"'
+);
 const built = new CapUrnBuilder()
-  .inSpec('media:void')
-  .outSpec('media:object')
-  .tag('op', 'generate')
-  .tag('target', 'thumbnail')
-  .build();
-
-// Matching
-const request = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
-console.log(cap.accepts(request)); // true
-
-// Find best match by specificity
-const caps = [
-  CapUrn.fromString('cap:in=*;extract;out=*'),
-  CapUrn.fromString('cap:in="media:binary";extract;out="media:object"'),
-  CapUrn.fromString('cap:ext=pdf;in="media:binary";extract;out="media:object"')
-];
-const best = CapMatcher.findBestMatch(caps, request);
-console.log(best.toString()); // Most specific match
-```
-
-## API Reference
-
-### CapUrn Class
-
-#### Static Methods
-- `CapUrn.fromString(s)` - Parse Cap URN from string
-  - Throws `CapUrnError` on invalid format or missing direction specifiers
-
-#### Instance Methods
-- `toString()` - Get canonical string representation
-- `getTag(key)` - Get tag value (case-insensitive)
-- `getInSpec()` - Get input media type
-- `getOutSpec()` - Get output media type
-- `hasTag(key, value)` - Check if tag exists with value
-- `withTag(key, value)` - Add/update tag (returns new instance)
-- `withoutTag(key)` - Remove tag (returns new instance)
-- `accepts(request)` - Check if this cap (as pattern) accepts a request
-- `specificity()` - Get specificity score for matching
-- `isMoreSpecificThan(other)` - Compare specificity
-- `equals(other)` - Check equality
-
-### CapUrnBuilder Class
-
-Fluent builder for constructing Cap URNs:
-
-```javascript
-const cap = new CapUrnBuilder()
-  .inSpec('media:binary')
-  .outSpec('media:object')
-  .tag('op', 'extract')
-  .tag('target', 'metadata')
+  .inSpec("media:ext=pdf")
+  .outSpec("media:enc=utf-8;page")
+  .marker("disbind")
   .build();
-```
 
-### CapMatcher Class
-
-Utility for matching sets of caps:
-
-- `CapMatcher.findBestMatch(caps, request)` - Find most specific match
-- `CapMatcher.findAllMatches(caps, request)` - Find all matches (sorted by specificity)
-
-### Error Handling
-
-```javascript
-const { CapUrnError, ErrorCodes } = require('capdag');
-
-try {
-  const cap = CapUrn.fromString('cap:extract;in=media:;out=media:'); // Missing in/out
-} catch (error) {
-  if (error instanceof CapUrnError) {
-    console.log(`Error code: ${error.code}`); // MISSING_IN_SPEC
-  }
-}
+console.log(parsed.toString() === built.toString());
 ```
 
-Cap-specific error codes:
-- `ErrorCodes.MISSING_IN_SPEC` - Missing required `in` tag
-- `ErrorCodes.MISSING_OUT_SPEC` - Missing required `out` tag
-- `ErrorCodes.INVALID_MEDIA_URN` - Invalid Media URN in direction spec
+Treat URNs as opaque parsed values. Use the package's predicates for
+equivalence, conformance, dispatch, and ranking instead of string surgery.
 
-For base Tagged URN error codes, see [Tagged URN documentation](https://github.com/machinefabric/tagged-urn-js).
+## Find the relevant API
 
-## Documentation
+- `capdag.js` provides URNs, definitions, dispatch, and matching.
+- `machine-parser.js` is generated from `machine.pegjs`.
+- `planner.js` provides planning and Machine Notation structures.
+- `cap-fab-renderer.js` and the browser build support graph presentation.
+- [`RULES.md`](RULES.md) records package-specific construction rules.
 
-- [RULES.md](./RULES.md) - Cap-specific rules
-- [Tagged URN RULES.md](https://github.com/machinefabric/tagged-urn-js/blob/main/RULES.md) - Base format rules (case, quoting, wildcards, etc.)
+The normative semantics and terminology live in the
+[CapDAG specification](https://github.com/machinefabric/capdag/blob/main/docs/01-overview.md). Source comments and
+exports are the JavaScript API reference.
 
-## Testing
+## Build and verify changes
 
 ```bash
+npm run build:parser
 npm test
 ```
 
-## Cross-Language Compatibility
+`npm test` runs the parser build first. Shared behavior changes require the
+applicable reference test with the same substantive number and assertions.
 
-This JavaScript implementation produces identical results to:
-- [Rust reference implementation](https://github.com/machinefabric/capdag)
-- [Go implementation](https://github.com/machinefabric/capdag-go)
-- [Objective-C implementation](https://github.com/machinefabric/capdag-objc)
+## License
 
-All implementations pass the same test cases and follow identical rules.
+MIT

package/build-browser.js

@@ -6,7 +6,7 @@
 //
 // The browser build exists because capdag-js source files are CJS:
 // they use `require()` and `module.exports`, which a plain <script tag>
-// cannot load. For browser consumers (capdag-dot-com, machfab-mac
+// cannot load. For browser consumers (capdag-dot-com, macfloom
 // WKWebViews) we strip those CJS hooks and wrap the result in an IIFE
 // that assigns to window.*.
 //

package/cap-fab-renderer.js

@@ -2234,8 +2234,7 @@ function buildRunGraphData(data) {
     };
   }
 
-  // Expanding. The plan mirrors the working
-  // `machfab-mac/.scrap/working_graph/.../RunGraphViewer.html`:
+  // Expanding. The plan uses the renderer's established fan-out layout:
   //
   //   pre-foreach backbone ... → [anchor]
   //                                 │
@@ -2448,7 +2447,7 @@ function buildRunGraphData(data) {
 
     // Successful bodies merge into the collect target ONLY when a
     // Collect closes the foreach body. Without a Collect (the
-    // common "unclosed foreach" case in machfab realize_strand),
+    // common "unclosed foreach" case in floom-engine realize_strand),
     // replicas terminate at their last body step — each body has
     // its own separate output, no shared merge.
     if (success && hasCollect && collectTargetId) {

package/capdag.js

@@ -2455,6 +2455,21 @@ class ArgSource {
   }
 }
 
+/** The definition's argument keys — what every capdag mirror's CapArg carries. */
+const CAP_ARG_KEYS = Object.freeze(['media_urn', 'required', 'sources', 'arg_description', 'default_value', 'metadata', 'is_sequence', 'streaming']);
+/** The definition's output keys — what every capdag mirror's CapOutput carries. */
+const CAP_OUTPUT_KEYS = Object.freeze(['media_urn', 'output_description', 'metadata', 'is_sequence', 'streaming']);
+
+function refuseUnknownDefinitionKeys(json, known, what) {
+  const unknown = Object.keys(json).filter(key => !known.includes(key)).sort();
+  if (unknown.length > 0) {
+    throw new Error(
+      `${what} carries field(s) this capdag does not know: ${unknown.join(', ')} — ` +
+      `the definition comes from a fabric newer than this capdag; the contract is ${known.join(', ')}`
+    );
+  }
+}
+
 /**
  * Cap argument definition - media_urn is the unique identifier
  */
@@ -2470,6 +2485,11 @@ class CapArg {
     this.media_urn = mediaUrn;
     this.required = required;
     this.is_sequence = options.is_sequence || false;
+    // Consumed WITHOUT a length promise (a feed): the cap processes items as
+    // they arrive and may be wired live to an unbounded producer. Orthogonal
+    // to is_sequence (cardinality), not part of the URN. Only the main input
+    // may stream (RULE14).
+    this.streaming = options.streaming || false;
     this.sources = sources;  // Array of ArgSource
     this.arg_description = options.arg_description !== undefined ? options.arg_description : null;
     this.default_value = options.default_value !== undefined ? options.default_value : null;
@@ -2482,6 +2502,12 @@ class CapArg {
    * @returns {CapArg} The CapArg instance
    */
   static fromJSON(json) {
+    // A key this definition does not know is a fabric NEWER than this
+    // capdag — a contract this build cannot honour. Dropping it would let a
+    // cartridge advertise a contract the fabric never made (this is how a
+    // `streaming` argument once went out as bounded); it is refused, named.
+    // Mirrors Rust `deny_unknown_fields`.
+    refuseUnknownDefinitionKeys(json, CAP_ARG_KEYS, 'cap argument');
     const sources = (json.sources || []).map(s => ArgSource.fromJSON(s));
     return new CapArg(
       json.media_urn,
@@ -2489,6 +2515,7 @@ class CapArg {
       sources,
       {
         is_sequence: json.is_sequence,
+        streaming: json.streaming,
         arg_description: json.arg_description,
         default_value: json.default_value,
         metadata: json.metadata
@@ -2507,6 +2534,7 @@ class CapArg {
       sources: this.sources.map(s => s.toJSON())
     };
     if (this.is_sequence) result.is_sequence = true;
+    if (this.streaming) result.streaming = true;
     if (this.arg_description !== null && this.arg_description !== undefined) {
       result.arg_description = this.arg_description;
     }
@@ -2934,6 +2962,9 @@ class Cap {
     } else {
       cap.args = [];
     }
+    if (json.output !== undefined && json.output !== null) {
+      refuseUnknownDefinitionKeys(json.output, CAP_OUTPUT_KEYS, 'cap output');
+    }
     cap.output = json.output;
     cap.registered_by = json.registered_by ? RegisteredBy.fromJSON(json.registered_by) : null;
     cap.supported_model_types = Array.isArray(json.supported_model_types) ? json.supported_model_types : [];
@@ -3333,6 +3364,19 @@ function validateCapArgs(cap) {
     });
   }
 
+  // RULE14: Only the main input may stream. `streaming: true` declares that
+  // an argument is consumed without a length promise — a feed. Side
+  // arguments (options, model specs, prompts alongside the main input) are
+  // values the runtime demuxes whole; a feed there has no meaning and would
+  // let an unbounded stream reach a collector that must refuse it (L16).
+  for (const arg of args) {
+    if (arg.streaming && !arg.isMainInput(inMediaUrn)) {
+      throw new ValidationError('InvalidCapSchema', capUrn, {
+        issue: `RULE14: Argument '${arg.media_urn}' declares streaming=true but is not the main input (no stdin source equivalent to in='${cap.urn.getInSpec()}') — only the main input may be consumed without a length promise`
+      });
+    }
+  }
+
   // RULE5: No two args may have same position
   const positionSet = new Set();
   for (const { position, mediaUrn } of positions) {
@@ -5372,6 +5416,320 @@ const CartridgeLifecycle = Object.freeze({
   OPERATIONAL: 'operational',
 });
 
+/**
+ * Format discriminator for release-key certificates.
+ * Mirrors Rust `RELEASE_KEY_CERT_FORMAT` (bifaci/release_cert.rs).
+ *
+ * THE WIRE FORMAT IS NOT A PRODUCT NAME. Every verifier — this library, the
+ * desktop clients' in-process verifiers, the publisher — must compare against
+ * THIS constant. A client that keeps its own copy can be renamed away from the
+ * protocol by a search-and-replace, verify nothing, and report the registry as
+ * unreachable; that is exactly what happened, and it is why these live here.
+ */
+const RELEASE_KEY_CERT_FORMAT = 'machinefabric-release-key-cert/1';
+
+/** Format discriminator for manifest signature envelopes.
+ *  Mirrors Rust `MANIFEST_SIG_FORMAT`. */
+const MANIFEST_SIG_FORMAT = 'machinefabric-manifest-sig/1';
+
+/**
+ * What a consumer concluded about a cartridge registry.
+ * Mirrors Rust `RegistryVerdictState` (bifaci/registry_verdict.rs).
+ *
+ * A REGISTRY IS NOT A CARTRIDGE: this is one fact per registry URL, shared by
+ * every cartridge that claims provenance from it. The vocabulary separates the
+ * two things a consumer can conclude — that it could not get an answer
+ * (OFFLINE, UNREACHABLE, HTTP_ERROR, MALFORMED) and that it got one and refused
+ * it (UNSIGNED, UNTRUSTED, UNVERIFIABLE) — because those have opposite
+ * remedies.
+ */
+const RegistryVerdictState = Object.freeze({
+  // Fetched, chain-verified and parsed. The only state that lets a cartridge
+  // from this registry attach.
+  VERIFIED: 'verified',
+  // No verdict yet — the first check has not run. NOT a failure.
+  PENDING: 'pending',
+  // The consumer's own network policy forbade the request. The remedy is a
+  // setting, not the network.
+  OFFLINE: 'offline',
+  // DNS, refused, timeout, TLS. The only state where "check your connection"
+  // is sound advice.
+  UNREACHABLE: 'unreachable',
+  // The registry answered with an HTTP error; the status travels with it.
+  HTTP_ERROR: 'http_error',
+  // The registry answered with a body this build cannot read as a manifest.
+  MALFORMED: 'malformed',
+  // No signature sidecar where one is required.
+  UNSIGNED: 'unsigned',
+  // The chain was evaluated and REJECTED — the registry's problem.
+  UNTRUSTED: 'untrusted',
+  // The chain could NOT be evaluated: a format this build does not implement.
+  // Our problem, remedied by updating the client — never by distrusting the
+  // registry, and never by checking the network.
+  UNVERIFIABLE: 'unverifiable',
+  // This build bakes no trust anchors, so there is no regime to verify against
+  // and the manifest was accepted without proof. A development build, and only
+  // ever that. It permits attachment — a dev build has to work — and is a
+  // SEPARATE state rather than being reported as VERIFIED, because "we checked
+  // and it passed" and "we did not check" are different facts.
+  UNENFORCED: 'unenforced',
+});
+
+/**
+ * WHAT TO DO ABOUT A REGISTRY IN A GIVEN STATE. Mirrors Rust `RegistryRemedy`.
+ *
+ * The remedy follows from the state and nothing else. It used to be a sentence
+ * glued onto the failure message at the point the record was built — "Check the
+ * network connection and try again." — appended whatever the cause, so a
+ * signature a build could not read sent operators to their router. A remedy
+ * asserted as fact regardless of what failed is worse than none.
+ *
+ * This is the ACTION, not its wording: a CLI prints a line, a desktop client
+ * offers a control. Both derive them from here.
+ */
+const RegistryRemedy = Object.freeze({
+  // Nothing to do — the registry verified.
+  NONE: 'none',
+  // A check is in flight and will answer on its own.
+  WAIT: 'wait',
+  // The machine cannot reach the registry. Check the connection.
+  CHECK_NETWORK: 'check_network',
+  // This build was told not to go out. Change the network policy.
+  CHANGE_NETWORK_POLICY: 'change_network_policy',
+  // The registry answered badly; it is the registry's side to fix.
+  RETRY_LATER: 'retry_later',
+  // This build cannot read the registry's signature format. Update the client —
+  // the registry is not at fault and the network is not involved.
+  UPDATE_CLIENT: 'update_client',
+  // The registry's answer was rejected. Do not proceed.
+  DO_NOT_PROCEED: 'do_not_proceed',
+});
+
+const _REGISTRY_REMEDY_BY_STATE = Object.freeze({
+  verified: RegistryRemedy.NONE,
+  pending: RegistryRemedy.WAIT,
+  offline: RegistryRemedy.CHANGE_NETWORK_POLICY,
+  unreachable: RegistryRemedy.CHECK_NETWORK,
+  http_error: RegistryRemedy.RETRY_LATER,
+  malformed: RegistryRemedy.RETRY_LATER,
+  unsigned: RegistryRemedy.DO_NOT_PROCEED,
+  untrusted: RegistryRemedy.DO_NOT_PROCEED,
+  unverifiable: RegistryRemedy.UPDATE_CLIENT,
+  unenforced: RegistryRemedy.NONE,
+});
+
+/** The one thing to do about a registry in this state. */
+function registryVerdictRemedy(state) {
+  const remedy = _REGISTRY_REMEDY_BY_STATE[state];
+  if (remedy === undefined) {
+    throw new Error(`unknown registry verdict state '${state}'`);
+  }
+  return remedy;
+}
+
+/** Why a signature chain failed. Mirrors Rust `ChainFailureReason`. */
+const ChainFailureReason = Object.freeze({
+  MALFORMED_ENVELOPE: 'malformed_envelope',
+  UNSUPPORTED_ENVELOPE_FORMAT: 'unsupported_envelope_format',
+  MALFORMED_CERTIFICATE: 'malformed_certificate',
+  UNSUPPORTED_CERTIFICATE_FORMAT: 'unsupported_certificate_format',
+  EMPTY_CERTIFICATE_LIST: 'empty_certificate_list',
+  INSUFFICIENT_ROOT_SIGNATURES: 'insufficient_root_signatures',
+  EXPIRED_CERTIFICATE: 'expired_certificate',
+  NOT_YET_VALID_CERTIFICATE: 'not_yet_valid_certificate',
+  ENVIRONMENT_MISMATCH: 'environment_mismatch',
+  KEY_ID_MISMATCH: 'key_id_mismatch',
+  NO_AUTHORIZING_CERTIFICATE: 'no_authorizing_certificate',
+  MANIFEST_SIGNATURE_INVALID: 'manifest_signature_invalid',
+});
+
+const REGISTRY_VERDICT_STATES = Object.freeze(Object.values(RegistryVerdictState));
+const CHAIN_FAILURE_REASONS = Object.freeze(Object.values(ChainFailureReason));
+
+/** The reasons that mean the chain could not be EVALUATED, as opposed to being
+ *  evaluated and rejected. */
+const UNEVALUABLE_CHAIN_FAILURES = Object.freeze([
+  ChainFailureReason.MALFORMED_ENVELOPE,
+  ChainFailureReason.UNSUPPORTED_ENVELOPE_FORMAT,
+  ChainFailureReason.MALFORMED_CERTIFICATE,
+  ChainFailureReason.UNSUPPORTED_CERTIFICATE_FORMAT,
+  ChainFailureReason.EMPTY_CERTIFICATE_LIST,
+]);
+
+/**
+ * The verdict a chain failure produces.
+ *
+ * Could the chain be evaluated at all? A format this build does not implement
+ * means no judgement was reached (UNVERIFIABLE — update the client). Anything
+ * else means the chain WAS judged and found wanting (UNTRUSTED — do not
+ * proceed). Leaving this decision to each consumer is how one client reported
+ * an unreadable signature format as a network outage.
+ */
+function registryVerdictStateForChainFailure(reason) {
+  if (!CHAIN_FAILURE_REASONS.includes(reason)) {
+    throw new Error(`unknown chain failure reason '${reason}'`);
+  }
+  return UNEVALUABLE_CHAIN_FAILURES.includes(reason)
+    ? RegistryVerdictState.UNVERIFIABLE
+    : RegistryVerdictState.UNTRUSTED;
+}
+
+/** Whether a cartridge from a registry in this state may attach. */
+function registryVerdictPermitsAttachment(state) {
+  if (!REGISTRY_VERDICT_STATES.includes(state)) {
+    throw new Error(`unknown registry verdict state '${state}'`);
+  }
+  return state === RegistryVerdictState.VERIFIED || state === RegistryVerdictState.UNENFORCED;
+}
+
+/** Whether the state is a refusal of an answer we DID get. Never changes on retry. */
+function registryVerdictIsTrustFailure(state) {
+  if (!REGISTRY_VERDICT_STATES.includes(state)) {
+    throw new Error(`unknown registry verdict state '${state}'`);
+  }
+  return state === RegistryVerdictState.UNSIGNED
+    || state === RegistryVerdictState.UNTRUSTED
+    || state === RegistryVerdictState.UNVERIFIABLE;
+}
+
+/** Whether an unattended retry could plausibly reach a different verdict. */
+function registryVerdictIsTransient(state) {
+  if (!REGISTRY_VERDICT_STATES.includes(state)) {
+    throw new Error(`unknown registry verdict state '${state}'`);
+  }
+  return state === RegistryVerdictState.PENDING
+    || state === RegistryVerdictState.UNREACHABLE
+    || state === RegistryVerdictState.HTTP_ERROR
+    || state === RegistryVerdictState.MALFORMED;
+}
+
+/**
+ * What a consumer concluded about one registry, and why.
+ * Mirrors Rust `RegistryVerdict`.
+ *
+ * Illegal combinations are unrepresentable: the constructors take exactly what
+ * their state requires and `validate()` refuses every contradiction, so a
+ * verdict that says "http_error" without a status, or "verified" with a failure
+ * detail, is refused at the boundary instead of rendered as a contradiction.
+ */
+class RegistryVerdict {
+  constructor(registryUrl, state, detail, httpStatus, chainFailure, checkedAtUnixSeconds) {
+    this.registry_url = registryUrl;
+    this.state = state;
+    this.detail = detail;
+    this.http_status = httpStatus === undefined ? null : httpStatus;
+    this.chain_failure = chainFailure === undefined ? null : chainFailure;
+    this.checked_at_unix_seconds = checkedAtUnixSeconds;
+    this.validate();
+  }
+
+  static verified(registryUrl, checkedAtUnixSeconds) {
+    return new RegistryVerdict(registryUrl, RegistryVerdictState.VERIFIED, '', null, null, checkedAtUnixSeconds);
+  }
+
+  /** This build bakes no trust anchors: the manifest was accepted without
+   *  proof, and says so rather than claiming it verified. */
+  static unenforced(registryUrl, checkedAtUnixSeconds) {
+    return new RegistryVerdict(registryUrl, RegistryVerdictState.UNENFORCED, '', null, null, checkedAtUnixSeconds);
+  }
+
+  /** No verdict yet. Carries no time, because nothing has been checked. */
+  static pending(registryUrl) {
+    return new RegistryVerdict(registryUrl, RegistryVerdictState.PENDING, '', null, null, 0);
+  }
+
+  /** A state carrying only a detail line: OFFLINE, UNREACHABLE, MALFORMED, UNSIGNED. */
+  static stated(registryUrl, state, detail, checkedAtUnixSeconds) {
+    return new RegistryVerdict(registryUrl, state, detail, null, null, checkedAtUnixSeconds);
+  }
+
+  static httpError(registryUrl, status, detail, checkedAtUnixSeconds) {
+    return new RegistryVerdict(registryUrl, RegistryVerdictState.HTTP_ERROR, detail, status, null, checkedAtUnixSeconds);
+  }
+
+  /** A signature chain that failed. The state FOLLOWS from the reason, so a
+   *  caller cannot file an unreadable format as a rejected key. */
+  static chainFailed(registryUrl, reason, detail, checkedAtUnixSeconds) {
+    return new RegistryVerdict(
+      registryUrl,
+      registryVerdictStateForChainFailure(reason),
+      detail,
+      null,
+      reason,
+      checkedAtUnixSeconds,
+    );
+  }
+
+  validate() {
+    if (typeof this.registry_url !== 'string' || this.registry_url.length === 0) {
+      throw new Error('a registry verdict must name the registry it is about');
+    }
+    if (!REGISTRY_VERDICT_STATES.includes(this.state)) {
+      throw new Error(`unknown registry verdict state '${this.state}'`);
+    }
+    if (typeof this.detail !== 'string') {
+      throw new Error('a registry verdict detail must be a string');
+    }
+    const statesNoFailure = this.state === RegistryVerdictState.VERIFIED
+      || this.state === RegistryVerdictState.PENDING
+      || this.state === RegistryVerdictState.UNENFORCED;
+    if (statesNoFailure && this.detail.length > 0) {
+      throw new Error(`a '${this.state}' verdict states no failure, so it carries no detail (got ${JSON.stringify(this.detail)})`);
+    }
+    if (!statesNoFailure && this.detail.length === 0) {
+      throw new Error(`a '${this.state}' verdict must carry the detail that explains it`);
+    }
+    if (this.state === RegistryVerdictState.HTTP_ERROR) {
+      if (!Number.isInteger(this.http_status)) {
+        throw new Error("an 'http_error' verdict must carry the status the registry answered with");
+      }
+    } else if (this.http_status !== null) {
+      throw new Error(`only an 'http_error' verdict carries an HTTP status (got one on '${this.state}')`);
+    }
+    const chainStates = this.state === RegistryVerdictState.UNTRUSTED
+      || this.state === RegistryVerdictState.UNVERIFIABLE;
+    if (chainStates) {
+      if (this.chain_failure === null) {
+        throw new Error(`a '${this.state}' verdict must carry the chain failure reason that produced it`);
+      }
+      if (registryVerdictStateForChainFailure(this.chain_failure) !== this.state) {
+        throw new Error(`only a trust failure carries a chain failure reason (got one on '${this.state}')`);
+      }
+    } else if (this.chain_failure !== null) {
+      throw new Error(`only a trust failure carries a chain failure reason (got one on '${this.state}')`);
+    }
+    if (!Number.isFinite(this.checked_at_unix_seconds)) {
+      throw new Error('a registry verdict must say when it was reached');
+    }
+  }
+
+  permitsAttachment() {
+    return registryVerdictPermitsAttachment(this.state);
+  }
+
+  toJSON() {
+    return {
+      registry_url: this.registry_url,
+      state: this.state,
+      detail: this.detail,
+      http_status: this.http_status,
+      chain_failure: this.chain_failure,
+      checked_at_unix_seconds: this.checked_at_unix_seconds,
+    };
+  }
+
+  static fromJSON(d) {
+    return new RegistryVerdict(
+      d.registry_url,
+      d.state,
+      d.detail,
+      d.http_status === undefined ? null : d.http_status,
+      d.chain_failure === undefined ? null : d.chain_failure,
+      d.checked_at_unix_seconds,
+    );
+  }
+}
+
 const CartridgeAttachmentErrorKind = Object.freeze({
   INCOMPATIBLE: 'incompatible',
   MANIFEST_INVALID: 'manifest_invalid',
@@ -5384,12 +5742,20 @@ const CartridgeAttachmentErrorKind = Object.freeze({
   // 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',
+  // Recovery is "reinstall".
+  MISPLACED: 'misplaced',
+  // The cartridge's registry verified, and does not list this
+  // (channel, id, version): the artefact says it came from somewhere that has
+  // never heard of it. Recovery is "wait for the publish, or rebuild as dev".
+  NOT_LISTED: 'not_listed',
   // 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 declares a non-null registry_url and that registry's verdict
+  // is not `verified`, so its provenance claim is unconfirmed. WHY belongs to
+  // the registry, not the cartridge — consumers join on registry_url and read
+  // the RegistryVerdict, which is one fact per registry rather than one per
+  // cartridge that claims it.
+  REGISTRY_UNVERIFIED: 'registry_unverified',
   // 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',
@@ -5507,7 +5873,7 @@ class InstalledCartridgeRecord {
    * @param {Array<Object>} [opts.capGroups=[]] - Cartridge's manifest cap_groups; each element is `{name, caps, adapter_urns}`.
    * @param {CartridgeAttachmentError|null} [opts.attachmentError=null]
    * @param {CartridgeRuntimeStats|null} [opts.runtimeStats=null]
-   * @param {string} [opts.lifecycle='discovered'] - One of `discovered` | `inspecting` | `verifying` | `operational`. Mutually exclusive with attachmentError; see `machfab-mac/docs/cartridge state machine.md`.
+   * @param {string} [opts.lifecycle='discovered'] - One of `discovered` | `inspecting` | `verifying` | `operational`. Mutually exclusive with attachmentError; see `macfloom/docs/cartridge state machine.md`.
    */
   constructor({ registryUrl = null, channel, id, version, sha256, capGroups = [], attachmentError = null, runtimeStats = null, lifecycle = 'discovered' }) {
     this.registry_url = registryUrl;
@@ -5664,7 +6030,7 @@ function validateRegistryUrlScheme(url, devMode) {
 /**
  * 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.
+ * consistency failure that discovery maps to MISPLACED.
  */
 const CartridgeJsonErrorKind = Object.freeze({
   NOT_FOUND: 'not_found',
@@ -5678,7 +6044,7 @@ const CartridgeJsonErrorKind = Object.freeze({
 
 /**
  * Error thrown by CartridgeJson.readFromDir. Carries a structured `kind` so
- * discovery can map a slug mismatch to BAD_INSTALLATION and everything else
+ * discovery can map a slug mismatch to MISPLACED and everything else
  * to MANIFEST_INVALID. Mirrors Rust CartridgeJsonError.
  */
 class CartridgeJsonError extends Error {
@@ -6155,7 +6521,6 @@ 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 = {
@@ -6270,9 +6635,21 @@ function probeCartridgeCapGroups(entryPath) {
         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`));
+      // The concurrency-pool state map is MANDATORY on a cartridge HELLO
+      // (bifaci pools, protocol v4): JSON bytes under meta key "pools". A
+      // missing or malformed map is a protocol violation, never a default.
+      const poolsVal = meta.get('pools');
+      if (!poolsVal || poolsVal.__bytes === undefined) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: missing required concurrency-pool state map`));
+        return;
+      }
+      try {
+        const poolStates = JSON.parse(Buffer.from(poolsVal.__bytes).toString('utf8'));
+        if (poolStates === null || typeof poolStates !== 'object' || Array.isArray(poolStates)) {
+          throw new Error('pool-state map must be a JSON object');
+        }
+      } catch (e) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: malformed pool-state map: ${e.message}`));
         return;
       }
       const manifestVal = meta.get('manifest');
@@ -6405,7 +6782,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
       cj = CartridgeJson.readFromDir(versionDir, expectedSlug);
     } catch (e) {
       const kind = (e instanceof CartridgeJsonError && e.kind === CartridgeJsonErrorKind.REGISTRY_SLUG_MISMATCH)
-        ? CartridgeAttachmentErrorKind.BAD_INSTALLATION
+        ? CartridgeAttachmentErrorKind.MISPLACED
         : CartridgeAttachmentErrorKind.MANIFEST_INVALID;
       discovered.push(DiscoveredCartridge.incompatible({
         version_dir: versionDir,
@@ -6430,7 +6807,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
         registry_url: cj.registryUrl,
         version: cj.version,
         error: new CartridgeAttachmentError(
-          CartridgeAttachmentErrorKind.BAD_INSTALLATION,
+          CartridgeAttachmentErrorKind.MISPLACED,
           `Channel mismatch: cartridge declares '${cj.channel}' but host is pinned to '${identity.channel}'. Release and nightly artefacts must not mix.`,
           detectedAt
         ),
@@ -6507,7 +6884,7 @@ async function scanChannelRoot(scanRoot, expectedSlug, identity, discovered) {
             registry_url: cj.registryUrl,
             version: cj.version,
             error: new CartridgeAttachmentError(
-              CartridgeAttachmentErrorKind.BAD_INSTALLATION,
+              CartridgeAttachmentErrorKind.MISPLACED,
               `bundled cartridge integrity check failed: ${reason}`,
               detectedAt
             ),
@@ -8053,6 +8430,21 @@ const planner = require('./planner.js');
 
 // Export for CommonJS
 module.exports = {
+  // Registry trust vocabulary — one verdict per registry, shared by every
+  // cartridge that claims provenance from it.
+  RegistryVerdict,
+  RegistryVerdictState,
+  ChainFailureReason,
+  REGISTRY_VERDICT_STATES,
+  CHAIN_FAILURE_REASONS,
+  registryVerdictStateForChainFailure,
+  registryVerdictPermitsAttachment,
+  registryVerdictIsTrustFailure,
+  registryVerdictIsTransient,
+  RegistryRemedy,
+  registryVerdictRemedy,
+  MANIFEST_SIG_FORMAT,
+  RELEASE_KEY_CERT_FORMAT,
   // Planner plan-space vocabulary
   PlanStateError: planner.PlanStateError,
   ConvergencePresence: planner.ConvergencePresence,

package/capdag.test.js

@@ -14,6 +14,12 @@ const {
   CartridgeJson, CartridgeJsonError, CartridgeJsonErrorKind, hashCartridgeDirectory,
   DiscoveryIdentity, DiscoveredCartridge, discoverCartridges,
   CartridgeAttachmentErrorKind, CartridgeChannel,
+  RegistryVerdict, RegistryVerdictState, ChainFailureReason,
+  REGISTRY_VERDICT_STATES, CHAIN_FAILURE_REASONS,
+  registryVerdictStateForChainFailure, registryVerdictPermitsAttachment,
+  registryVerdictIsTrustFailure, registryVerdictIsTransient,
+  RegistryRemedy, registryVerdictRemedy,
+  MANIFEST_SIG_FORMAT, RELEASE_KEY_CERT_FORMAT,
   CapFabEdge, CapFabStats, CapFab,
   StdinSource, StdinSourceKind,
   validateNoMediaDefRedefinitionSync,
@@ -74,6 +80,27 @@ function assertThrows(fn, expectedErrorCode, message) {
   }
 }
 
+/**
+ * A refusal: the call must throw, and its message must match. Distinct from
+ * `assertThrows`, which is specific to `CapUrnError` codes — asserting only
+ * "it threw" would pass on a typo in the very message the refusal exists to
+ * state.
+ */
+function assertRefuses(fn, pattern, message) {
+  let thrown = null;
+  try {
+    fn();
+  } catch (error) {
+    thrown = error;
+  }
+  if (thrown === null) {
+    throw new Error(`Expected a refusal but the call succeeded: ${message || pattern}`);
+  }
+  if (!pattern.test(thrown.message)) {
+    throw new Error(`Expected a refusal matching ${pattern} but got: ${thrown.message}`);
+  }
+}
+
 function assertThrowsMediaUrn(fn, expectedErrorCode, message) {
   try {
     fn();
@@ -1705,7 +1732,7 @@ function test6236_JS_mediaUrnsForExtension() {
   assert(thrownError instanceof MediaDefError, 'Should throw MediaDefError for unknown ext');
 }
 
-// TEST0070: J s get extension mappings
+// TEST6240: J s get extension mappings
 function test6240_JS_getExtensionMappings() {
   const mediaDefs = [
     { urn: 'media:ext=pdf', media_type: 'application/pdf', extensions: ['pdf'] },
@@ -1716,7 +1743,7 @@ function test6240_JS_getExtensionMappings() {
   assertEqual(mappings.length, 3, 'Should have 3 mappings');
 }
 
-// TEST0073: J s resolve media urn from specs
+// TEST6242: J s resolve media urn from specs
 function test6242_JS_resolveMediaUrnFromSpecs() {
   const mediaDefs = [
     { urn: MEDIA_STRING, media_type: 'text/plain', title: 'String', profile_uri: 'https://capdag.com/schema/str' },
@@ -2693,7 +2720,7 @@ async function test1877_registryCartridgeUnderWrongSlugIsBadInstall() {
     const json = discoveryRegistryCartridgeJson(url, 'nightly', 1);
     discoveryInstallFixture(root, wrongSlug, 'nightly', 'cart', '1.0.0', json, 'cart');
     const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1, cartridgeRegistryVersion: 1 }));
-    discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.BAD_INSTALLATION);
+    discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.MISPLACED);
   } finally {
     discoveryRemoveRoot(root);
   }
@@ -2721,7 +2748,7 @@ async function test1878_bundledCartridgeWithoutBakedHashIsRejected() {
     });
     discoveryInstallFixture(root, 'dev', 'nightly', 'cart', '1.0.0', json, 'cart');
     const out = await discoverCartridges(root, new DiscoveryIdentity({ channel: 'nightly', registryUrl: null, fabricManifestVersion: 1, cartridgeRegistryVersion: 1 }));
-    discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.BAD_INSTALLATION);
+    discoveryExpectIncompatible(out, CartridgeAttachmentErrorKind.MISPLACED);
     assert(out[0].error.message.includes('bundled cartridge integrity'),
       `message should name the bundled-integrity failure: ${out[0].error.message}`);
   } finally {
@@ -3018,6 +3045,54 @@ function test1296_rule11VoidInputCliFlagOnly() {
   validateCapArgs(cap);
 }
 
+// TEST1953: RULE14 — `streaming: true` is accepted on the main input (the
+// stdin arg equivalent to `in=`), survives the JSON round-trip, and is refused
+// on any other argument: a side option has no wire stream, so it has nothing
+// to consume incrementally, and the rule keeps the executor's hop rule
+// one-dimensional.
+function test1953_rule14StreamingOnlyOnMainInput() {
+  const urn = CapUrn.fromString('cap:in="media:string";test;out="media:string"');
+  const ok = new Cap(urn, 'Test', ['test-cmd']);
+  const main = new CapArg('media:string', true, [ArgSource.fromJSON({ stdin: 'media:string' })], { streaming: true });
+  ok.args = [main];
+  validateCapArgs(ok);
+  assert(CapArg.fromJSON(main.toJSON()).streaming === true, 'streaming survives the JSON round-trip');
+  assert(!('streaming' in new CapArg('media:string', true, []).toJSON()), 'streaming is omitted when false, like is_sequence');
+
+  const bad = new Cap(CapUrn.fromString('cap:in="media:string";test;out="media:string"'), 'Test', ['test-cmd']);
+  bad.args = [
+    new CapArg('media:string', true, [ArgSource.fromJSON({ stdin: 'media:string' })]),
+    new CapArg('media:integer;numeric', false, [ArgSource.fromJSON({ cli_flag: '--count' })], { streaming: true }),
+  ];
+  try {
+    validateCapArgs(bad);
+    assert(false, 'Should have thrown RULE14 for a streaming side option');
+  } catch (e) {
+    assert(e instanceof ValidationError, 'Should be ValidationError');
+    assert(e.message.includes('RULE14'), 'Should mention RULE14: ' + e.message);
+    assert(e.message.includes('media:integer;numeric'), 'Should name the offending arg: ' + e.message);
+  }
+}
+
+// TEST1964: a definition field this capdag does not know is a NEWER fabric,
+// not noise — parsing refuses it, naming the key, for arguments and outputs
+// alike. The field being dropped is how a cartridge built on an older capdag
+// once advertised a `streaming` input as bounded.
+function test1964_unknownDefinitionFieldIsRefused() {
+  let threw = null;
+  try {
+    CapArg.fromJSON({ media_urn: 'media:string', required: true, sources: [{ stdin: 'media:string' }], chunking: 'adaptive' });
+  } catch (e) { threw = e; }
+  assert(threw !== null && threw.message.includes('chunking'), 'an unknown arg field must be refused by name: ' + (threw && threw.message));
+  assert(CapArg.fromJSON({ media_urn: 'media:string', required: true, sources: [{ stdin: 'media:string' }], streaming: true }).streaming === true);
+
+  const capJson = new Cap(CapUrn.fromString('cap:in="media:string";test;out="media:string"'), 'Test', ['test-cmd']).toJSON();
+  capJson.output = { media_urn: 'media:string', output_description: 'x', windowed: true };
+  threw = null;
+  try { Cap.fromJSON(capJson); } catch (e) { threw = e; }
+  assert(threw !== null && threw.message.includes('windowed'), 'an unknown output field must be refused by name: ' + (threw && threw.message));
+}
+
 // TEST1297: RULE11 - non-void-input cap with stdin source passes
 function test1297_rule11NonVoidInputWithStdin() {
   const urn = CapUrn.fromString('cap:in="media:string";test;out="media:string"');
@@ -3309,12 +3384,12 @@ function test6275_Machine_emptyInput() {
   assertThrowsWithCode(() => parseMachine(''), MachineSyntaxErrorCodes.EMPTY);
 }
 
-// TEST0088: Machine whitespace only
+// TEST6277: Machine whitespace only
 function test6277_Machine_whitespaceOnly() {
   assertThrowsWithCode(() => parseMachine('   \n  \t  '), MachineSyntaxErrorCodes.EMPTY);
 }
 
-// TEST0089: Machine header only no wirings
+// TEST6279: Machine header only no wirings
 function test6279_Machine_headerOnlyNoWirings() {
   assertThrowsWithCode(
     () => Machine.fromString('[extract cap:in="media:ext=pdf";extract;out="media:enc=utf-8;ext=txt"]'),
@@ -3322,7 +3397,7 @@ function test6279_Machine_headerOnlyNoWirings() {
   );
 }
 
-// TEST0090: Machine duplicate alias
+// TEST6280: Machine duplicate alias
 function test6280_Machine_duplicateAlias() {
   assertThrowsWithCode(
     () => Machine.fromString(
@@ -3334,7 +3409,7 @@ function test6280_Machine_duplicateAlias() {
   );
 }
 
-// TEST0094: Machine simple linear chain
+// TEST6286: Machine simple linear chain
 function test6286_Machine_simpleLinearChain() {
   const g = Machine.fromString(
     '[extract cap:in="media:ext=pdf";extract;out="media:enc=utf-8;ext=txt"]' +
@@ -3350,7 +3425,7 @@ function test6286_Machine_simpleLinearChain() {
   assertEqual(edge.isLoop, false);
 }
 
-// TEST0095: Machine two step chain
+// TEST6288: Machine two step chain
 function test6288_Machine_twoStepChain() {
   const g = Machine.fromString(
     '[extract cap:in="media:ext=pdf";extract;out="media:enc=utf-8;ext=txt"]' +
@@ -3365,7 +3440,7 @@ function test6288_Machine_twoStepChain() {
     'Second edge target should be media:embedding-vector;enc=utf-8;record');
 }
 
-// TEST0096: Machine fan out
+// TEST6290: Machine fan out
 function test6290_Machine_fanOut() {
   const g = Machine.fromString(
     '[meta cap:in="media:ext=pdf";extract-metadata;out="media:enc=utf-8;file-metadata;record"]' +
@@ -3383,7 +3458,7 @@ function test6290_Machine_fanOut() {
   }
 }
 
-// TEST0097: Machine fan in secondary assigned by prior wiring
+// TEST6292: Machine fan in secondary assigned by prior wiring
 function test6292_Machine_fanInSecondaryAssignedByPriorWiring() {
   const g = Machine.fromString(
     '[thumb cap:in="media:ext=pdf";generate-thumbnail;out="media:ext=png;image;thumbnail"]' +
@@ -3397,7 +3472,7 @@ function test6292_Machine_fanInSecondaryAssignedByPriorWiring() {
   assertEqual(g.edges()[2].sources.length, 2);
 }
 
-// TEST0098: Machine fan in secondary unassigned gets wildcard
+// TEST6294: Machine fan in secondary unassigned gets wildcard
 function test6294_Machine_fanInSecondaryUnassignedGetsWildcard() {
   const g = Machine.fromString(
     '[describe cap:in="media:ext=png;image";describe-image;out="media:enc=utf-8;image-description"]\n' +
@@ -5779,7 +5854,7 @@ function test6508_Renderer_buildRunGraphData_allFailedDropsTargetPlaceholder() {
 // TEST6509: Renderer build run graph data unclosed foreach success no merge
 function test6509_Renderer_buildRunGraphData_unclosedForeachSuccessNoMerge() {
   // Strand without a Collect: [Disbind, ForEach, make_decision].
-  // Under the machfab realize_strand semantics there's no Collect,
+  // Under the floom-engine realize_strand semantics there's no Collect,
   // so each body produces its OWN terminal output. Successful
   // replicas do NOT merge into a shared target — each body has
   // its own separate decision.
@@ -6963,8 +7038,6 @@ function assertThrowsPlanState(fn, message) {
   throw new Error(`Expected PlanStateError but function succeeded: ${message}`);
 }
 
-// TEST1450: a defaults-only request is AUTO with every knob at its default,
-// and the proto JSON carries the documented wire shape.
 // TEST1514: the provenance vocabulary grows with installers. A workspace
 // build install parses to its named value; a spelling this build does not
 // know parses, is preserved VERBATIM, round-trips, and is not BUNDLE (the
@@ -6999,6 +7072,8 @@ function test1514_installSourceVocabularyTolerance() {
     'unknown spellings round-trip');
 }
 
+// TEST1450: a defaults-only request is AUTO with every knob at its default,
+// and the proto JSON carries the documented wire shape.
 function test1450_planRequestDefaults() {
   const request = new plannerNS.PlanRequest({
     sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
@@ -7367,6 +7442,8 @@ async function runTests() {
   runTest('TEST1295: rule11_non_void_input_without_stdin_rejected', test1295_rule11NonVoidInputWithoutStdinRejected);
   runTest('TEST1296: rule11_void_input_cli_flag_only', test1296_rule11VoidInputCliFlagOnly);
   runTest('TEST1297: rule11_non_void_input_with_stdin', test1297_rule11NonVoidInputWithStdin);
+  runTest('TEST1953: rule14_streaming_only_on_main_input', test1953_rule14StreamingOnlyOnMainInput);
+  runTest('TEST1964: unknown_definition_field_is_refused', test1964_unknownDefinitionFieldIsRefused);
 
   // cap_urn.rs: TEST639-TEST653 (Cap URN wildcard tests)
   console.log('\n--- cap_urn.rs (wildcard tests) ---');
@@ -7389,6 +7466,15 @@ async function runTests() {
   runTest('TEST655: effect_declared_uses_declared_output', test126_effectDeclaredUsesDeclaredOutput);
   runTest('TEST656: invalid_effect_none_fails_hard', test127_invalidEffectNoneFailsHard);
   runTest('TEST657: effect_dispatch_requires_explicit_wildcard', test128_effectDispatchRequiresExplicitWildcard);
+  runTest('TEST8150: registry_verdict_states_closed', test8150_registryVerdictStatesAreTheClosedWireVocabulary);
+  runTest('TEST8151: chain_failure_classification', test8151_unreadableFormatIsUnverifiableAndRejectedKeyIsUntrusted);
+  runTest('TEST8152: only_verified_permits_attachment', test8152_onlyVerifiedPermitsAttachment);
+  runTest('TEST8153: trust_failures_never_transient', test8153_trustFailuresAreNeverTransient);
+  runTest('TEST8154: contradictory_verdicts_refused', test8154_contradictoryVerdictsAreRefused);
+  runTest('TEST8159: remedy_follows_from_state', test8159_theRemedyFollowsFromTheState);
+  runTest('TEST8155: registry_verdict_wire_round_trip', test8155_registryVerdictWireRoundTrip);
+  runTest('TEST8157: signature_formats_from_library', test8157_signatureFormatDiscriminatorsComeFromTheLibrary);
+  runTest('TEST8158: attachment_kinds_separate_situations', test8158_attachmentKindsSeparateTheirSituations);
   runTest('TEST8121: effect_conformance_declared_asymmetry', test8121_effectConformanceDeclaredAsymmetry);
   runTest('TEST8122: effect_conformance_none_requires_equivalence', test8122_effectConformanceNoneRequiresEquivalence);
   runTest('TEST8123: effect_conformance_patch_requires_patched_input', test8123_effectConformancePatchRequiresPatchedInput);
@@ -7639,6 +7725,235 @@ async function runTests() {
   }
 }
 
+
+// ============================================================================
+// Registry verdicts — the vocabulary a consumer concludes about a REGISTRY
+// ============================================================================
+
+/** TEST8150: the wire vocabulary is closed and matches the Rust mirror. */
+function test8150_registryVerdictStatesAreTheClosedWireVocabulary() {
+  const expected = [
+    'verified', 'pending', 'offline', 'unreachable',
+    'http_error', 'malformed', 'unsigned', 'untrusted', 'unverifiable', 'unenforced',
+  ];
+  assertEqual(REGISTRY_VERDICT_STATES.length, expected.length, 'state count matches the Rust mirror');
+  for (const state of expected) {
+    assert(REGISTRY_VERDICT_STATES.includes(state), `wire vocabulary carries '${state}'`);
+  }
+  const reasons = [
+    'malformed_envelope', 'unsupported_envelope_format', 'malformed_certificate',
+    'unsupported_certificate_format', 'empty_certificate_list', 'insufficient_root_signatures',
+    'expired_certificate', 'not_yet_valid_certificate', 'environment_mismatch',
+    'key_id_mismatch', 'no_authorizing_certificate', 'manifest_signature_invalid',
+  ];
+  assertEqual(CHAIN_FAILURE_REASONS.length, reasons.length, 'reason count matches the Rust mirror');
+  for (const reason of reasons) {
+    assert(CHAIN_FAILURE_REASONS.includes(reason), `wire vocabulary carries '${reason}'`);
+  }
+  assertRefuses(() => registryVerdictPermitsAttachment('network_error'), /unknown registry verdict state/);
+}
+
+/** TEST8151: a format this build cannot read is OUR limitation — never the
+ *  registry being untrustworthy, and never a network problem. */
+function test8151_unreadableFormatIsUnverifiableAndRejectedKeyIsUntrusted() {
+  for (const unevaluable of [
+    ChainFailureReason.MALFORMED_ENVELOPE,
+    ChainFailureReason.UNSUPPORTED_ENVELOPE_FORMAT,
+    ChainFailureReason.MALFORMED_CERTIFICATE,
+    ChainFailureReason.UNSUPPORTED_CERTIFICATE_FORMAT,
+    ChainFailureReason.EMPTY_CERTIFICATE_LIST,
+  ]) {
+    assertEqual(
+      registryVerdictStateForChainFailure(unevaluable),
+      RegistryVerdictState.UNVERIFIABLE,
+      `${unevaluable} could not be judged at all`,
+    );
+  }
+  for (const judged of [
+    ChainFailureReason.INSUFFICIENT_ROOT_SIGNATURES,
+    ChainFailureReason.EXPIRED_CERTIFICATE,
+    ChainFailureReason.NOT_YET_VALID_CERTIFICATE,
+    ChainFailureReason.ENVIRONMENT_MISMATCH,
+    ChainFailureReason.KEY_ID_MISMATCH,
+    ChainFailureReason.NO_AUTHORIZING_CERTIFICATE,
+    ChainFailureReason.MANIFEST_SIGNATURE_INVALID,
+  ]) {
+    assertEqual(
+      registryVerdictStateForChainFailure(judged),
+      RegistryVerdictState.UNTRUSTED,
+      `${judged} is a judgement that WAS reached`,
+    );
+  }
+  assertRefuses(() => registryVerdictStateForChainFailure('bad_signature'), /unknown chain failure reason/);
+}
+
+/** TEST8152: only a verified registry lets a cartridge attach — `pending`
+ *  included, which must never read as permission. */
+function test8152_onlyVerifiedPermitsAttachment() {
+  for (const state of REGISTRY_VERDICT_STATES) {
+    assertEqual(
+      registryVerdictPermitsAttachment(state),
+      state === RegistryVerdictState.VERIFIED || state === RegistryVerdictState.UNENFORCED,
+      `permits_attachment('${state}')`,
+    );
+  }
+  // A DEV BUILD HAS TO WORK, and it says which of the two it is: "we checked
+  // and it passed" and "we did not check" are different facts.
+  assert(registryVerdictPermitsAttachment(RegistryVerdictState.UNENFORCED));
+  assert(!registryVerdictIsTrustFailure(RegistryVerdictState.UNENFORCED));
+  assert(!registryVerdictIsTransient(RegistryVerdictState.UNENFORCED));
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.UNENFORCED), RegistryRemedy.NONE);
+}
+
+/** TEST8153: a refusal never resolves itself, so nothing may present it as
+ *  worth retrying. */
+function test8153_trustFailuresAreNeverTransient() {
+  for (const state of REGISTRY_VERDICT_STATES) {
+    assert(
+      !(registryVerdictIsTrustFailure(state) && registryVerdictIsTransient(state)),
+      `'${state}' cannot be both a refusal and something a retry could fix`,
+    );
+  }
+  assert(registryVerdictIsTrustFailure(RegistryVerdictState.UNVERIFIABLE));
+  assert(registryVerdictIsTrustFailure(RegistryVerdictState.UNTRUSTED));
+  assert(registryVerdictIsTrustFailure(RegistryVerdictState.UNSIGNED));
+  assert(registryVerdictIsTransient(RegistryVerdictState.UNREACHABLE));
+  assert(registryVerdictIsTransient(RegistryVerdictState.PENDING));
+  // Policy is not transient: it holds until an operator changes it.
+  assert(!registryVerdictIsTransient(RegistryVerdictState.OFFLINE));
+  assert(!registryVerdictIsTrustFailure(RegistryVerdictState.OFFLINE));
+}
+
+/** TEST8159: the remedy follows from the state, and "check the network" is
+ *  reachable from exactly one state. That sentence used to be appended to every
+ *  held-cartridge message whatever the cause, which is how a signature format a
+ *  build could not read sent operators to their router. */
+function test8159_theRemedyFollowsFromTheState() {
+  const network = REGISTRY_VERDICT_STATES.filter(
+    (state) => registryVerdictRemedy(state) === RegistryRemedy.CHECK_NETWORK,
+  );
+  assertEqual(network.length, 1, 'exactly one state is a network problem');
+  assertEqual(network[0], RegistryVerdictState.UNREACHABLE);
+  for (const state of REGISTRY_VERDICT_STATES) {
+    if (!registryVerdictIsTrustFailure(state)) continue;
+    const remedy = registryVerdictRemedy(state);
+    assert(
+      remedy === RegistryRemedy.DO_NOT_PROCEED || remedy === RegistryRemedy.UPDATE_CLIENT,
+      `'${state}' is a refusal; its remedy must not be a retry (got '${remedy}')`,
+    );
+  }
+  // The one that was misclassified: our limitation, so update the client —
+  // never distrust the registry, never touch the network.
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.UNVERIFIABLE), RegistryRemedy.UPDATE_CLIENT);
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.UNTRUSTED), RegistryRemedy.DO_NOT_PROCEED);
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.VERIFIED), RegistryRemedy.NONE);
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.PENDING), RegistryRemedy.WAIT);
+  // Policy is the operator's setting, not their router.
+  assertEqual(registryVerdictRemedy(RegistryVerdictState.OFFLINE), RegistryRemedy.CHANGE_NETWORK_POLICY);
+  assertRefuses(() => registryVerdictRemedy('flaky'), /unknown registry verdict state/);
+}
+
+/** TEST8154: illegal states are unrepresentable — every contradiction is
+ *  refused at construction. */
+function test8154_contradictoryVerdictsAreRefused() {
+  const URL = 'https://cartridges.example/v1/manifest';
+  const now = 1700000000;
+  assertRefuses(
+    () => RegistryVerdict.stated(URL, RegistryVerdictState.UNREACHABLE, '', now),
+    /must carry the detail/,
+  );
+  assertRefuses(
+    () => RegistryVerdict.stated(URL, RegistryVerdictState.VERIFIED, 'all good', now),
+    /states no failure/,
+  );
+  assertRefuses(
+    () => RegistryVerdict.stated(URL, RegistryVerdictState.HTTP_ERROR, '500', now),
+    /must carry the status/,
+  );
+  assertRefuses(
+    () => RegistryVerdict.stated(URL, RegistryVerdictState.UNTRUSTED, 'nope', now),
+    /must carry the chain failure reason/,
+  );
+  assertRefuses(
+    () => RegistryVerdict.stated('', RegistryVerdictState.UNREACHABLE, 'timeout', now),
+    /must name the registry/,
+  );
+  // A reason that contradicts the state it is filed under.
+  assertRefuses(
+    () => new RegistryVerdict(URL, RegistryVerdictState.UNTRUSTED, 'x', null,
+      ChainFailureReason.UNSUPPORTED_ENVELOPE_FORMAT, now),
+    /chain failure reason/,
+  );
+  // A status on a state that never answered.
+  assertRefuses(
+    () => new RegistryVerdict(URL, RegistryVerdictState.UNREACHABLE, 'timeout', 404, null, now),
+    /only an 'http_error' verdict carries an HTTP status/,
+  );
+}
+
+/** TEST8155: the wire form round-trips with its invariants intact. */
+function test8155_registryVerdictWireRoundTrip() {
+  const URL = 'https://cartridges.example/v1/manifest';
+  const now = 1700000000;
+  const verdict = RegistryVerdict.chainFailed(
+    URL,
+    ChainFailureReason.UNSUPPORTED_ENVELOPE_FORMAT,
+    "envelope format 'other/1' is not implemented by this build",
+    now,
+  );
+  assertEqual(verdict.state, RegistryVerdictState.UNVERIFIABLE);
+  const decoded = RegistryVerdict.fromJSON(JSON.parse(JSON.stringify(verdict.toJSON())));
+  assertEqual(decoded.state, verdict.state);
+  assertEqual(decoded.chain_failure, verdict.chain_failure);
+  assertEqual(decoded.detail, verdict.detail);
+  assertEqual(decoded.registry_url, verdict.registry_url);
+  assertEqual(decoded.permitsAttachment(), false);
+
+  const http = RegistryVerdict.httpError(URL, 404, 'registry answered HTTP 404', now);
+  assertEqual(http.http_status, 404);
+  assertEqual(RegistryVerdict.fromJSON(http.toJSON()).http_status, 404);
+
+  assertRefuses(
+    () => RegistryVerdict.fromJSON({
+      registry_url: URL, state: 'http_error', detail: 'answered badly',
+      http_status: null, chain_failure: null, checked_at_unix_seconds: now,
+    }),
+    /must carry the status/,
+  );
+  assertRefuses(
+    () => RegistryVerdict.fromJSON({
+      registry_url: URL, state: 'flaky', detail: 'hm',
+      http_status: null, chain_failure: null, checked_at_unix_seconds: now,
+    }),
+    /unknown registry verdict state/,
+  );
+}
+
+/** TEST8157: the format discriminators are the library's, so no consumer can
+ *  hold a divergent copy. A product rename that edits a client's private
+ *  constant makes that client verify nothing while every other implementation
+ *  keeps working — which is precisely what happened. */
+function test8157_signatureFormatDiscriminatorsComeFromTheLibrary() {
+  assertEqual(MANIFEST_SIG_FORMAT, 'machinefabric-manifest-sig/1');
+  assertEqual(RELEASE_KEY_CERT_FORMAT, 'machinefabric-release-key-cert/1');
+}
+
+/** TEST8158: the attachment vocabulary names the situations apart. */
+function test8158_attachmentKindsSeparateTheirSituations() {
+  assertEqual(CartridgeAttachmentErrorKind.MISPLACED, 'misplaced');
+  assertEqual(CartridgeAttachmentErrorKind.NOT_LISTED, 'not_listed');
+  assertEqual(CartridgeAttachmentErrorKind.REGISTRY_UNVERIFIED, 'registry_unverified');
+  assert(
+    CartridgeAttachmentErrorKind.BAD_INSTALLATION === undefined,
+    'bad_installation meant two things with different remedies and is gone',
+  );
+  assert(
+    CartridgeAttachmentErrorKind.REGISTRY_UNREACHABLE === undefined,
+    'registry_unreachable claimed a cause it could not know and is gone',
+  );
+}
+
+
 // Run the tests
 if (require.main === module) {
   runTests()

package/package.json

@@ -41,5 +41,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "1.249.12"
+  "version": "1.266.66"
 }

package/planner.js

@@ -1,10 +1,10 @@
 // Unified configurable planner — the plan-space vocabulary for JS clients.
 //
 // Mirrors core Rust `capdag/src/planner/plan_space.rs` and the proto surface
-// (`machfab/proto/cap.proto` PlanMachines/DiscoverConvergentTargets): the knob
+// (`floom-engine/proto/cap.proto` PlanMachines/DiscoverConvergentTargets): the knob
 // enums, the request shape with the same validation the engine applies, and
 // parsers for the proto-JSON response shapes (ts-proto `snakeToCamel=false`,
-// so wire field names are snake_case). This is what lets fabricloom represent
+// so wire field names are snake_case). This is what lets floom-uikit represent
 // and manipulate the FULL planner state — knobs, ranked candidates, apexes —
 // both standalone (fixtures) and fed over gRPC by the desktop clients.
 //