capdag 0.180.452 → 0.182.459

package/cap-fab-renderer.js

@@ -555,6 +555,26 @@ function buildStylesheet() {
       selector: 'edge.active',
       style: { 'width': 3, 'z-index': 1000 },
     },
+    {
+      selector: 'edge.strand-shape-edge',
+      style: {
+        'line-style': 'dashed',
+        'width': 2,
+        'text-background-opacity': 0.92,
+      },
+    },
+    {
+      selector: 'edge.strand-foreach-edge',
+      style: {
+        'target-arrow-shape': 'triangle',
+      },
+    },
+    {
+      selector: 'edge.strand-collect-edge',
+      style: {
+        'target-arrow-shape': 'tee',
+      },
+    },
     {
       selector: 'edge.faded',
       style: { 'opacity': fadedEdgeOpacity },
@@ -1374,7 +1394,7 @@ function collapseStrandShapeTransitions(built) {
           label: '',
           title: '',
           fullUrn: '',
-          edgeClass: 'strand-cap-edge',
+          edgeClass: 'strand-cap-edge strand-shape-edge strand-collect-edge',
           color: bodyExitCapEdge ? bodyExitCapEdge.color : inEdge.color,
           foreachEntry: false,
         });
@@ -1399,15 +1419,16 @@ function collapseStrandShapeTransitions(built) {
     e.edgeClass !== 'strand-collection');
   edges = edges.concat(synthesizedExitEdges);
 
-  // Step 2: foreach-entry cap edges keep whatever label the
-  // strand builder emitted — the cap's own cardinality marker
-  // (from input_is_sequence/output_is_sequence) is the single
-  // source of truth for which edge carries a (1→n) / (n→1) /
-  // (n→n) annotation. The ForEach/Collect shape transitions
-  // themselves are invisible in the render; the cap preceding a
-  // ForEach (with output_is_sequence=true) already produces the
-  // (1→n) marker, and the cap following a Collect (with
-  // input_is_sequence=true) produces (n→1). No relabeling.
+  // Step 2: surface shape transitions as distinct edge semantics.
+  // The cap edge that enters a foreach body keeps its original cap
+  // label; only the edge styling changes. Collect bridges are
+  // synthesized above as dedicated dashed edges.
+  edges = edges.map(edge => {
+    if (!edge.foreachEntry) return edge;
+    return Object.assign({}, edge, {
+      edgeClass: `${edge.edgeClass} strand-shape-edge strand-foreach-edge`,
+    });
+  });
 
   // Step 3: merge the trailing `step_N → output` edge when step_N
   // and output represent the same media URN. The strand builder

package/capdag.js

@@ -2,7 +2,11 @@
 // Follows the exact same rules as Rust, Go, and Objective-C implementations
 
 // Import TaggedUrn from the tagged-urn package
-const { TaggedUrn, valuesMatch: taggedUrnValuesMatch, scoreTagValue } = require('tagged-urn');
+const {
+  TaggedUrn,
+  valuesMatch: taggedUrnValuesMatch,
+  scoreTagValue
+} = require('tagged-urn');
 
 /**
  * Error types for Cap URN operations
@@ -30,7 +34,10 @@ const ErrorCodes = {
   MISSING_OUT_SPEC: 11,
   EMPTY_VALUE: 12,
   INVALID_IN_SPEC: 13,
-  INVALID_OUT_SPEC: 14
+  INVALID_OUT_SPEC: 14,
+  INVALID_EFFECT: 15,
+  INVALID_EFFECT_APPLICATION: 16,
+  ILLEGAL_DECLARATION: 17
 };
 
 // Note: All parsing is delegated to TaggedUrn from tagged-urn-js
@@ -114,8 +121,8 @@ function validatePreservedDirectionSpec(spec, tagName) {
 }
 
 /**
- * Functional category of a cap, derived from all three axes (`in`,
- * `out`, and the remaining tags). The classification is **logical** —
+ * Functional category of a cap, derived from all four structural axes
+ * (`in`, `out`, `effect`, and the remaining tags). The classification is **logical** —
  * the dispatch protocol does not branch on CapKind. Exposed so tools,
  * UIs, planners, and tests can reason about a cap's role without
  * re-deriving the rules.
@@ -124,15 +131,13 @@ function validatePreservedDirectionSpec(spec, tagName) {
  * is the **top type** (universal wildcard). With those anchors the
  * five kinds fall out:
  *
- *   IDENTITY   in=media:, out=media:, no other tags  → A → A
+ *   IDENTITY   in=media:, out=media:, effect=none, no other tags  → A → A
  *   SOURCE     in=media:void, out!=void              → () → B
  *   SINK       in!=void,    out=media:void           → A → ()
  *   EFFECT     in=media:void, out=media:void         → () → ()
  *   TRANSFORM  anything else
  *
- * IDENTITY is the **fully generic** cap on every axis. Adding any
- * tag specifies something on the third axis and demotes the morphism
- * to a TRANSFORM whose in/out happen to be the wildcards.
+ * `cap:effect=none` is the categorical identity morphism.
  *
  * String values are snake_case to match other capdag enum
  * serializations on the wire.
@@ -145,6 +150,50 @@ const CapKind = Object.freeze({
   TRANSFORM: 'transform',
 });
 
+const CapEffect = Object.freeze({
+  DECLARED: 'declared',
+  NONE: 'none',
+  PATCH: 'patch',
+  ANY: '?',
+});
+
+function normalizeEffectValue(rawValue) {
+  if (rawValue === undefined || rawValue === null) return CapEffect.DECLARED;
+  if (rawValue === '?' || rawValue === '*') return CapEffect.ANY;
+  if (rawValue === CapEffect.DECLARED) return CapEffect.DECLARED;
+  if (rawValue === CapEffect.NONE) return CapEffect.NONE;
+  if (rawValue === CapEffect.PATCH) return CapEffect.PATCH;
+  if (rawValue === '') {
+    throw new CapUrnError(ErrorCodes.INVALID_EFFECT, "Empty value for 'effect' tag is not allowed");
+  }
+  throw new CapUrnError(
+    ErrorCodes.INVALID_EFFECT,
+    `Unsupported effect '${rawValue}'. Supported values are declared, none, patch, or explicit unconstrained ?effect/effect=*`
+  );
+}
+
+function validateNonStructuralTags(tags) {
+  try {
+    new TaggedUrn('cap', tags, true);
+  } catch (error) {
+    const msg = error && error.message ? error.message : String(error);
+    const msgLower = msg.toLowerCase();
+    if (msgLower.includes('duplicate')) {
+      throw new CapUrnError(ErrorCodes.DUPLICATE_KEY, msg);
+    }
+    if (msgLower.includes('numeric') || msgLower.includes('purely numeric')) {
+      throw new CapUrnError(ErrorCodes.NUMERIC_KEY, msg);
+    }
+    if (msgLower.includes('invalid character')) {
+      throw new CapUrnError(ErrorCodes.INVALID_CHARACTER, msg);
+    }
+    if (msgLower.includes('escape')) {
+      throw new CapUrnError(ErrorCodes.INVALID_ESCAPE_SEQUENCE, msg);
+    }
+    throw new CapUrnError(ErrorCodes.INVALID_TAG_FORMAT, msg);
+  }
+}
+
 class CapUrn {
   // Per-axis weights for cap-URN specificity. Two orders of
   // magnitude separate each axis to keep them in distinct digit
@@ -157,19 +206,23 @@ class CapUrn {
    * Create a new CapUrn with direction specs.
    * @param {string} inSpec - Input media URN (e.g., "media:void")
    * @param {string} outSpec - Output media URN (e.g., "media:object")
-   * @param {Object} tags - Other tags (must NOT contain 'in' or 'out')
+   * @param {string} effect - Runtime media identity effect
+   * @param {Object} tags - Other tags (must NOT contain 'in', 'out', or 'effect')
    */
-  constructor(inSpec, outSpec, tags = {}) {
+  constructor(inSpec, outSpec, effect = CapEffect.DECLARED, tags = {}) {
     this.inSpec = canonicalizeDirectionSpec(inSpec, 'in');
     this.outSpec = canonicalizeDirectionSpec(outSpec, 'out');
+    this.effectValue = normalizeEffectValue(effect);
     this.tags = {};
-    // Copy tags, filtering out any 'in' or 'out' that might have slipped through
+    // Copy tags, filtering out any structural coordinates that might have slipped through
     for (const [key, value] of Object.entries(tags)) {
       const keyLower = key.toLowerCase();
-      if (keyLower !== 'in' && keyLower !== 'out') {
+      if (keyLower !== 'in' && keyLower !== 'out' && keyLower !== 'effect') {
         this.tags[keyLower] = value;
       }
     }
+    validateNonStructuralTags(this.tags);
+    this._validateAdmissible();
   }
 
   /**
@@ -188,6 +241,14 @@ class CapUrn {
     return this.outSpec;
   }
 
+  /**
+   * Get the canonical effect coordinate.
+   * @returns {string}
+   */
+  getEffect() {
+    return this.effectValue;
+  }
+
   /**
    * Parse the in= spec into a MediaUrn.
    * @returns {MediaUrn} The input media URN
@@ -207,15 +268,11 @@ class CapUrn {
   }
 
   /**
-   * Functional category of this cap, derived from all three axes:
-   * `in` (parsed MediaUrn), `out` (parsed MediaUrn), and the rest of
-   * the tags (the operation/metadata axis — `this.tags` does NOT
-   * include in/out, those live in this.inSpec/this.outSpec).
+   * Functional category of this cap, derived from all four axes:
+   * `in`, `out`, `effect`, and the remaining y-axis tags.
    *
-   * Identity requires every axis to be in its most generic form: in
-   * is the top media URN (`media:`), out is the top media URN, and
-   * there are no other tags. Source/Sink/Effect are decided by void
-   * on either directional axis. Anything else is Transform.
+   * Identity requires top/top, no other tags, and explicit
+   * `effect=none`.
    *
    * @returns {string} A {@link CapKind} value (snake_case string).
    * @throws {MediaUrnError} If either side is not a valid media URN
@@ -232,7 +289,9 @@ class CapUrn {
     const outTop = outMedia.isTop();
     const noExtraTags = Object.keys(this.tags).length === 0;
 
-    if (inTop && outTop && noExtraTags) return CapKind.IDENTITY;
+    if (inTop && outTop && noExtraTags) {
+      if (this.effectValue === CapEffect.NONE) return CapKind.IDENTITY;
+    }
     if (inVoid && outVoid) return CapKind.EFFECT;
     if (inVoid) return CapKind.SOURCE;
     if (outVoid) return CapKind.SINK;
@@ -293,20 +352,23 @@ class CapUrn {
     const inSpec = processDirectionTag(taggedUrn, 'in');
     const outSpec = processDirectionTag(taggedUrn, 'out');
 
-    // Build remaining tags (excluding in/out)
+    const effect = normalizeEffectValue(taggedUrn.getTag('effect'));
+
+    // Build remaining tags (excluding in/out/effect)
     const remainingTags = {};
     for (const [key, value] of Object.entries(taggedUrn.tags)) {
-      if (key !== 'in' && key !== 'out') {
+      if (key !== 'in' && key !== 'out' && key !== 'effect') {
         remainingTags[key] = value;
       }
     }
 
-    return new CapUrn(inSpec, outSpec, remainingTags);
+    return new CapUrn(inSpec, outSpec, effect, remainingTags);
   }
 
   /**
    * Create a Cap URN from a tags object.
-   * Unlike string parsing, this path requires explicit `in` and `out` tags.
+   * Missing structural coordinates default exactly as they do in string
+   * parsing (`in=media:`, `out=media:`, `effect=declared`).
    *
    * @param {Object} tags - Object containing all tags including 'in' and 'out'
    * @returns {CapUrn} The parsed Cap URN
@@ -330,16 +392,18 @@ class CapUrn {
       throw new CapUrnError(ErrorCodes.INVALID_OUT_SPEC, "Empty value for 'out' tag is not allowed");
     }
 
-    // Build remaining tags (excluding in/out)
+    const effect = normalizeEffectValue(tags['effect'] || tags['EFFECT']);
+
+    // Build remaining tags (excluding in/out/effect)
     const remainingTags = {};
     for (const [key, value] of Object.entries(tags)) {
       const keyLower = key.toLowerCase();
-      if (keyLower !== 'in' && keyLower !== 'out') {
+      if (keyLower !== 'in' && keyLower !== 'out' && keyLower !== 'effect') {
         remainingTags[keyLower] = value;
       }
     }
 
-    return new CapUrn(inSpec, outSpec, remainingTags);
+    return new CapUrn(inSpec, outSpec, effect, remainingTags);
   }
 
   /**
@@ -352,11 +416,8 @@ class CapUrn {
    */
   toString() {
     // `in` and `out` segments are emitted only when they refine beyond
-    // the trivial wildcard `media:`. A cap whose in/out are both
-    // `media:` and which has no other tags has the canonical form
-    // `cap:` — the bare identity URN. The canonicalizer collapses both
-    // written forms (`cap:` and `cap:in=media:;out=media:`) to one
-    // representative so byte-equality matches semantic identity.
+    // the trivial wildcard `media:`. Missing `effect` means the default
+    // `declared`; `effect=none` is preserved.
     const allTags = { ...this.tags };
     if (this.inSpec !== 'media:') {
       allTags['in'] = this.inSpec;
@@ -364,6 +425,9 @@ class CapUrn {
     if (this.outSpec !== 'media:') {
       allTags['out'] = this.outSpec;
     }
+    if (this.effectValue !== CapEffect.DECLARED) {
+      allTags['effect'] = this.effectValue;
+    }
 
     const taggedUrn = new TaggedUrn('cap', allTags, true);
     return taggedUrn.toString();
@@ -372,7 +436,8 @@ class CapUrn {
   /**
    * Get the value of a specific tag
    * Key is normalized to lowercase for lookup
-   * Returns inSpec for "in" key, outSpec for "out" key
+   * Returns inSpec for "in" key, outSpec for "out" key, and the effect
+   * coordinate for "effect".
    *
    * @param {string} key - The tag key
    * @returns {string|undefined} The tag value or undefined if not found
@@ -385,13 +450,16 @@ class CapUrn {
     if (keyLower === 'out') {
       return this.outSpec;
     }
+    if (keyLower === 'effect') {
+      return this.effectValue;
+    }
     return this.tags[keyLower];
   }
 
   /**
    * Check if this cap has a specific tag with a specific value
    * Key is normalized to lowercase; value comparison is case-sensitive
-   * Checks inSpec for "in" key, outSpec for "out" key
+   * Checks inSpec for "in" key, outSpec for "out" key, and effect for "effect"
    *
    * @param {string} key - The tag key
    * @param {string} value - The tag value to check
@@ -405,6 +473,9 @@ class CapUrn {
     if (keyLower === 'out') {
       return this.outSpec === value;
     }
+    if (keyLower === 'effect') {
+      return this.effectValue === value;
+    }
     const tagValue = this.tags[keyLower];
     return tagValue !== undefined && tagValue === value;
   }
@@ -422,7 +493,7 @@ class CapUrn {
    */
   hasMarkerTag(tagName) {
     const keyLower = tagName.toLowerCase();
-    if (keyLower === 'in' || keyLower === 'out') {
+    if (keyLower === 'in' || keyLower === 'out' || keyLower === 'effect') {
       return false;
     }
     return this.tags[keyLower] === '*';
@@ -430,8 +501,8 @@ class CapUrn {
 
   /**
    * Create a new cap URN with an added or updated tag.
-   * Attempts to set `in` / `out` through `withTag` are ignored; use
-   * `withInSpec` / `withOutSpec` instead.
+   * Reserved structural coordinates must be changed through dedicated
+   * accessors.
    *
    * @param {string} key - The tag key
    * @param {string} value - The tag value
@@ -442,13 +513,15 @@ class CapUrn {
       throw new CapUrnError(ErrorCodes.EMPTY_VALUE, `Empty value for key '${key}' (use '*' for wildcard)`);
     }
     const keyLower = key.toLowerCase();
-    // Silently ignore attempts to set in/out via withTag
-    if (keyLower === 'in' || keyLower === 'out') {
-      return this;
+    if (keyLower === 'in' || keyLower === 'out' || keyLower === 'effect') {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_TAG_FORMAT,
+        `Reserved structural key '${keyLower}' must be changed via withInSpec(), withOutSpec(), or withEffect()`
+      );
     }
     const newTags = { ...this.tags };
     newTags[keyLower] = value;
-    return new CapUrn(this.inSpec, this.outSpec, newTags);
+    return new CapUrn(this.inSpec, this.outSpec, this.effectValue, newTags);
   }
 
   /**
@@ -458,9 +531,12 @@ class CapUrn {
    * @returns {CapUrn} A new CapUrn instance with the updated inSpec
    */
   withInSpec(inSpec) {
-    const updated = new CapUrn(this.inSpec, this.outSpec, this.tags);
-    updated.inSpec = validatePreservedDirectionSpec(inSpec, 'in');
-    return updated;
+    return new CapUrn(
+      validatePreservedDirectionSpec(inSpec, 'in'),
+      this.outSpec,
+      this.effectValue,
+      this.tags
+    );
   }
 
   /**
@@ -470,28 +546,43 @@ class CapUrn {
    * @returns {CapUrn} A new CapUrn instance with the updated outSpec
    */
   withOutSpec(outSpec) {
-    const updated = new CapUrn(this.inSpec, this.outSpec, this.tags);
-    updated.outSpec = validatePreservedDirectionSpec(outSpec, 'out');
-    return updated;
+    return new CapUrn(
+      this.inSpec,
+      validatePreservedDirectionSpec(outSpec, 'out'),
+      this.effectValue,
+      this.tags
+    );
+  }
+
+  /**
+   * Create a new cap URN with a different effect coordinate.
+   *
+   * @param {string} effect
+   * @returns {CapUrn}
+   */
+  withEffect(effect) {
+    return new CapUrn(this.inSpec, this.outSpec, normalizeEffectValue(effect), this.tags);
   }
 
   /**
    * Create a new cap URN with a tag removed
    * Key is normalized to lowercase for case-insensitive removal
-   * SILENTLY IGNORES attempts to remove "in" or "out" - they are required
+   * Reserved structural coordinates must be changed through dedicated accessors.
    *
    * @param {string} key - The tag key to remove
    * @returns {CapUrn} A new CapUrn instance with the tag removed
    */
   withoutTag(key) {
     const keyLower = key.toLowerCase();
-    // Silently ignore attempts to remove in/out - they are required
-    if (keyLower === 'in' || keyLower === 'out') {
-      return this;
+    if (keyLower === 'in' || keyLower === 'out' || keyLower === 'effect') {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_TAG_FORMAT,
+        `Reserved structural key '${keyLower}' cannot be removed via withoutTag()`
+      );
     }
     const newTags = { ...this.tags };
     delete newTags[keyLower];
-    return new CapUrn(this.inSpec, this.outSpec, newTags);
+    return new CapUrn(this.inSpec, this.outSpec, this.effectValue, newTags);
   }
 
   /**
@@ -516,8 +607,8 @@ class CapUrn {
     // Input direction: pattern accepts instance. `media:` on the pattern side is
     // the wildcard top and skips the check.
     if (this.inSpec !== 'media:' && this.inSpec !== '*') {
-      const capIn = TaggedUrn.fromString(this.inSpec);
-      const requestIn = TaggedUrn.fromString(request.inSpec);
+      const capIn = MediaUrn.fromString(this.inSpec);
+      const requestIn = MediaUrn.fromString(request.inSpec);
       if (!capIn.accepts(requestIn)) {
         return false;
       }
@@ -526,13 +617,17 @@ class CapUrn {
     // Output direction: provider output must conform to requested output.
     // `media:` on the pattern side is wildcard top and skips the check.
     if (this.outSpec !== 'media:' && this.outSpec !== '*') {
-      const capOut = TaggedUrn.fromString(this.outSpec);
-      const requestOut = TaggedUrn.fromString(request.outSpec);
+      const capOut = MediaUrn.fromString(this.outSpec);
+      const requestOut = MediaUrn.fromString(request.outSpec);
       if (!capOut.conformsTo(requestOut)) {
         return false;
       }
     }
 
+    if (this.effectValue !== CapEffect.ANY && this.effectValue !== request.effectValue) {
+      return false;
+    }
+
     // Y-axis: every tag's per-key match runs through the six-form
     // truth table (taggedUrnValuesMatch). Walk the union of all keys
     // appearing on either side so missing-on-pattern and
@@ -593,8 +688,8 @@ class CapUrn {
    * @returns {number} The specificity score
    */
   specificity() {
-    const inUrn = TaggedUrn.fromString(this.inSpec);
-    const outUrn = TaggedUrn.fromString(this.outSpec);
+    const inUrn = MediaUrn.fromString(this.inSpec);
+    const outUrn = MediaUrn.fromString(this.outSpec);
 
     let yScore = 0;
     for (const value of Object.values(this.tags)) {
@@ -629,10 +724,13 @@ class CapUrn {
   withWildcardTag(key) {
     const keyLower = key.toLowerCase();
     if (keyLower === 'in') {
-      return this.withInSpec('*');
+      return this.withInSpec('media:');
     }
     if (keyLower === 'out') {
-      return this.withOutSpec('*');
+      return this.withOutSpec('media:');
+    }
+    if (keyLower === 'effect') {
+      return this.withEffect(CapEffect.ANY);
     }
     if (this.tags.hasOwnProperty(keyLower)) {
       return this.withTag(key, '*');
@@ -642,7 +740,7 @@ class CapUrn {
 
   /**
    * Create a new cap with only specified tags
-   * Always preserves inSpec and outSpec (they are required)
+   * Always preserves inSpec, outSpec, and effect.
    *
    * @param {string[]} keys - Array of tag keys to include
    * @returns {CapUrn} A new CapUrn instance with only the specified tags (plus in/out)
@@ -651,29 +749,28 @@ class CapUrn {
     const newTags = {};
     for (const key of keys) {
       const normalizedKey = key.toLowerCase();
-      // Skip in/out - they are always preserved via constructor
-      if (normalizedKey !== 'in' && normalizedKey !== 'out') {
+      if (normalizedKey !== 'in' && normalizedKey !== 'out' && normalizedKey !== 'effect') {
         if (this.tags.hasOwnProperty(normalizedKey)) {
           newTags[normalizedKey] = this.tags[normalizedKey];
         }
       }
     }
-    return new CapUrn(this.inSpec, this.outSpec, newTags);
+    return new CapUrn(this.inSpec, this.outSpec, this.effectValue, newTags);
   }
 
   /**
    * Merge with another cap (other takes precedence for conflicts)
-   * Direction specs (in/out) are taken from other
+   * Structural coordinates are taken from other.
    *
    * @param {CapUrn} other - The cap to merge with
    * @returns {CapUrn} A new CapUrn instance with merged tags
    */
   merge(other) {
     if (!other) {
-      return new CapUrn(this.inSpec, this.outSpec, this.tags);
+      return new CapUrn(this.inSpec, this.outSpec, this.effectValue, this.tags);
     }
     const newTags = { ...this.tags, ...other.tags };
-    return new CapUrn(other.inSpec, other.outSpec, newTags);
+    return new CapUrn(other.inSpec, other.outSpec, other.effectValue, newTags);
   }
 
   /**
@@ -710,7 +807,7 @@ class CapUrn {
     }
 
     // Compare direction specs
-    if (this.inSpec !== other.inSpec || this.outSpec !== other.outSpec) {
+    if (this.inSpec !== other.inSpec || this.outSpec !== other.outSpec || this.effectValue !== other.effectValue) {
       return false;
     }
 
@@ -751,6 +848,139 @@ class CapUrn {
     }
     return hash.toString(16);
   }
+
+  /**
+   * Check if this provider can dispatch the given request.
+   *
+   * @param {CapUrn} request
+   * @returns {boolean}
+   */
+  isDispatchable(request) {
+    return this._inputDispatchable(request)
+      && this._outputDispatchable(request)
+      && this._effectDispatchable(request)
+      && this._capTagsDispatchable(request);
+  }
+
+  _inputDispatchable(request) {
+    if (request.inSpec === 'media:') return true;
+    if (this.inSpec === 'media:') return true;
+    return MediaUrn.fromString(request.inSpec).conformsTo(MediaUrn.fromString(this.inSpec));
+  }
+
+  _outputDispatchable(request) {
+    if (request.outSpec === 'media:') return true;
+    if (this.outSpec === 'media:') return false;
+    return MediaUrn.fromString(this.outSpec).conformsTo(MediaUrn.fromString(request.outSpec));
+  }
+
+  _effectDispatchable(request) {
+    return request.effectValue === CapEffect.ANY || this.effectValue === request.effectValue;
+  }
+
+  _capTagsDispatchable(request) {
+    const allKeys = new Set([
+      ...Object.keys(this.tags),
+      ...Object.keys(request.tags),
+    ]);
+    for (const key of allKeys) {
+      const patt = Object.prototype.hasOwnProperty.call(request.tags, key)
+        ? request.tags[key]
+        : undefined;
+      const inst = Object.prototype.hasOwnProperty.call(this.tags, key)
+        ? this.tags[key]
+        : undefined;
+      if (!taggedUrnValuesMatch(inst, patt)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Infer the runtime output media for a concrete runtime input.
+   *
+   * @param {MediaUrn} runtimeInput
+   * @returns {MediaUrn}
+   */
+  inferRuntimeOutputMedia(runtimeInput) {
+    const declaredIn = this.inMediaUrn();
+    const declaredOut = this.outMediaUrn();
+
+    if (!runtimeInput.conformsTo(declaredIn)) {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_EFFECT_APPLICATION,
+        `Runtime input '${runtimeInput}' does not conform to declared input '${declaredIn}'`
+      );
+    }
+
+    let runtimeOut;
+    switch (this.effectValue) {
+      case CapEffect.DECLARED:
+        runtimeOut = declaredOut;
+        break;
+      case CapEffect.NONE:
+        runtimeOut = runtimeInput;
+        break;
+      case CapEffect.PATCH: {
+        const delta = declaredOut.deltaFrom(declaredIn);
+        runtimeOut = runtimeInput.applyDelta(delta);
+        break;
+      }
+      case CapEffect.ANY:
+        throw new CapUrnError(
+          ErrorCodes.INVALID_EFFECT_APPLICATION,
+          'Cannot infer runtime output for an unconstrained effect request'
+        );
+      default:
+        throw new CapUrnError(
+          ErrorCodes.INVALID_EFFECT_APPLICATION,
+          `Unexpected effect '${this.effectValue}' during runtime output inference`
+        );
+    }
+
+    if (!runtimeOut.conformsTo(declaredOut)) {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_EFFECT_APPLICATION,
+        `Inferred runtime output '${runtimeOut}' does not conform to declared output '${declaredOut}'`
+      );
+    }
+    return runtimeOut;
+  }
+
+  _validateAdmissible() {
+    const inMedia = this.inMediaUrn();
+    const outMedia = this.outMediaUrn();
+    const noExtraTags = Object.keys(this.tags).length === 0;
+
+    if (inMedia.isTop() && outMedia.isTop() && noExtraTags && this.effectValue === CapEffect.DECLARED) {
+      throw new CapUrnError(
+        ErrorCodes.ILLEGAL_DECLARATION,
+        'illegal bare top cap; use cap:effect=none for identity, or declare a non-vacuous input/output/effect/tag'
+      );
+    }
+
+    if (this.effectValue === CapEffect.NONE) {
+      if (!inMedia.conformsTo(outMedia)) {
+        throw new CapUrnError(
+          ErrorCodes.ILLEGAL_DECLARATION,
+          `effect=none requires declared input '${inMedia}' to conform to declared output '${outMedia}'`
+        );
+      }
+      return;
+    }
+
+    if (this.effectValue === CapEffect.PATCH) {
+      const delta = outMedia.deltaFrom(inMedia);
+      const witness = inMedia.applyDelta(delta);
+      if (!witness.conformsTo(outMedia)) {
+        throw new CapUrnError(
+          ErrorCodes.ILLEGAL_DECLARATION,
+          `effect=patch witness '${witness}' does not conform to declared output '${outMedia}'`
+        );
+      }
+    }
+  }
 }
 
 /**
@@ -760,6 +990,7 @@ class CapUrnBuilder {
   constructor() {
     this._inSpec = null;
     this._outSpec = null;
+    this._effect = CapEffect.DECLARED;
     this._tags = {};
   }
 
@@ -785,10 +1016,15 @@ class CapUrnBuilder {
     return this;
   }
 
+  effect(effect) {
+    this._effect = normalizeEffectValue(effect);
+    return this;
+  }
+
   /**
    * Add or update a tag
    * Key is normalized to lowercase; value is preserved as-is
-   * SILENTLY IGNORES attempts to set "in" or "out" - use inSpec/outSpec methods
+   * Structural coordinates are reserved; use dedicated methods instead.
    *
    * @param {string} key - The tag key
    * @param {string} value - The tag value
@@ -796,10 +1032,13 @@ class CapUrnBuilder {
    */
   tag(key, value) {
     const keyLower = key.toLowerCase();
-    // Silently ignore in/out - use inSpec/outSpec methods
-    if (keyLower !== 'in' && keyLower !== 'out') {
-      this._tags[keyLower] = value;
+    if (keyLower === 'in' || keyLower === 'out' || keyLower === 'effect') {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_TAG_FORMAT,
+        `Reserved structural key '${keyLower}' must be set via inSpec(), outSpec(), or effect()`
+      );
     }
+    this._tags[keyLower] = value;
     return this;
   }
 
@@ -813,9 +1052,13 @@ class CapUrnBuilder {
    */
   marker(key) {
     const keyLower = key.toLowerCase();
-    if (keyLower !== 'in' && keyLower !== 'out') {
-      this._tags[keyLower] = '*';
+    if (keyLower === 'in' || keyLower === 'out' || keyLower === 'effect') {
+      throw new CapUrnError(
+        ErrorCodes.INVALID_TAG_FORMAT,
+        `Reserved structural key '${keyLower}' cannot be used as a marker`
+      );
     }
+    this._tags[keyLower] = '*';
     return this;
   }
 
@@ -832,7 +1075,7 @@ class CapUrnBuilder {
     if (!this._outSpec) {
       throw new CapUrnError(ErrorCodes.MISSING_OUT_SPEC, "Cap URN requires 'out' spec - call outSpec() before build()");
     }
-    return new CapUrn(this._inSpec, this._outSpec, this._tags);
+    return new CapUrn(this._inSpec, this._outSpec, this._effect, this._tags);
   }
 }
 
@@ -1128,9 +1371,9 @@ const MEDIA_MEDIA_SPEC_DEFINITION = 'media:media-spec-definition;json;record;tex
 // STANDARD CAP URN CONSTANTS
 // =============================================================================
 
-// Standard echo capability URN
-// Accepts any media type as input and outputs any media type
-const CAP_IDENTITY = 'cap:in=media:;out=media:';
+// Standard identity capability URN.
+// Accepts any media type as input and preserves the runtime media identity.
+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": [...]}.
@@ -1390,6 +1633,20 @@ class MediaUrn {
    */
   isComparable(other) { return this._urn.isComparable(other._urn); }
 
+  /**
+   * Compute the coordinate-space delta from `base` to this media URN.
+   * @param {MediaUrn} base
+   * @returns {TaggedUrnCoordinateDelta}
+   */
+  deltaFrom(base) { return this._urn.deltaFrom(base._urn); }
+
+  /**
+   * Apply a coordinate-space delta to this media URN.
+   * @param {TaggedUrnCoordinateDelta} delta
+   * @returns {MediaUrn}
+   */
+  applyDelta(delta) { return new MediaUrn(this._urn.applyDelta(delta)); }
+
   /**
    * @param {MediaUrn} other
    * @returns {boolean}
@@ -6096,6 +6353,7 @@ class FabricRegistryClient {
 module.exports = {
   CapUrn,
   CapKind,
+  CapEffect,
   CapUrnBuilder,
   CapMatcher,
   CapUrnError,
@@ -6230,6 +6488,7 @@ module.exports = {
   MEDIA_CAP_DEFINITION,
   MEDIA_MEDIA_SPEC_DEFINITION,
   // Standard cap URN constants
+  CAP_IDENTITY,
   CAP_ADAPTER_SELECTION,
   CAP_LOOKUP_CAP_FABRIC,
   CAP_LOOKUP_MEDIA_SPEC_FABRIC,

package/capdag.test.js

@@ -3,7 +3,7 @@
 // All implementations (Rust, Go, JS, ObjC, Python) must pass these identically.
 
 const {
-  CapUrn, CapKind, CapUrnBuilder, CapMatcher, CapUrnError, ErrorCodes,
+  CapUrn, CapKind, CapEffect, CapUrnBuilder, CapMatcher, CapUrnError, ErrorCodes,
   MediaUrn, MediaUrnError, MediaUrnErrorCodes,
   Cap, CapGroup, CapManifest, MediaSpec, MediaSpecError, MediaSpecErrorCodes,
   resolveMediaUrn, buildExtensionIndex, mediaUrnsForExtension, getExtensionMappings,
@@ -26,7 +26,8 @@ const {
   MEDIA_FILE_PATH,
   MEDIA_COLLECTION, MEDIA_COLLECTION_LIST,
   MEDIA_DECISION,
-  MEDIA_AUDIO_SPEECH
+  MEDIA_AUDIO_SPEECH,
+  CAP_IDENTITY
 } = require('./capdag.js');
 
 // ============================================================================
@@ -309,9 +310,15 @@ function test939_capUrnCanonicalFormDropsWildcardInOut() {
       `input ${JSON.stringify(v)} canonicalized to ${JSON.stringify(parsed.toString())}, expected ${JSON.stringify(canonical)} — wildcard in/out segments must be elided so the registry SHA-256 key is stable across input spellings`
     );
   }
-  // Bare-identity round-trip.
-  const identity = CapUrn.fromString('cap:in=media:;out=media:');
-  assertEqual(identity.toString(), 'cap:', 'cap with wildcard in/out and no other tags must canonicalize to bare "cap:"');
+  assertThrows(
+    () => CapUrn.fromString('cap:in=media:;out=media:'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'declared top-to-top cap must be rejected as inadmissible'
+  );
+
+  const identity = CapUrn.fromString('cap:effect=none');
+  assertEqual(identity.toString(), 'cap:effect=none', 'true identity must preserve explicit effect=none');
+  assert(identity.toString() !== generic.toString(), 'cap: and cap:effect=none must not collapse');
 }
 
 // TEST017: Test tag matching: exact match, subset match, wildcard match, value mismatch
@@ -494,17 +501,19 @@ function test027_wildcardTag() {
   assertEqual(wildcardExt.getTag('ext'), '*', 'Should set ext to wildcard');
 
   const wildcardIn = cap.withWildcardTag('in');
-  assertEqual(wildcardIn.getInSpec(), '*', 'Should set in to wildcard');
+  assertEqual(wildcardIn.getInSpec(), 'media:', 'Should set in to canonical top media:');
 
   const wildcardOut = cap.withWildcardTag('out');
-  assertEqual(wildcardOut.getOutSpec(), '*', 'Should set out to wildcard');
+  assertEqual(wildcardOut.getOutSpec(), 'media:', 'Should set out to canonical top media:');
 }
 
-// TEST028: Test empty cap URN defaults to media: wildcard
+// TEST028: Test empty cap URN is illegal
 function test028_emptyCapUrnNotAllowed() {
-  const empty = CapUrn.fromString('cap:');
-  assertEqual(empty.getInSpec(), MEDIA_IDENTITY, 'Empty cap should default in to media:');
-  assertEqual(empty.getOutSpec(), MEDIA_IDENTITY, 'Empty cap should default out to media:');
+  assertThrows(
+    () => CapUrn.fromString('cap:'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Empty cap must be rejected as inadmissible'
+  );
 }
 
 // TEST029: Test minimal valid cap URN has just in and out, empty tags
@@ -683,7 +692,7 @@ function test047_matchingSemanticsThumbnailVoidInput() {
 
 // TEST048: Matching semantics - wildcard direction matches anything
 function test048_matchingSemanticsWildcardDirection() {
-  const cap = CapUrn.fromString('cap:in=*;out=*');
+  const cap = CapUrn.fromString('cap:in=*;out=*;op');
   const request = CapUrn.fromString(testUrn('generate;ext=pdf'));
   assert(cap.accepts(request), 'Wildcard cap should accept any request');
 }
@@ -2542,7 +2551,7 @@ function test1302_predicateConstantConsistency() {
 // cap_urn.rs: TEST1303-TEST1307 (CapUrn tier tests)
 // ============================================================================
 
-// TEST1303: without_tag removes tag, ignores in/out, case-insensitive for keys
+// TEST1303: without_tag removes tag, rejects structural keys, case-insensitive for keys
 function test1303_withoutTag() {
   const cap = CapUrn.fromString('cap:in="media:void";test;ext=pdf;out="media:void"');
   const removed = cap.withoutTag('ext');
@@ -2553,11 +2562,9 @@ function test1303_withoutTag() {
   const removed2 = cap.withoutTag('EXT');
   assertEqual(removed2.getTag('ext'), undefined, 'withoutTag should be case-insensitive');
 
-  // Removing in/out is silently ignored
-  const same = cap.withoutTag('in');
-  assertEqual(same.getInSpec(), 'media:void', 'withoutTag must not remove in');
-  const same2 = cap.withoutTag('out');
-  assertEqual(same2.getOutSpec(), 'media:void', 'withoutTag must not remove out');
+  assertThrows(() => cap.withoutTag('in'), 'withoutTag must reject in');
+  assertThrows(() => cap.withoutTag('out'), 'withoutTag must reject out');
+  assertThrows(() => cap.withoutTag('effect'), 'withoutTag must reject effect');
 
   // Removing non-existent tag is no-op
   const same3 = cap.withoutTag('nonexistent');
@@ -2581,6 +2588,12 @@ function test1304_withInOutSpec() {
   const changedBoth = cap.withInSpec('media:pdf').withOutSpec(MEDIA_TXT);
   assertEqual(changedBoth.getInSpec(), 'media:pdf', 'Chain should set inSpec');
   assertEqual(changedBoth.getOutSpec(), MEDIA_TXT, 'Chain should set outSpec');
+
+  const identity = CapUrn.fromString('cap:effect=none');
+  assertThrows(
+    () => identity.withOutSpec('media:pdf'),
+    'withOutSpec must revalidate admissibility'
+  );
 }
 
 // TEST561: N/A for JS (in_media_urn/out_media_urn not in JS CapUrn)
@@ -2630,15 +2643,28 @@ function test1306_areCompatible() {
 
 // TEST565: N/A for JS (tags_to_string not in JS CapUrn)
 
-// TEST1307: with_tag silently ignores in/out keys
-function test1307_withTagIgnoresInOut() {
+// TEST1307: with_tag rejects structural keys
+function test1307_withTagRejectsStructuralKeys() {
   const cap = CapUrn.fromString('cap:in="media:void";test;out="media:void"');
-  // Attempting to set in/out via withTag is silently ignored
-  const same = cap.withTag('in', 'media:');
-  assertEqual(same.getInSpec(), 'media:void', 'withTag must not change in_spec');
+  assertThrows(() => cap.withTag('in', 'media:'), 'withTag must reject in');
+  assertThrows(() => cap.withTag('out', 'media:'), 'withTag must reject out');
+  assertThrows(() => cap.withTag('effect', 'none'), 'withTag must reject effect');
+}
 
-  const same2 = cap.withTag('out', 'media:');
-  assertEqual(same2.getOutSpec(), 'media:void', 'withTag must not change out_spec');
+// TEST1308: builder rejects structural keys on tag/marker
+function test1308_builderRejectsStructuralKeys() {
+  assertThrows(
+    () => new CapUrnBuilder().tag('in', 'media:void'),
+    'builder.tag must reject structural in'
+  );
+  assertThrows(
+    () => new CapUrnBuilder().marker('effect'),
+    'builder.marker must reject structural effect'
+  );
+  assertThrows(
+    () => new CapUrnBuilder().inSpec('media:void').outSpec('media:record').tag('123', 'value').build(),
+    'builder.build must reject invalid non-structural tags'
+  );
 }
 
 // TEST1294: RULE11 - void-input cap with stdin source rejected
@@ -2697,47 +2723,58 @@ function test1297_rule11NonVoidInputWithStdin() {
 // cap_urn.rs: TEST639-TEST653 (Cap URN wildcard tests)
 // ============================================================================
 
-// TEST639: cap: (empty) defaults to in=media:;out=media:
-function test639_emptyCapDefaultsToMediaWildcard() {
-  const cap = CapUrn.fromString('cap:');
-  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'Empty cap should default in to media:');
-  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'Empty cap should default out to media:');
-  assertEqual(Object.keys(cap.tags).length, 0, 'Empty cap should have no extra tags');
+// TEST639: cap: (empty) is the illegal bare top form
+function test639_emptyCapIsIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Empty cap must be rejected as inadmissible'
+  );
 }
 
-// TEST640: cap:in defaults out to media:
-function test640_inOnlyDefaultsOutToMedia() {
-  const cap = CapUrn.fromString('cap:in');
-  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'Bare in should normalize to media:');
-  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'Missing out should default to media:');
+// TEST640: cap:in collapses to the same illegal bare top form
+function test640_inOnlyIsIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Bare in must be rejected as inadmissible'
+  );
 }
 
-// TEST641: cap:out defaults in to media:
-function test641_outOnlyDefaultsInToMedia() {
-  const cap = CapUrn.fromString('cap:out');
-  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'Missing in should default to media:');
-  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'Bare out should normalize to media:');
+// TEST641: cap:out collapses to the same illegal bare top form
+function test641_outOnlyIsIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:out'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Bare out must be rejected as inadmissible'
+  );
 }
 
-// TEST642: cap:in;out both become media:
-function test642_inOutWithoutValuesBecomeMedia() {
-  const cap = CapUrn.fromString('cap:in;out');
-  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'Bare in should normalize to media:');
-  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'Bare out should normalize to media:');
+// TEST642: cap:in;out collapses to the same illegal bare top form
+function test642_inOutWithoutValuesAreIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in;out'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Bare in/out must be rejected as inadmissible'
+  );
 }
 
-// TEST643: cap:in=*;out=* becomes media:
-function test643_explicitAsteriskIsWildcard() {
-  const cap = CapUrn.fromString('cap:in=*;out=*');
-  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'in=* should normalize to media:');
-  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'out=* should normalize to media:');
+// TEST643: cap:in=*;out=* is the same illegal bare top form
+function test643_explicitAsteriskIsIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=*;out=*'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Explicit wildcard top-to-top must be rejected as inadmissible'
+  );
 }
 
-// TEST644: cap:in=media:;out=* has specific in, wildcard out
-function test644_specificInWildcardOut() {
-  const cap = CapUrn.fromString('cap:in=media:;out=*');
-  assertEqual(cap.getInSpec(), 'media:', 'Should have specific in');
-  assertEqual(cap.getOutSpec(), 'media:', 'Wildcard out should normalize to media:');
+// TEST644: cap:in=media:;out=* is the same illegal bare top form
+function test644_specificInWildcardOutIsIllegal() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=media:;out=*'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'Top-to-top declared form must be rejected as inadmissible'
+  );
 }
 
 // TEST645: cap:in=*;out=media:text has wildcard in, specific out
@@ -2767,8 +2804,8 @@ function test647_invalidOutSpecFails() {
 
 // TEST648: Wildcard in/out match specific caps
 function test648_wildcardAcceptsSpecific() {
-  const wildcard = CapUrn.fromString('cap:in=*;out=*');
-  const specific = CapUrn.fromString('cap:in="media:";out="media:text"');
+  const wildcard = CapUrn.fromString('cap:in=*;out=*;raw');
+  const specific = CapUrn.fromString('cap:in="media:";out="media:text";raw');
 
   assert(wildcard.accepts(specific), 'Wildcard should accept specific');
   assert(specific.conformsTo(wildcard), 'Specific should conform to wildcard');
@@ -2776,52 +2813,105 @@ function test648_wildcardAcceptsSpecific() {
 
 // TEST649: Specificity - wildcard has 0, specific has tag count
 function test649_specificityScoring() {
-  const wildcard = CapUrn.fromString('cap:in=*;out=*');
-  const specific = CapUrn.fromString('cap:in="media:";out="media:text"');
+  const wildcard = CapUrn.fromString('cap:in=*;out=*;raw');
+  const specific = CapUrn.fromString('cap:in="media:";out="media:text";raw');
 
-  assertEqual(wildcard.specificity(), 0, 'Wildcard cap should have 0 specificity');
+  assertEqual(wildcard.specificity(), 2, 'Marker-only wildcard cap should have y-axis specificity only');
   assert(specific.specificity() > 0, 'Specific cap should have non-zero specificity');
 }
 
-// TEST650: N/A for JS (JS requires in/out, cap:in=media:;out=media:;test would fail parsing)
+// TEST650: cap:in=media:;out=media:;test preserves other tags
+function test650_wildcardPreserveOtherTags() {
+  const cap = CapUrn.fromString('cap:in=media:;out=media:;test');
+  assertEqual(cap.getInSpec(), 'media:', 'in spec should remain media:');
+  assertEqual(cap.getOutSpec(), 'media:', 'out spec should remain media:');
+  assertEqual(cap.getEffect(), CapEffect.DECLARED, 'missing effect should default to declared');
+  assert(cap.hasMarkerTag('test'), 'marker tag should be preserved');
+}
 
-// TEST651: All identity forms produce the same CapUrn
-function test651_identityFormsEquivalent() {
+// TEST651: Generic top-to-top spellings are all rejected.
+function test651_wildcardGenericFormsRejected() {
   const forms = [
+    'cap:',
+    'cap:in;out',
     'cap:in=*;out=*',
-    'cap:in="media:";out="media:"',
+    'cap:in=media:;out=media:',
+    'cap:in;out=media:',
+    'cap:in=*;out=media:',
+    'cap:in=media:;out',
+    'cap:in=media:;out=*',
   ];
-
-  const first = CapUrn.fromString(forms[0]);
-  // All forms should produce equivalent caps (wildcard behavior)
-  for (let i = 1; i < forms.length; i++) {
-    const cap = CapUrn.fromString(forms[i]);
-    // Both should accept specific caps
-    const specific = CapUrn.fromString('cap:in="media:";out="media:text"');
-    assert(first.accepts(specific), `Form 0 should accept specific`);
-    assert(cap.accepts(specific), `Form ${i} should accept specific`);
+  for (const form of forms) {
+    assertThrows(
+      () => CapUrn.fromString(form),
+      ErrorCodes.ILLEGAL_DECLARATION,
+      `${form} must be rejected as inadmissible`
+    );
   }
 }
 
-// TEST652: N/A for JS (CAP_IDENTITY constant not in JS)
+// TEST652: CAP_IDENTITY constant names the true identity cap, not bare cap:
+function test652_capIdentityConstantWorks() {
+  const identity = CapUrn.fromString(CAP_IDENTITY);
+  assertEqual(identity.toString(), 'cap:effect=none', 'CAP_IDENTITY must be explicit effect=none');
+  assertEqual(identity.kind(), CapKind.IDENTITY, 'CAP_IDENTITY must classify as identity');
 
-// TEST653: Identity (no tags) does not match specific requests via routing
-function test653_identityRoutingIsolation() {
-  const identity = CapUrn.fromString('cap:in=*;out=*');
-  const specificRequest = CapUrn.fromString('cap:in="media:void";test;out="media:void"');
+  const longForm = CapUrn.fromString('cap:in=media:;out=media:;effect=none');
+  assert(identity.accepts(longForm), 'identity should accept its long form');
+  assert(longForm.accepts(identity), 'long form should accept canonical identity');
 
-  // Identity has specificity 0 (no tags, wildcard directions)
-  assertEqual(identity.specificity(), 0, 'Identity specificity should be 0');
+  assertThrows(
+    () => CapUrn.fromString('cap:'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'bare cap must be rejected as inadmissible'
+  );
+}
 
-  // Specific request has higher specificity
-  assert(specificRequest.specificity() > identity.specificity(),
-    'Specific request should have higher specificity than identity');
+// TEST653: invalid effect=none declarations fail at construction.
+function test653_invalidEffectNoneDeclarationRejected() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=media:pdf;out=media:textable;effect=none'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'invalid effect=none declaration must fail at construction'
+  );
+}
 
-  // CapMatcher should prefer specific over identity
-  const specificCap = CapUrn.fromString('cap:in="media:void";test;out="media:void"');
-  const best = CapMatcher.findBestMatch([identity, specificCap], specificRequest);
-  assert(best !== null, 'Should find a match');
-  assert(best.hasMarkerTag('test'), 'CapMatcher should prefer specific cap over identity');
+// TEST654: effect=none preserves runtime media identity.
+function test654_effectNonePreservesRuntimeMedia() {
+  const decimate = CapUrn.fromString('cap:decimate-sequence;effect=none');
+  const png = MediaUrn.fromString('media:image;png');
+  const pdf = MediaUrn.fromString('media:pdf');
+  assertEqual(decimate.inferRuntimeOutputMedia(png).toString(), png.toString(), 'effect=none should preserve png');
+  assertEqual(decimate.inferRuntimeOutputMedia(pdf).toString(), pdf.toString(), 'effect=none should preserve pdf');
+}
+
+// TEST655: default effect=declared does not preserve runtime refinements.
+function test655_effectDeclaredUsesDeclaredOutput() {
+  const resize = CapUrn.fromString('cap:in=media:image;out=media:image;resize');
+  const png = MediaUrn.fromString('media:image;png;width=4000');
+  assertEqual(
+    resize.inferRuntimeOutputMedia(png).toString(),
+    'media:image',
+    'default declared effect should collapse to declared output'
+  );
+}
+
+// TEST656: invalid effect=none declarations fail hard at construction.
+function test656_invalidEffectNoneFailsHard() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=media:pdf;out=media:textable;effect=none'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'invalid effect=none declaration must fail at construction'
+  );
+}
+
+// TEST657: omitted effect means declared; unconstrained effect must be explicit.
+function test657_effectDispatchRequiresExplicitWildcard() {
+  const noneProvider = CapUrn.fromString('cap:effect=none');
+  const declaredRequest = CapUrn.fromString('cap:raw');
+  const anyRequest = CapUrn.fromString('cap:?effect');
+  assert(!noneProvider.isDispatchable(declaredRequest), 'effect=none should not silently satisfy declared request');
+  assert(noneProvider.isDispatchable(anyRequest), 'explicit ?effect should accept any provider effect');
 }
 
 // ============================================================================
@@ -5481,25 +5571,28 @@ function testRenderer_validateResolvedMachinePayload_rejectsMissingFields() {
 // surface, not a per-port detail.
 // ============================================================================
 
-// TEST1800: Identity classifier — only the bare cap: form qualifies.
-// Adding any tag (even one that doesn't constrain in/out) demotes
-// the cap to Transform because the operation/metadata axis is no
-// longer fully generic.
+// TEST1800: Identity classifier — only explicit effect=none qualifies.
 function test1800_kindIdentityOnlyForBareCap() {
-  const identity = CapUrn.fromString('cap:');
-  assertEqual(identity.kind(), CapKind.IDENTITY, 'cap: should be Identity');
+  const identity = CapUrn.fromString('cap:effect=none');
+  assertEqual(identity.kind(), CapKind.IDENTITY, 'cap:effect=none should be Identity');
 
   for (const spelling of [
-    'cap:in=media:;out=media:',
-    'cap:in=*;out=*',
-    'cap:in=media:',
-    'cap:out=media:',
+    'cap:in=media:;out=media:;effect=none',
+    'cap:effect=none;in=*;out=*',
+    'cap:effect=none;in=media:',
+    'cap:effect=none;out=media:',
   ]) {
     const cap = CapUrn.fromString(spelling);
     assertEqual(cap.kind(), CapKind.IDENTITY,
-      `${spelling} should classify as Identity (canonical form is cap:)`);
+      `${spelling} should classify as Identity`);
   }
 
+  assertThrows(
+    () => CapUrn.fromString('cap:'),
+    ErrorCodes.ILLEGAL_DECLARATION,
+    'bare cap must be rejected as inadmissible'
+  );
+
   const withOp = CapUrn.fromString('cap:passthrough');
   assertEqual(withOp.kind(), CapKind.TRANSFORM,
     'cap:passthrough specifies the operation axis — not Identity');
@@ -5587,7 +5680,7 @@ function test1810_mediaVoidIsAtomic() {
 // once parsed.
 function test1805_kindInvariantUnderCanonicalSpellings() {
   const cases = [
-    { a: 'cap:', b: 'cap:in=media:;out=media:', expected: CapKind.IDENTITY },
+    { a: 'cap:effect=none', b: 'cap:in=media:;out=media:;effect=none', expected: CapKind.IDENTITY },
     {
       a: 'cap:extract;in=media:pdf;out=media:textable',
       b: 'cap:extract;in="media:pdf";out="media:textable"',
@@ -5627,8 +5720,8 @@ function test1805_kindInvariantUnderCanonicalSpellings() {
 
 // TEST1820: A `?`-valued cap-tag scores 0. Same as missing.
 function test1820_specificityQuestionIsZero() {
-  const bare = CapUrn.fromString('cap:');
-  assertEqual(bare.specificity(), 0, 'cap: must score 0 (top of order)');
+  const bare = CapUrn.fromString('cap:?effect');
+  assertEqual(bare.specificity(), 0, 'cap:?effect must score 0 (fully unconstrained request)');
 
   const withQ = CapUrn.fromString('cap:?target');
   assertEqual(withQ.specificity(), 0,
@@ -6023,7 +6116,8 @@ async function runTests() {
   runTest('TEST1304: with_in_out_spec', test1304_withInOutSpec);
   runTest('TEST1305: find_all_matches', test1305_findAllMatches);
   runTest('TEST1306: are_compatible', test1306_areCompatible);
-  runTest('TEST1307: with_tag_ignores_in_out', test1307_withTagIgnoresInOut);
+  runTest('TEST1307: with_tag_rejects_structural_keys', test1307_withTagRejectsStructuralKeys);
+  runTest('TEST1308: builder_rejects_structural_keys', test1308_builderRejectsStructuralKeys);
   runTest('TEST1294: rule11_void_input_with_stdin_rejected', test1294_rule11VoidInputWithStdinRejected);
   runTest('TEST1295: rule11_non_void_input_without_stdin_rejected', test1295_rule11NonVoidInputWithoutStdinRejected);
   runTest('TEST1296: rule11_void_input_cli_flag_only', test1296_rule11VoidInputCliFlagOnly);
@@ -6031,21 +6125,25 @@ async function runTests() {
 
   // cap_urn.rs: TEST639-TEST653 (Cap URN wildcard tests)
   console.log('\n--- cap_urn.rs (wildcard tests) ---');
-  runTest('TEST639: empty_cap_defaults_to_media_wildcard', test639_emptyCapDefaultsToMediaWildcard);
-  runTest('TEST640: in_only_defaults_out_to_media', test640_inOnlyDefaultsOutToMedia);
-  runTest('TEST641: out_only_defaults_in_to_media', test641_outOnlyDefaultsInToMedia);
-  runTest('TEST642: in_out_without_values_become_media', test642_inOutWithoutValuesBecomeMedia);
-  runTest('TEST643: explicit_asterisk_is_wildcard', test643_explicitAsteriskIsWildcard);
-  runTest('TEST644: specific_in_wildcard_out', test644_specificInWildcardOut);
+  runTest('TEST639: empty_cap_is_illegal', test639_emptyCapIsIllegal);
+  runTest('TEST640: in_only_is_illegal', test640_inOnlyIsIllegal);
+  runTest('TEST641: out_only_is_illegal', test641_outOnlyIsIllegal);
+  runTest('TEST642: in_out_without_values_are_illegal', test642_inOutWithoutValuesAreIllegal);
+  runTest('TEST643: explicit_asterisk_is_illegal', test643_explicitAsteriskIsIllegal);
+  runTest('TEST644: specific_in_wildcard_out_is_illegal', test644_specificInWildcardOutIsIllegal);
   runTest('TEST645: wildcard_in_specific_out', test645_wildcardInSpecificOut);
   runTest('TEST646: invalid_in_spec_fails', test646_invalidInSpecFails);
   runTest('TEST647: invalid_out_spec_fails', test647_invalidOutSpecFails);
   runTest('TEST648: wildcard_accepts_specific', test648_wildcardAcceptsSpecific);
   runTest('TEST649: specificity_scoring', test649_specificityScoring);
-  console.log('  SKIP TEST650: N/A for JS (requires in/out)');
-  runTest('TEST651: identity_forms_equivalent', test651_identityFormsEquivalent);
-  console.log('  SKIP TEST652: N/A for JS (CAP_IDENTITY constant)');
-  runTest('TEST653: identity_routing_isolation', test653_identityRoutingIsolation);
+  runTest('TEST650: wildcard_preserve_other_tags', test650_wildcardPreserveOtherTags);
+  runTest('TEST651: wildcard_generic_forms_rejected', test651_wildcardGenericFormsRejected);
+  runTest('TEST652: cap_identity_constant_works', test652_capIdentityConstantWorks);
+  runTest('TEST653: invalid_effect_none_declaration_rejected', test653_invalidEffectNoneDeclarationRejected);
+  runTest('TEST654: effect_none_preserves_runtime_media', test654_effectNonePreservesRuntimeMedia);
+  runTest('TEST655: effect_declared_uses_declared_output', test655_effectDeclaredUsesDeclaredOutput);
+  runTest('TEST656: invalid_effect_none_fails_hard', test656_invalidEffectNoneFailsHard);
+  runTest('TEST657: effect_dispatch_requires_explicit_wildcard', test657_effectDispatchRequiresExplicitWildcard);
 
   // machine module: parser tests (mirrors parser.rs)
   console.log('\n--- machine/parser.rs ---');
@@ -6219,7 +6317,7 @@ async function runTests() {
   runTest('RENDERER: validateResolvedMachine_rejectsMissingFields', testRenderer_validateResolvedMachinePayload_rejectsMissingFields);
 
   console.log('\n--- CapKind classifier (test1800–test1805) ---');
-  runTest('TEST1800: kind_identity_only_for_bare_cap',      test1800_kindIdentityOnlyForBareCap);
+  runTest('TEST1800: kind_identity_requires_effect_none',   test1800_kindIdentityOnlyForBareCap);
   runTest('TEST1801: kind_source_when_input_is_void',       test1801_kindSourceWhenInputIsVoid);
   runTest('TEST1802: kind_sink_when_output_is_void',        test1802_kindSinkWhenOutputIsVoid);
   runTest('TEST1803: kind_effect_when_both_sides_void',     test1803_kindEffectWhenBothSidesVoid);

package/package.json

@@ -2,7 +2,7 @@
   "author": "Bahram Joharshamshiri",
   "dependencies": {
     "peggy": "^5.1.0",
-    "tagged-urn": "^0.40.107"
+    "tagged-urn": "^0.42.114"
   },
   "description": "JavaScript implementation of Cap URN (Capability Uniform Resource Names) with strict validation and matching",
   "engines": {
@@ -40,5 +40,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "0.180.452"
+  "version": "0.182.459"
 }