capdag 0.161.384 → 0.165.398

package/README.md

@@ -95,7 +95,7 @@ Utility for matching sets of caps:
 const { CapUrnError, ErrorCodes } = require('capdag');
 
 try {
-  const cap = CapUrn.fromString('cap:op=extract'); // Missing in/out
+  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

package/RULES.md

@@ -17,7 +17,7 @@ Cap URNs **must** include `in` and `out` tags that specify input/output media ty
 const cap = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
 
 // Invalid - missing direction specifiers
-CapUrn.fromString('cap:op=extract'); // throws ErrorCodes.MISSING_IN_SPEC
+CapUrn.fromString('cap:extract;in=media:;out=media:'); // throws ErrorCodes.MISSING_IN_SPEC
 ```
 
 ### 2. Media URN Validation

package/capdag.js

@@ -2,7 +2,7 @@
 // Follows the exact same rules as Rust, Go, and Objective-C implementations
 
 // Import TaggedUrn from the tagged-urn package
-const { TaggedUrn } = require('tagged-urn');
+const { TaggedUrn, valuesMatch: taggedUrnValuesMatch } = require('tagged-urn');
 
 /**
  * Error types for Cap URN operations
@@ -113,7 +113,52 @@ function validatePreservedDirectionSpec(spec, tagName) {
   }
 }
 
+// Per-tag truth-table specificity scoring is owned by the
+// tagged-urn module — same scorer applies uniformly to media-URN
+// tags, cap-tag y-axis, and any other Tagged URN dimension. We
+// re-use the canonical implementation rather than duplicate it.
+const { scoreTagValue } = require('tagged-urn');
+
+/**
+ * Functional category of a cap, derived from all three axes (`in`,
+ * `out`, 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.
+ *
+ * `media:void` is the **unit type** (no meaningful value). `media:`
+ * is the **top type** (universal wildcard). With those anchors the
+ * five kinds fall out:
+ *
+ *   IDENTITY   in=media:, out=media:, 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.
+ *
+ * String values are snake_case to match other capdag enum
+ * serializations on the wire.
+ */
+const CapKind = Object.freeze({
+  IDENTITY: 'identity',
+  SOURCE: 'source',
+  SINK: 'sink',
+  EFFECT: 'effect',
+  TRANSFORM: 'transform',
+});
+
 class CapUrn {
+  // Per-axis weights for cap-URN specificity. Two orders of
+  // magnitude separate each axis to keep them in distinct digit
+  // slots while folding into a single comparable integer.
+  //   spec_C(c) = WEIGHT_OUT*spec_U(out) + WEIGHT_IN*spec_U(in) + spec_U(y)
+  static WEIGHT_OUT = 10000;
+  static WEIGHT_IN = 100;
+
   /**
    * Create a new CapUrn with direction specs.
    * @param {string} inSpec - Input media URN (e.g., "media:void")
@@ -167,6 +212,39 @@ class CapUrn {
     return MediaUrn.fromString(this.outSpec);
   }
 
+  /**
+   * 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).
+   *
+   * 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.
+   *
+   * @returns {string} A {@link CapKind} value (snake_case string).
+   * @throws {MediaUrnError} If either side is not a valid media URN
+   *   (only happens on internally inconsistent state since
+   *   construction validates both sides).
+   */
+  kind() {
+    const inMedia = this.inMediaUrn();
+    const outMedia = this.outMediaUrn();
+
+    const inVoid = inMedia.isVoid();
+    const outVoid = outMedia.isVoid();
+    const inTop = inMedia.isTop();
+    const outTop = outMedia.isTop();
+    const noExtraTags = Object.keys(this.tags).length === 0;
+
+    if (inTop && outTop && noExtraTags) return CapKind.IDENTITY;
+    if (inVoid && outVoid) return CapKind.EFFECT;
+    if (inVoid) return CapKind.SOURCE;
+    if (outVoid) return CapKind.SINK;
+    return CapKind.TRANSFORM;
+  }
+
   /**
    * Create a Cap URN from string representation
    * Format: cap:in="<media-urn>";out="<media-urn>";key1=value1;key2=value2;...
@@ -279,10 +357,20 @@ class CapUrn {
    * @returns {string} The canonical string representation
    */
   toString() {
-    // Build complete tags map including in and out
-    const allTags = { ...this.tags, 'in': this.inSpec, 'out': this.outSpec };
+    // `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.
+    const allTags = { ...this.tags };
+    if (this.inSpec !== 'media:') {
+      allTags['in'] = this.inSpec;
+    }
+    if (this.outSpec !== 'media:') {
+      allTags['out'] = this.outSpec;
+    }
 
-    // Use TaggedUrn for canonical serialization
     const taggedUrn = new TaggedUrn('cap', allTags, true);
     return taggedUrn.toString();
   }
@@ -327,6 +415,25 @@ class CapUrn {
     return tagValue !== undefined && tagValue === value;
   }
 
+  /**
+   * Check whether a marker tag (a tag whose value is "*") is present at the
+   * given key. Equivalent to hasTag(tagName, "*") but expresses authorial
+   * intent: this tag is present as a marker (a wildcard-valued tag that
+   * serializes as just the key), not as a key=value pair. Direction specs
+   * (in/out) are not markers.
+   * Example: cap:constrained;... has marker tag "constrained".
+   *
+   * @param {string} tagName - The marker key
+   * @returns {boolean} Whether the tag exists with value "*"
+   */
+  hasMarkerTag(tagName) {
+    const keyLower = tagName.toLowerCase();
+    if (keyLower === 'in' || keyLower === 'out') {
+      return false;
+    }
+    return this.tags[keyLower] === '*';
+  }
+
   /**
    * Create a new cap URN with an added or updated tag.
    * Attempts to set `in` / `out` through `withTag` are ignored; use
@@ -432,23 +539,25 @@ class CapUrn {
       }
     }
 
-    // Check all tags required by the pattern. Missing tags in the instance reject.
-    for (const [patternKey, patternValue] of Object.entries(this.tags)) {
-      const requestValue = request.tags[patternKey];
-
-      if (requestValue === undefined) {
-        return false;
-      }
-
-      if (patternValue === '*' || requestValue === '*') {
-        continue;
-      }
-
-      if (patternValue !== requestValue) {
+    // 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
+    // missing-on-instance cells both get evaluated.
+    const allKeys = new Set([
+      ...Object.keys(this.tags),
+      ...Object.keys(request.tags),
+    ]);
+    for (const key of allKeys) {
+      const patt = Object.prototype.hasOwnProperty.call(this.tags, key)
+        ? this.tags[key]
+        : undefined;
+      const inst = Object.prototype.hasOwnProperty.call(request.tags, key)
+        ? request.tags[key]
+        : undefined;
+      if (!taggedUrnValuesMatch(inst, patt)) {
         return false;
       }
     }
-
     return true;
   }
 
@@ -464,29 +573,42 @@ class CapUrn {
   }
 
   /**
-   * Calculate specificity score for cap matching
+   * Calculate specificity score for cap matching.
+   *
+   * Weighted sum of the per-tag truth-table score across the three
+   * axes (`out`, `in`, `y`):
+   *
+   *   spec_C(c) = WEIGHT_OUT * spec_U(c.out)
+   *             + WEIGHT_IN  * spec_U(c.in)
+   *             +              spec_U(c.y)
+   *
+   * Per-tag ladder:
+   *
+   *   "?"            -> 0   (no constraint)
+   *   starts "?="    -> 1   (absent or not v)
+   *   "*"            -> 2   (must-have-any)
+   *   starts "!="    -> 3   (present and not v)
+   *   exact value    -> 4   (exact match)
+   *   "!"            -> 5   (must-not-have)
    *
-   * More specific caps have higher scores and are preferred.
-   * Direction specs contribute their MediaUrn tag count (more tags = more specific).
-   * Other tags contribute 1 per non-wildcard value.
+   * The lexicographic priority `(out, in, y)` reflects the routing
+   * intent: producing different things is the largest semantic
+   * difference between two caps; consuming different things is next;
+   * descriptive y-axis metadata is last.
    *
    * @returns {number} The specificity score
    */
   specificity() {
-    let count = 0;
-    // Direction specs contribute their MediaUrn tag count. `media:` is the
-    // wildcard top and contributes zero.
-    if (this.inSpec !== 'media:' && this.inSpec !== '*') {
-      const inMedia = TaggedUrn.fromString(this.inSpec);
-      count += Object.keys(inMedia.tags).length;
-    }
-    if (this.outSpec !== 'media:' && this.outSpec !== '*') {
-      const outMedia = TaggedUrn.fromString(this.outSpec);
-      count += Object.keys(outMedia.tags).length;
+    const inUrn = TaggedUrn.fromString(this.inSpec);
+    const outUrn = TaggedUrn.fromString(this.outSpec);
+
+    let yScore = 0;
+    for (const value of Object.values(this.tags)) {
+      yScore += scoreTagValue(value);
     }
-    // Count non-wildcard tags
-    count += Object.values(this.tags).filter(value => value !== '*').length;
-    return count;
+    return CapUrn.WEIGHT_OUT * outUrn.specificity()
+         + CapUrn.WEIGHT_IN  * inUrn.specificity()
+         + yScore;
   }
 
   /**
@@ -687,6 +809,22 @@ class CapUrnBuilder {
     return this;
   }
 
+  /**
+   * Add a marker tag (a wildcard-valued tag that serializes as just the key).
+   * Equivalent to tag(key, "*") but expresses authorial intent: this tag is
+   * present as a marker, not a key=value pair.
+   *
+   * @param {string} key - The marker key
+   * @returns {CapUrnBuilder} This builder instance for chaining
+   */
+  marker(key) {
+    const keyLower = key.toLowerCase();
+    if (keyLower !== 'in' && keyLower !== 'out') {
+      this._tags[keyLower] = '*';
+    }
+    return this;
+  }
+
   /**
    * Build the final CapUrn
    *
@@ -1009,6 +1147,11 @@ class MediaUrnError extends Error {
 
 const MediaUrnErrorCodes = {
   INVALID_PREFIX: 'INVALID_PREFIX',
+  /** `media:void` was combined with one or more other tags. The unit
+   * type is atomic — there is no lattice underneath it. Reasons for
+   * "why void was used" belong on cap-tags or args, not on the
+   * media URN. */
+  VOID_NOT_ATOMIC: 'VOID_NOT_ATOMIC',
 };
 
 /**
@@ -1026,6 +1169,17 @@ class MediaUrn {
         `Expected prefix 'media', got '${taggedUrn.getPrefix()}'`
       );
     }
+    // Enforce media:void atomicity. The unit type has no lattice
+    // underneath it; refinements are conceptually wrong.
+    const tagKeys = Object.keys(taggedUrn.tags);
+    if (tagKeys.includes('void') && tagKeys.length > 1) {
+      const extras = tagKeys.filter((k) => k !== 'void').sort();
+      throw new MediaUrnError(
+        MediaUrnErrorCodes.VOID_NOT_ATOMIC,
+        `media:void is atomic and cannot be refined; got extra tag(s): ${extras.join(', ')}. ` +
+          'Move why/how this void is used into cap-tags or args, not the media URN.'
+      );
+    }
     this._urn = taggedUrn;
   }
 
@@ -1103,9 +1257,18 @@ class MediaUrn {
   /** @returns {boolean} True if the "textable" marker tag is present */
   isText() { return this._urn.getTag('textable') !== undefined; }
 
-  /** @returns {boolean} True if the "void" marker tag is present */
+  /** @returns {boolean} True if the "void" marker tag is present —
+   *  the **unit type** in the type-theoretic reading. media:void is
+   *  the nullary value; NOT "invalid" or "absent". */
   isVoid() { return this._urn.getTag('void') !== undefined; }
 
+  /** @returns {boolean} True if this is the **top** media URN — the
+   *  universal wildcard `media:` with no tags. Order-theoretically,
+   *  every other media URN conformsTo this one. Distinct from
+   *  isVoid(): top means "any data type accepted here," void means
+   *  "no data flows here." */
+  isTop() { return Object.keys(this._urn.tags).length === 0; }
+
   /** @returns {boolean} True if the "image" marker tag is present */
   isImage() { return this._urn.getTag('image') !== undefined; }
 
@@ -1232,7 +1395,7 @@ class MediaUrn {
  */
 function llmGenerateTextUrn() {
   return new CapUrnBuilder()
-    .tag('op', 'generate_text')
+    .marker('generate_text')
     .tag('llm', '*')
     .tag('ml-model', '*')
     .inSpec(MEDIA_STRING)
@@ -1247,7 +1410,7 @@ function llmGenerateTextUrn() {
  */
 function renderPageImageUrn(inputMedia) {
   return new CapUrnBuilder()
-    .tag('op', 'render_page_image')
+    .marker('render_page_image')
     .inSpec(inputMedia)
     .outSpec(MEDIA_PNG)
     .build();
@@ -1261,7 +1424,7 @@ function renderPageImageUrn(inputMedia) {
  */
 function formatConversionUrn(inMedia, outMedia) {
   return new CapUrnBuilder()
-    .tag('op', 'convert_format')
+    .marker('convert_format')
     .inSpec(inMedia)
     .outSpec(outMedia)
     .build();
@@ -1294,7 +1457,7 @@ function mediaUrnForType(typeName) {
  */
 function modelAvailabilityUrn() {
   return new CapUrnBuilder()
-    .tag('op', 'model-availability')
+    .marker('model-availability')
     .inSpec(MEDIA_MODEL_SPEC)
     .outSpec(MEDIA_AVAILABILITY_OUTPUT)
     .build();
@@ -1306,7 +1469,7 @@ function modelAvailabilityUrn() {
  */
 function modelPathUrn() {
   return new CapUrnBuilder()
-    .tag('op', 'model-path')
+    .marker('model-path')
     .inSpec(MEDIA_MODEL_SPEC)
     .outSpec(MEDIA_PATH_OUTPUT)
     .build();
@@ -4528,6 +4691,24 @@ class CartridgeRepoServer {
  * Reasons why a cartridge attachment attempt failed.
  * Mirrors Rust CartridgeAttachmentErrorKind.
  */
+const CartridgeLifecycle = Object.freeze({
+  // Discovery scan has found the version directory and is about
+  // to inspect it. Transient.
+  DISCOVERED: 'discovered',
+  // Reading cartridge.json, computing directory hash, validating
+  // on-disk install context. Hashing can take seconds for large
+  // model cartridges; runs on a background queue so other
+  // cartridges' inspections proceed in parallel.
+  INSPECTING: 'inspecting',
+  // Inspection succeeded; awaiting a verdict from the registry
+  // verifier service. Skipped for dev cartridges
+  // (registry_url == null) and bundle cartridges.
+  VERIFYING: 'verifying',
+  // Cleared every gate. Caps are registered with the engine and
+  // dispatch can route requests to this cartridge.
+  OPERATIONAL: 'operational',
+});
+
 const CartridgeAttachmentErrorKind = Object.freeze({
   INCOMPATIBLE: 'incompatible',
   MANIFEST_INVALID: 'manifest_invalid',
@@ -4636,9 +4817,9 @@ class CartridgeRuntimeStats {
 /**
  * Full identity of an installed cartridge, including optional attachment error
  * and runtime statistics.
- * Mirrors Rust InstalledCartridgeIdentity.
+ * Mirrors Rust InstalledCartridgeRecord.
  */
-class InstalledCartridgeIdentity {
+class InstalledCartridgeRecord {
   /**
    * @param {Object} opts
    * @param {string|null} [opts.registryUrl=null]
@@ -4649,8 +4830,9 @@ class InstalledCartridgeIdentity {
    * @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`.
    */
-  constructor({ registryUrl = null, channel, id, version, sha256, capGroups = [], attachmentError = null, runtimeStats = null }) {
+  constructor({ registryUrl = null, channel, id, version, sha256, capGroups = [], attachmentError = null, runtimeStats = null, lifecycle = 'discovered' }) {
     this.registry_url = registryUrl;
     this.channel = channel;
     this.id = id;
@@ -4659,6 +4841,7 @@ class InstalledCartridgeIdentity {
     this.cap_groups = capGroups;
     this.attachment_error = attachmentError;
     this.runtime_stats = runtimeStats;
+    this.lifecycle = lifecycle;
   }
 
   toJSON() {
@@ -4667,6 +4850,7 @@ class InstalledCartridgeIdentity {
       id: this.id,
       version: this.version,
       sha256: this.sha256,
+      lifecycle: this.lifecycle,
     };
     if (this.registry_url !== null) obj.registry_url = this.registry_url;
     if (this.cap_groups && this.cap_groups.length > 0) obj.cap_groups = this.cap_groups;
@@ -4676,7 +4860,7 @@ class InstalledCartridgeIdentity {
   }
 
   static fromJSON(d) {
-    return new InstalledCartridgeIdentity({
+    return new InstalledCartridgeRecord({
       registryUrl: d.registry_url !== undefined ? d.registry_url : null,
       channel: d.channel,
       id: d.id,
@@ -4685,6 +4869,9 @@ class InstalledCartridgeIdentity {
       capGroups: Array.isArray(d.cap_groups) ? d.cap_groups : [],
       attachmentError: d.attachment_error ? CartridgeAttachmentError.fromJSON(d.attachment_error) : null,
       runtimeStats: d.runtime_stats ? CartridgeRuntimeStats.fromJSON(d.runtime_stats) : null,
+      // Default to 'discovered' (the safe sentinel) — never
+      // 'operational' — when the field is missing from the wire.
+      lifecycle: typeof d.lifecycle === 'string' ? d.lifecycle : 'discovered',
     });
   }
 
@@ -5190,19 +5377,14 @@ class Machine {
       return ea.target.toString().localeCompare(eb.target.toString());
     });
 
-    // Step 2: Generate aliases from op= tag
+    // Step 2: Generate edge aliases. The Rust reference implementation
+    // uses `edge_<idx>` unconditionally — there is no privileged tag (such
+    // as the legacy `op=…` tag) we can derive a friendlier name from, so
+    // we mirror the same pure-index scheme here.
     const aliases = new Map();
-    const aliasCounts = new Map();
-
     for (const idx of edgeOrder) {
       const edge = this._edges[idx];
-      const opTag = edge.capUrn.getTag('op');
-      const baseAlias = opTag !== undefined ? opTag : `edge_${idx}`;
-
-      const count = aliasCounts.get(baseAlias) || 0;
-      const alias = count === 0 ? baseAlias : `${baseAlias}_${count}`;
-      aliasCounts.set(baseAlias, count + 1);
-
+      const alias = `edge_${idx}`;
       const capStr = edge.capUrn.toString();
       aliases.set(alias, { edgeIdx: idx, capStr });
     }
@@ -5273,16 +5455,17 @@ class Machine {
     // Define edges
     for (const edgeIdx of edgeOrder) {
       const edge = this._edges[edgeIdx];
-      // Find alias for this edge
-      let edgeLabel = null;
+      // Find alias for this edge. The label on the rendered diagram is the
+      // edge's alias (`edge_<idx>`), matching the Rust serializer which
+      // also uses pure-index aliases — no special tag (like the legacy
+      // `op=…`) is privileged for label derivation.
+      let label = null;
       for (const [a, info] of aliases) {
         if (info.edgeIdx === edgeIdx) {
-          edgeLabel = a;
+          label = a;
           break;
         }
       }
-      const opTag = edge.capUrn.getTag('op');
-      const label = opTag !== undefined ? opTag : edgeLabel;
 
       const targetKey = edge.target.toString();
       const targetName = nodeNames.get(targetKey);
@@ -5811,6 +5994,7 @@ class CapRegistryClient {
 // Export for CommonJS
 module.exports = {
   CapUrn,
+  CapKind,
   CapUrnBuilder,
   CapMatcher,
   CapUrnError,
@@ -5966,10 +6150,11 @@ module.exports = {
   CartridgeRepoServer,
   CartridgeChannel,
   // Bifaci — cartridge attachment & runtime identity
+  CartridgeLifecycle,
   CartridgeAttachmentErrorKind,
   CartridgeAttachmentError,
   CartridgeRuntimeStats,
-  InstalledCartridgeIdentity,
+  InstalledCartridgeRecord,
   // Registry slug
   DEV_SLUG,
   SLUG_HEX_LEN,

package/capdag.test.js

@@ -3,7 +3,7 @@
 // All implementations (Rust, Go, JS, ObjC, Python) must pass these identically.
 
 const {
-  CapUrn, CapUrnBuilder, CapMatcher, CapUrnError, ErrorCodes,
+  CapUrn, CapKind, CapUrnBuilder, CapMatcher, CapUrnError, ErrorCodes,
   MediaUrn, MediaUrnError, MediaUrnErrorCodes,
   Cap, MediaSpec, MediaSpecError, MediaSpecErrorCodes,
   resolveMediaUrn, buildExtensionIndex, mediaUrnsForExtension, getExtensionMappings,
@@ -131,7 +131,7 @@ function makeGraphCap(inUrn, outUrn, title) {
 // TEST001: Test that cap URN is created with tags parsed correctly and direction specs accessible
 function test001_capUrnCreation() {
   const cap = CapUrn.fromString(testUrn('generate;ext=pdf;target=thumbnail'));
-  assertEqual(cap.getTag('op'), 'generate', 'Should get op tag');
+  assert(cap.hasMarkerTag('generate'), 'Should get op tag');
   assertEqual(cap.getTag('target'), 'thumbnail', 'Should get target tag');
   assertEqual(cap.getTag('ext'), 'pdf', 'Should get ext tag');
   assertEqual(cap.getInSpec(), MEDIA_VOID, 'Should get inSpec');
@@ -140,19 +140,19 @@ function test001_capUrnCreation() {
 
 // TEST002: Test that missing 'in' or 'out' defaults to media: wildcard
 function test002_directionSpecsRequired() {
-  const missingIn = CapUrn.fromString('cap:out="media:void";op=test');
+  const missingIn = CapUrn.fromString('cap:in=media:;out=media:void;test');
   assertEqual(missingIn.getInSpec(), MEDIA_IDENTITY, 'Missing in should default to media:');
   assertEqual(missingIn.getOutSpec(), MEDIA_VOID, 'Explicit out should be preserved');
 
-  const missingOut = CapUrn.fromString('cap:in="media:void";op=test');
+  const missingOut = CapUrn.fromString('cap:in=media:void;out=media:;test');
   assertEqual(missingOut.getInSpec(), MEDIA_VOID, 'Explicit in should be preserved');
   assertEqual(missingOut.getOutSpec(), MEDIA_IDENTITY, 'Missing out should default to media:');
 }
 
 // TEST003: Test that direction specs must match exactly, different in/out types don't match, wildcard matches any
 function test003_directionMatching() {
-  const cap = CapUrn.fromString(testUrn('op=generate'));
-  const request = CapUrn.fromString(testUrn('op=generate'));
+  const cap = CapUrn.fromString(testUrn('generate'));
+  const request = CapUrn.fromString(testUrn('generate'));
   assert(cap.accepts(request), 'Same direction specs should match');
 
   // Different direction should not match
@@ -166,8 +166,8 @@ function test003_directionMatching() {
 
 // TEST004: Test that unquoted keys and values are normalized to lowercase
 function test004_unquotedValuesLowercased() {
-  const cap = CapUrn.fromString('cap:IN="media:void";OP=Generate;EXT=PDF;OUT="media:record;textable"');
-  assertEqual(cap.getTag('op'), 'generate', 'Unquoted value should be lowercased');
+  const cap = CapUrn.fromString('cap:ext=pdf;generate;in=media:void;out="media:record;textable"');
+  assert(cap.hasMarkerTag('generate'), 'Unquoted value should be lowercased');
   assertEqual(cap.getTag('ext'), 'pdf', 'Unquoted value should be lowercased');
   // Key lookup is case-insensitive
   assertEqual(cap.getTag('OP'), 'generate', 'Key lookup should be case-insensitive');
@@ -265,13 +265,13 @@ function test014_roundTripEscapes() {
 // TEST015: Test that cap: prefix is required and case-insensitive
 function test015_capPrefixRequired() {
   assertThrows(
-    () => CapUrn.fromString('in="media:void";out="media:void";op=generate'),
+    () => CapUrn.fromString('in="media:void";out="media:void";generate'),
     ErrorCodes.MISSING_CAP_PREFIX,
     'Should require cap: prefix'
   );
   // Valid cap: prefix should work
-  const cap = CapUrn.fromString(testUrn('op=generate'));
-  assertEqual(cap.getTag('op'), 'generate', 'Should parse with valid cap: prefix');
+  const cap = CapUrn.fromString(testUrn('generate'));
+  assert(cap.hasMarkerTag('generate'), 'Should parse with valid cap: prefix');
 }
 
 // TEST016: Test that trailing semicolon is equivalent (same hash, same string, matches)
@@ -291,8 +291,8 @@ function test017_tagMatching() {
   assert(cap.accepts(exact), 'Should accept exact match');
   assert(exact.accepts(cap), 'Exact match should accept in reverse too');
 
-  // Routing direction: request(op=generate) accepts cap(op,ext,target)
-  const subset = CapUrn.fromString(testUrn('op=generate'));
+  // Routing direction: request(generate) accepts cap(op,ext,target)
+  const subset = CapUrn.fromString(testUrn('generate'));
   assert(subset.accepts(cap), 'General request should accept more specific instance');
   assert(!cap.accepts(subset), 'Specific pattern should reject subset instance');
 
@@ -301,7 +301,7 @@ function test017_tagMatching() {
   assert(wildcard.accepts(cap), 'Wildcard request should accept specific instance');
 
   // Conflicting value — neither direction accepts
-  const mismatch = CapUrn.fromString(testUrn('op=extract'));
+  const mismatch = CapUrn.fromString(testUrn('extract'));
   assert(!cap.accepts(mismatch), 'Should not accept value mismatch');
   assert(!mismatch.accepts(cap), 'Reverse mismatch should also reject');
 }
@@ -315,34 +315,52 @@ function test018_matchingCaseSensitiveValues() {
 
 // TEST019: Missing tag in instance causes rejection — pattern's tags are constraints
 function test019_missingTagHandling() {
-  const cap = CapUrn.fromString(testUrn('op=generate'));
+  const cap = CapUrn.fromString(testUrn('generate'));
   const request = CapUrn.fromString(testUrn('ext=pdf'));
   assert(!cap.accepts(request), 'Pattern requiring op should reject instance missing op');
   assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
 
   const cap2 = CapUrn.fromString(testUrn('generate;ext=pdf'));
-  const request2 = CapUrn.fromString(testUrn('op=generate'));
+  const request2 = CapUrn.fromString(testUrn('generate'));
   assert(!cap2.accepts(request2), 'Specific pattern should reject instance missing ext');
   assert(request2.accepts(cap2), 'General request should accept more specific instance');
 }
 
-// TEST020: Test specificity calculation (direction specs use MediaUrn tag count, wildcards don't count)
+// TEST020: Specificity is the sum of per-tag truth-table scores
+// across in/out/y. Marker tags (bare segments and `key=*`) score 2
+// (must-have-any), exact `key=value` tags score 3, missing/`?` score
+// 0, `!` scores 1.
+//
+// testUrn() builds "cap:in=media:void;out=media:record;<tags>" so
+// the directional baseline is:
+//   in:  media:void   -> {void=*}    -> 2
+//   out: media:record -> {record=*}  -> 2
+// Total directional baseline: 4.
 function test020_specificity() {
-  // Direction specs contribute their MediaUrn tag count:
-  // MEDIA_VOID = "media:void" -> 1 tag (void)
-  // MEDIA_OBJECT = "media:record" -> 1 tag (record)
+  // testUrn() prepends in="media:void" (1 marker, score 2) and
+  // out="media:record" (1 marker, score 2). Cap-URN spec is
+  // 10000*spec_U(out) + 100*spec_U(in) + spec_U(y).
+
   const cap1 = CapUrn.fromString(testUrn('type=general'));
-  assertEqual(cap1.specificity(), 3, 'void(1) + record(1) + type(1)');
+  // out=2, in=2, y=4 (type=general exact)
+  assertEqual(cap1.specificity(), 10000*2 + 100*2 + 4,
+    'out=2, in=2, y=type=general exact=4 -> 20204');
 
-  const cap2 = CapUrn.fromString(testUrn('op=generate'));
-  assertEqual(cap2.specificity(), 3, 'void(1) + record(1) + op(1)');
+  const cap2 = CapUrn.fromString(testUrn('generate'));
+  // out=2, in=2, y=2 (generate marker = must-have-any)
+  assertEqual(cap2.specificity(), 10000*2 + 100*2 + 2,
+    'out=2, in=2, y=generate marker=2 -> 20202');
 
-  const cap3 = CapUrn.fromString(testUrn('op=*;ext=pdf'));
-  assertEqual(cap3.specificity(), 3, 'void(1) + record(1) + ext(1) (wildcard op doesn\'t count)');
+  const cap3 = CapUrn.fromString(testUrn('op;ext=pdf'));
+  // out=2, in=2, y=2+4 (op marker, ext=pdf exact)
+  assertEqual(cap3.specificity(), 10000*2 + 100*2 + 6,
+    'out=2, in=2, y=op marker(2)+ext=pdf exact(4) -> 20206');
 
-  // Wildcard in direction doesn't count
-  const cap4 = CapUrn.fromString(`cap:in=*;out="${MEDIA_OBJECT}";op=test`);
-  assertEqual(cap4.specificity(), 2, 'record(1) + op(1) (in wildcard doesn\'t count)');
+  // Wildcard in direction normalizes to media: (no tags, score 0).
+  const cap4 = CapUrn.fromString(`cap:in=*;out="${MEDIA_OBJECT}";test`);
+  // out=2 (record=*), in=0 (media: empty), y=2 (test marker)
+  assertEqual(cap4.specificity(), 10000*2 + 100*0 + 2,
+    'out=record=2, in=*->0, y=test marker=2 -> 20002');
 }
 
 // TEST021: Test builder creates cap URN with correct tags and direction specs
@@ -353,7 +371,7 @@ function test021_builder() {
     .tag('op', 'generate')
     .tag('ext', 'pdf')
     .build();
-  assertEqual(cap.getTag('op'), 'generate', 'Builder should set op');
+  assert(cap.hasMarkerTag('generate'), 'Builder should set op');
   assertEqual(cap.getTag('ext'), 'pdf', 'Builder should set ext');
   assertEqual(cap.getInSpec(), 'media:void', 'Builder should set inSpec');
   assertEqual(cap.getOutSpec(), 'media:object', 'Builder should set outSpec');
@@ -388,14 +406,14 @@ function test023_builderPreservesCase() {
 function test024_compatibility() {
   const cap1 = CapUrn.fromString(testUrn('generate;ext=pdf'));
   const cap2 = CapUrn.fromString(testUrn('generate;format=*'));
-  const cap3 = CapUrn.fromString(testUrn('type=image;op=extract'));
+  const cap3 = CapUrn.fromString(testUrn('type=image;extract'));
 
   assert(!cap1.accepts(cap2), 'Pattern requiring ext should reject instance missing ext');
   assert(!cap2.accepts(cap1), 'Pattern requiring format should reject instance missing format');
   assert(!cap1.accepts(cap3), 'Different op should not accept');
   assert(!cap3.accepts(cap1), 'Different op should not accept in reverse');
 
-  const general = CapUrn.fromString(testUrn('op=generate'));
+  const general = CapUrn.fromString(testUrn('generate'));
   assert(general.accepts(cap1), 'General request should accept more specific instance');
   assert(!cap1.accepts(general), 'Specific pattern should reject general instance');
 
@@ -407,11 +425,11 @@ function test024_compatibility() {
 // TEST025: Test find_best_match returns most specific matching cap
 function test025_bestMatch() {
   const caps = [
-    CapUrn.fromString('cap:in=*;out=*;op=*'),
-    CapUrn.fromString(testUrn('op=generate')),
+    CapUrn.fromString('cap:in=*;out=*;op'),
+    CapUrn.fromString(testUrn('generate')),
     CapUrn.fromString(testUrn('generate;ext=pdf'))
   ];
-  const request = CapUrn.fromString(testUrn('op=generate'));
+  const request = CapUrn.fromString(testUrn('generate'));
   const best = CapMatcher.findBestMatch(caps, request);
   assert(best !== null, 'Should find a best match');
   assertEqual(best.getTag('ext'), 'pdf', 'Best match should be the most specific (ext=pdf)');
@@ -419,20 +437,20 @@ function test025_bestMatch() {
 
 // TEST026: Test merge combines tags from both caps, subset keeps only specified tags
 function test026_mergeAndSubset() {
-  const cap1 = CapUrn.fromString(testUrn('op=generate'));
+  const cap1 = CapUrn.fromString(testUrn('generate'));
   const cap2 = CapUrn.fromString('cap:in="media:textable";ext=pdf;format=binary;out="media:"');
 
   // Merge (other takes precedence)
   const merged = cap1.merge(cap2);
   assertEqual(merged.getInSpec(), 'media:textable', 'Merge should take inSpec from other');
   assertEqual(merged.getOutSpec(), 'media:', 'Merge should take outSpec from other');
-  assertEqual(merged.getTag('op'), 'generate', 'Merge should keep original tags');
+  assert(merged.hasMarkerTag('generate'), 'Merge should keep original tags');
   assertEqual(merged.getTag('ext'), 'pdf', 'Merge should add other tags');
 
   // Subset (always preserves in/out)
   const sub = merged.subset(['ext']);
   assertEqual(sub.getTag('ext'), 'pdf', 'Subset should keep ext');
-  assertEqual(sub.getTag('op'), undefined, 'Subset should drop op');
+  assert(!sub.hasMarkerTag('generate'), 'Subset should drop the generate marker');
   assertEqual(sub.getInSpec(), 'media:textable', 'Subset should preserve inSpec');
 }
 
@@ -580,7 +598,7 @@ function test040_matchingSemanticsExactMatch() {
 
 // TEST041: Matching semantics - cap missing tag matches (implicit wildcard)
 function test041_matchingSemanticsCapMissingTag() {
-  const cap = CapUrn.fromString(testUrn('op=generate'));
+  const cap = CapUrn.fromString(testUrn('generate'));
   const request = CapUrn.fromString(testUrn('generate;ext=pdf'));
   assert(cap.accepts(request), 'General pattern with only op should accept specific instance');
   assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
@@ -639,7 +657,7 @@ function test048_matchingSemanticsWildcardDirection() {
 
 // TEST049: Non-overlapping tags — neither direction accepts
 function test049_matchingSemanticsCrossDimension() {
-  const cap = CapUrn.fromString(testUrn('op=generate'));
+  const cap = CapUrn.fromString(testUrn('generate'));
   const request = CapUrn.fromString(testUrn('ext=pdf'));
   assert(!cap.accepts(request), 'Pattern requiring op should reject instance missing op');
   assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
@@ -706,7 +724,10 @@ function test890_directionSemanticMatching() {
     'Generic output cap must NOT satisfy specific output request');
 }
 
-// TEST891: Semantic direction specificity - more media URN tags = higher specificity
+// TEST891: Semantic direction specificity — more constraints in
+// either axis means a higher score under the truth-table-driven sum.
+// media: (top, no tags) scores 0; each marker tag scores 2; each
+// exact tag scores 3.
 function test891_directionSemanticSpecificity() {
   const genericCap = CapUrn.fromString(
     'cap:in="media:";generate-thumbnail;out="media:image;png;thumbnail"'
@@ -715,8 +736,20 @@ function test891_directionSemanticSpecificity() {
     'cap:in="media:pdf";generate-thumbnail;out="media:image;png;thumbnail"'
   );
 
-  assertEqual(genericCap.specificity(), 4, 'media:(0) + image;png;thumbnail(3) + op(1) = 4');
-  assertEqual(specificCap.specificity(), 5, 'pdf(1) + image;png;thumbnail(3) + op(1) = 5');
+  // generic:
+  //   out=media:image;png;thumbnail -> 2+2+2 = 6
+  //   in=media:                     -> 0
+  //   y: generate-thumbnail marker  -> 2
+  //   spec_C = 10000*6 + 100*0 + 2 = 60002
+  assertEqual(genericCap.specificity(), 10000*6 + 100*0 + 2,
+    'out=image;png;thumbnail(6) + in=media:(0) + generate-thumbnail marker(2) = 60002');
+  // specific:
+  //   out=media:image;png;thumbnail -> 6
+  //   in=media:pdf                  -> 2
+  //   y: generate-thumbnail marker  -> 2
+  //   spec_C = 10000*6 + 100*2 + 2 = 60202
+  assertEqual(specificCap.specificity(), 10000*6 + 100*2 + 2,
+    'out=image;png;thumbnail(6) + in=pdf(2) + generate-thumbnail marker(2) = 60202');
   assert(specificCap.specificity() > genericCap.specificity(), 'pdf should be more specific');
 
   // CapMatcher should prefer more specific
@@ -1367,7 +1400,7 @@ function test306_availabilityAndPathOutputDistinct() {
 // TEST307: Test model_availability_urn builds valid cap URN with correct op and media specs
 function test307_modelAvailabilityUrn() {
   const urn = modelAvailabilityUrn();
-  assert(urn.hasTag('op', 'model-availability'), 'Must have op=model-availability');
+  assert(urn.hasMarkerTag('model-availability'), 'Must have model-availability marker');
   const inSpec = TaggedUrn.fromString(urn.getInSpec());
   const expectedIn = TaggedUrn.fromString(MEDIA_MODEL_SPEC);
   assert(inSpec.conformsTo(expectedIn), 'input must conform to MEDIA_MODEL_SPEC');
@@ -1379,7 +1412,7 @@ function test307_modelAvailabilityUrn() {
 // TEST308: Test model_path_urn builds valid cap URN with correct op and media specs
 function test308_modelPathUrn() {
   const urn = modelPathUrn();
-  assert(urn.hasTag('op', 'model-path'), 'Must have op=model-path');
+  assert(urn.hasMarkerTag('model-path'), 'Must have model-path marker');
   const inSpec = TaggedUrn.fromString(urn.getInSpec());
   const expectedIn = TaggedUrn.fromString(MEDIA_MODEL_SPEC);
   assert(inSpec.conformsTo(expectedIn), 'input must conform to MEDIA_MODEL_SPEC');
@@ -1398,7 +1431,7 @@ function test309_modelAvailabilityAndPathAreDistinct() {
 // TEST310: llm_generate_text_urn() produces a valid cap URN with textable in/out specs
 function test310_llmGenerateTextUrn() {
   const urn = llmGenerateTextUrn();
-  assert(urn.hasTag('op', 'generate_text'), 'Must have op=generate_text');
+  assert(urn.hasMarkerTag('generate_text'), 'Must have generate_text marker');
   assert(urn.getTag('llm') !== undefined, 'Must have llm tag');
   assert(urn.getTag('ml-model') !== undefined, 'Must have ml-model tag');
   assert(TaggedUrn.fromString(urn.getInSpec()).conformsTo(TaggedUrn.fromString(MEDIA_STRING)),
@@ -1508,7 +1541,7 @@ function testJS_capWithMediaSpecs() {
 }
 
 function testJS_capJSONSerialization() {
-  const urn = CapUrn.fromString(testUrn('op=test'));
+  const urn = CapUrn.fromString(testUrn('test'));
   const cap = new Cap(urn, 'Test Cap', 'test_command');
   cap.mediaSpecs = [
     { urn: 'media:custom', media_type: 'text/plain', title: 'Custom' }
@@ -1535,7 +1568,7 @@ function testJS_capJSONSerialization() {
 // JSON.stringify on this side and the Rust serializer on the other side
 // surface as failures here.
 function testJS_capDocumentationRoundTrip() {
-  const urn = CapUrn.fromString(testUrn('op=documented'));
+  const urn = CapUrn.fromString(testUrn('documented'));
   const cap = new Cap(urn, 'Documented Cap', 'documented');
   const body = '# Documented Cap\r\n\nDoes the thing.\n\n```bash\necho "hi"\n```\n\nSee also: \u2605\n';
   cap.setDocumentation(body);
@@ -1557,7 +1590,7 @@ function testJS_capDocumentationRoundTrip() {
 // `documentation: null` would break the symmetric round-trip with Rust
 // (which has no null sentinel) and pollute generated JSON.
 function testJS_capDocumentationOmittedWhenNull() {
-  const urn = CapUrn.fromString(testUrn('op=undocumented'));
+  const urn = CapUrn.fromString(testUrn('undocumented'));
   const cap = new Cap(urn, 'Undocumented Cap', 'undocumented');
   assertEqual(cap.getDocumentation(), null, 'Default documentation must be null');
 
@@ -2341,7 +2374,7 @@ function test1303_withoutTag() {
   const cap = CapUrn.fromString('cap:in="media:void";test;ext=pdf;out="media:void"');
   const removed = cap.withoutTag('ext');
   assertEqual(removed.getTag('ext'), undefined, 'withoutTag should remove ext');
-  assertEqual(removed.getTag('op'), 'test', 'withoutTag should preserve op');
+  assert(removed.hasMarkerTag('test'), 'withoutTag should preserve op');
 
   // Case-insensitive removal
   const removed2 = cap.withoutTag('EXT');
@@ -2365,7 +2398,7 @@ function test1304_withInOutSpec() {
   const changedIn = cap.withInSpec('media:');
   assertEqual(changedIn.getInSpec(), 'media:', 'withInSpec should change inSpec');
   assertEqual(changedIn.getOutSpec(), 'media:void', 'withInSpec should preserve outSpec');
-  assertEqual(changedIn.getTag('op'), 'test', 'withInSpec should preserve tags');
+  assert(changedIn.hasMarkerTag('test'), 'withInSpec should preserve tags');
 
   const changedOut = cap.withOutSpec('media:string');
   assertEqual(changedOut.getInSpec(), 'media:void', 'withOutSpec should preserve inSpec');
@@ -2392,7 +2425,7 @@ function test1305_findAllMatches() {
   const request = CapUrn.fromString('cap:in="media:void";test;out="media:void"');
   const matches = CapMatcher.findAllMatches(caps, request);
 
-  // Should find 2 matches (op=test and test;ext=pdf), not op=different
+  // Should find 2 matches (test and test;ext=pdf), not different
   assertEqual(matches.length, 2, 'Should find 2 matches');
   // Sorted by specificity descending: ext=pdf first (more specific)
   assert(matches[0].specificity() >= matches[1].specificity(), 'First match should be more specific');
@@ -2411,10 +2444,10 @@ function test1306_areCompatible() {
     CapUrn.fromString('cap:in="media:void";different;out="media:void"'),
   ];
 
-  // caps1 (op=test) accepts caps2 (test;ext=pdf) -> compatible
+  // caps1 (test) accepts caps2 (test;ext=pdf) -> compatible
   assert(CapMatcher.areCompatible(caps1, caps2), 'caps1 and caps2 should be compatible');
 
-  // caps1 (op=test) vs caps3 (op=different) -> not compatible
+  // caps1 (test) vs caps3 (different) -> not compatible
   assert(!CapMatcher.areCompatible(caps1, caps3), 'caps1 and caps3 should not be compatible');
 
   // Empty sets are not compatible
@@ -2577,7 +2610,7 @@ function test649_specificityScoring() {
   assert(specific.specificity() > 0, 'Specific cap should have non-zero specificity');
 }
 
-// TEST650: N/A for JS (JS requires in/out, cap:in;out;op=test would fail parsing)
+// TEST650: N/A for JS (JS requires in/out, cap:in=media:;out=media:;test would fail parsing)
 
 // TEST651: All identity forms produce the same CapUrn
 function test651_identityFormsEquivalent() {
@@ -2615,7 +2648,7 @@ function test653_identityRoutingIsolation() {
   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');
-  assertEqual(best.getTag('op'), 'test', 'CapMatcher should prefer specific cap over identity');
+  assert(best.hasMarkerTag('test'), 'CapMatcher should prefer specific cap over identity');
 }
 
 // ============================================================================
@@ -4622,7 +4655,7 @@ function testRenderer_buildRunGraphData_usesCapUrnIsEquivalentForFailedCap() {
         saved_paths: [],
         total_bytes: 0,
         duration_ms: 0,
-        failed_cap: 'cap:in="media:b";out="media:c";op=y',  // different tag order
+        failed_cap: 'cap:in=media:b;out=media:c;y',  // different tag order
         error: 'fail',
       },
     ],
@@ -5258,6 +5291,354 @@ function testRenderer_validateResolvedMachinePayload_rejectsMissingFields() {
   }
 }
 
+// ============================================================================
+// CapKind classifier tests (test1800–test1805)
+//
+// Mirrored across every language port (Rust, Go, Python, Swift/ObjC,
+// JS) under the SAME numbers. Any divergence is a wire-level
+// inconsistency — the kind taxonomy is part of the protocol's public
+// 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.
+function test1800_kindIdentityOnlyForBareCap() {
+  const identity = CapUrn.fromString('cap:');
+  assertEqual(identity.kind(), CapKind.IDENTITY, 'cap: should be Identity');
+
+  for (const spelling of [
+    'cap:in=media:;out=media:',
+    'cap:in=*;out=*',
+    'cap:in=media:',
+    'cap:out=media:',
+  ]) {
+    const cap = CapUrn.fromString(spelling);
+    assertEqual(cap.kind(), CapKind.IDENTITY,
+      `${spelling} should classify as Identity (canonical form is cap:)`);
+  }
+
+  const withOp = CapUrn.fromString('cap:passthrough');
+  assertEqual(withOp.kind(), CapKind.TRANSFORM,
+    'cap:passthrough specifies the operation axis — not Identity');
+}
+
+// TEST1801: Source classifier — in=media:void, out non-void.
+function test1801_kindSourceWhenInputIsVoid() {
+  const warm = CapUrn.fromString('cap:in=media:void;out="media:model-artifact";warm');
+  assertEqual(warm.kind(), CapKind.SOURCE, 'warm cap is a Source');
+
+  const gen = CapUrn.fromString('cap:in=media:void;out=media:textable');
+  assertEqual(gen.kind(), CapKind.SOURCE, 'in=void with concrete out is a Source');
+}
+
+// TEST1802: Sink classifier — out=media:void, in non-void.
+function test1802_kindSinkWhenOutputIsVoid() {
+  const discard = CapUrn.fromString('cap:discard;in=media:;out=media:void');
+  assertEqual(discard.kind(), CapKind.SINK, 'discard cap is a Sink');
+
+  const log = CapUrn.fromString('cap:in="media:json;textable";log;out=media:void');
+  assertEqual(log.kind(), CapKind.SINK, 'log cap is a Sink');
+}
+
+// TEST1803: Effect classifier — both sides void. Reads as `() → ()`.
+function test1803_kindEffectWhenBothSidesVoid() {
+  const ping = CapUrn.fromString('cap:in=media:void;out=media:void;ping');
+  assertEqual(ping.kind(), CapKind.EFFECT, 'ping is an Effect');
+
+  const bare = CapUrn.fromString('cap:in=media:void;out=media:void');
+  assertEqual(bare.kind(), CapKind.EFFECT,
+    'in=void;out=void with empty y is still an Effect');
+}
+
+// TEST1804: Transform classifier — at least one side non-void, and
+// the cap is not the bare identity.
+function test1804_kindTransformForNormalDataProcessors() {
+  const extract = CapUrn.fromString('cap:extract;in=media:pdf;out="media:record;textable"');
+  assertEqual(extract.kind(), CapKind.TRANSFORM, 'extract is a Transform');
+
+  const labeled = CapUrn.fromString('cap:passthrough;in=media:;out=media:');
+  assertEqual(labeled.kind(), CapKind.TRANSFORM,
+    'fully generic in/out with a tag is a Transform, not Identity');
+}
+
+// TEST1810: media:void is atomic — refinements are parse errors.
+//
+// Mirrored across every language port (Rust, Go, Python, Swift/ObjC,
+// JS) under the SAME number. Any divergence is a wire-level
+// inconsistency — the unit type's atomicity is part of the protocol's
+// deepest layer, not a per-port detail.
+function test1810_mediaVoidIsAtomic() {
+  // Bare void: must parse successfully.
+  const bare = MediaUrn.fromString('media:void');
+  assert(bare.isVoid(), 'bare media:void must parse — it is the unit type');
+
+  const badInputs = [
+    'media:void;text',
+    'media:void;pdf',
+    'media:void;audio',
+    'media:void;reason=warmup',
+    'media:void;heartbeat',
+    'media:void;manual',
+    // Order must not matter — the parser canonicalizes tags.
+    'media:warmup;void',
+    'media:reason=foo;void',
+  ];
+
+  for (const input of badInputs) {
+    let threw = false;
+    let code = null;
+    try {
+      MediaUrn.fromString(input);
+    } catch (e) {
+      threw = true;
+      code = e.code;
+    }
+    assert(threw, `${input}: expected parse error, but parsed successfully`);
+    assertEqual(code, MediaUrnErrorCodes.VOID_NOT_ATOMIC,
+      `${input}: expected VOID_NOT_ATOMIC error code`);
+  }
+}
+
+// TEST1805: Kind is invariant under canonicalization. The same
+// morphism written in many surface forms must classify the same way
+// once parsed.
+function test1805_kindInvariantUnderCanonicalSpellings() {
+  const cases = [
+    { a: 'cap:', b: 'cap:in=media:;out=media:', expected: CapKind.IDENTITY },
+    {
+      a: 'cap:extract;in=media:pdf;out=media:textable',
+      b: 'cap:extract;in="media:pdf";out="media:textable"',
+      expected: CapKind.TRANSFORM,
+    },
+    {
+      a: 'cap:in=media:void;out=media:textable;warm',
+      b: 'cap:warm;out=media:textable;in=media:void',
+      expected: CapKind.SOURCE,
+    },
+  ];
+
+  for (const { a, b, expected } of cases) {
+    const kindA = CapUrn.fromString(a).kind();
+    const kindB = CapUrn.fromString(b).kind();
+    assertEqual(kindA, expected, `${a} should classify as ${expected}`);
+    assertEqual(kindB, expected, `${b} should classify as ${expected}`);
+    assertEqual(kindA, kindB,
+      `${a} and ${b} parse to the same cap and must classify identically`);
+  }
+}
+
+// ============================================================================
+// Truth-table specificity tests (test1820–test1824)
+//
+// Mirrored across every language port (Rust, Go, Python, Swift/ObjC,
+// JS) under the SAME numbers. Specificity must be the truth-table
+// sum across all three axes using the six-form ladder:
+//
+//   ?x or missing     -> 0   (no constraint)
+//   x?=v              -> 1   (absent OR not v)
+//   x (=x=*) marker   -> 2   (must-have-any)
+//   x!=v              -> 3   (present and not v)
+//   x=v exact         -> 4   (must-have-this-value)
+//   !x                -> 5   (must-not-have)
+// ============================================================================
+
+// 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 withQ = CapUrn.fromString('cap:?target');
+  assertEqual(withQ.specificity(), 0,
+    '?x must score 0 (explicit no-constraint, same as missing)');
+}
+
+// TEST1821: A `!`-valued cap-tag scores 5 (top of negative chain).
+function test1821_specificityMustNotHaveIsFive() {
+  const cap = CapUrn.fromString('cap:!constrained');
+  assertEqual(cap.specificity(), 5,
+    '!constrained (must-not-have) must score 5');
+}
+
+// TEST1822: A `*`-valued cap-tag (including bare markers) scores 2.
+function test1822_specificityMustHaveAnyIsTwo() {
+  const bareMarker = CapUrn.fromString('cap:extract');
+  assertEqual(bareMarker.specificity(), 2,
+    'bare `extract` parses as extract=* (must-have-any) and scores 2');
+
+  const explicitStar = CapUrn.fromString('cap:extract=*');
+  assertEqual(explicitStar.specificity(), 2,
+    'explicit key=* must score 2 (same as bare marker)');
+
+  assertEqual(bareMarker.specificity(), explicitStar.specificity(),
+    'bare marker and explicit key=* are the same form and must score identically');
+}
+
+// TEST1823: An exact-valued cap-tag scores 4.
+function test1823_specificityExactValueIsFour() {
+  const cap = CapUrn.fromString('cap:target=metadata');
+  assertEqual(cap.specificity(), 4,
+    'target=metadata (exact value) must score 4');
+}
+
+// TEST1824: All six forms compose additively on a single cap.
+// y combining 0+1+2+3+4+5 must sum to 15.
+function test1824_specificityCombinedYAxis() {
+  const cap = CapUrn.fromString('cap:!constrained;?target;extract;stage!=alpha;target2=metadata;ver?=draft');
+  assertEqual(cap.specificity(), 15,
+    'y combining all six forms (0+1+2+3+4+5) must sum to 15');
+}
+
+// ============================================================================
+// Six-form canonicalization tests (test1830–test1835).
+// ============================================================================
+
+// TEST1830: ?x ≡ x? ≡ x=? all canonicalize to ?x.
+function test1830_canonicalizeNoConstraint() {
+  const canonical = 'cap:?x';
+  for (const input of ['cap:?x', 'cap:x?', 'cap:x=?']) {
+    const cap = CapUrn.fromString(input);
+    assertEqual(cap.toString(), canonical,
+      `input ${input} must canonicalize to ${canonical}`);
+  }
+}
+
+// TEST1831: ?x=v and x?=v both canonicalize to x?=v. The third
+// hypothetical form `x=?v` is NOT recognized as a qualifier — a
+// value starting with `?` is just an exact value beginning with
+// a `?` character.
+function test1831_canonicalizeAbsentOrNotValue() {
+  const canonical = 'cap:x?=foo';
+  for (const input of ['cap:?x=foo', 'cap:x?=foo']) {
+    const cap = CapUrn.fromString(input);
+    assertEqual(cap.toString(), canonical,
+      `input ${input} must canonicalize to ${canonical}`);
+  }
+
+  // `x=?foo` is a plain exact tag whose value is the string `?foo`
+  // — NOT a canonicalization alias.
+  const exact = CapUrn.fromString('cap:x=?foo');
+  assertEqual(exact.toString(), 'cap:x=?foo');
+  assertEqual(exact.getTag('x'), '?foo');
+}
+
+// TEST1832: x ≡ x=* both canonicalize to bare x.
+function test1832_canonicalizeMustHaveAny() {
+  const canonical = 'cap:x';
+  for (const input of ['cap:x', 'cap:x=*']) {
+    const cap = CapUrn.fromString(input);
+    assertEqual(cap.toString(), canonical,
+      `input ${input} must canonicalize to ${canonical}`);
+  }
+}
+
+// TEST1833: !x=v and x!=v both canonicalize to x!=v. The third
+// hypothetical form `x=!v` is NOT recognized as a qualifier — a
+// value starting with `!` is just an exact value beginning with
+// a `!` character.
+function test1833_canonicalizePresentNotValue() {
+  const canonical = 'cap:x!=foo';
+  for (const input of ['cap:!x=foo', 'cap:x!=foo']) {
+    const cap = CapUrn.fromString(input);
+    assertEqual(cap.toString(), canonical,
+      `input ${input} must canonicalize to ${canonical}`);
+  }
+
+  // `x=!foo` is a plain exact tag whose value is the string `!foo`
+  // — NOT a canonicalization alias.
+  const exact = CapUrn.fromString('cap:x=!foo');
+  assertEqual(exact.toString(), 'cap:x=!foo');
+  assertEqual(exact.getTag('x'), '!foo');
+}
+
+// TEST1834: x=v stays as x=v.
+function test1834_canonicalizeExactValue() {
+  const cap = CapUrn.fromString('cap:x=foo');
+  assertEqual(cap.toString(), 'cap:x=foo');
+}
+
+// TEST1835: !x ≡ x! ≡ x=! all canonicalize to !x.
+function test1835_canonicalizeMustNotHave() {
+  const canonical = 'cap:!x';
+  for (const input of ['cap:!x', 'cap:x!', 'cap:x=!']) {
+    const cap = CapUrn.fromString(input);
+    assertEqual(cap.toString(), canonical,
+      `input ${input} must canonicalize to ${canonical}`);
+  }
+}
+
+// TEST1842: Full 6×6 truth table.
+function test1842_truthTableFullCrossProduct() {
+  const forms = ['', '?x', 'x?=v', 'x', 'x!=v', 'x=v', '!x'];
+  // miss   ?x    x?=v   x      x!=v   x=v    !x
+  const expected = [
+    [true,  true, true,  false, false, false, true ], // missing
+    [true,  true, true,  true,  true,  true,  true ], // ?x
+    [true,  true, true,  false, false, false, true ], // x?=v
+    [true,  true, true,  true,  true,  true,  false], // x
+    [true,  true, true,  true,  true,  false, false], // x!=v
+    [true,  true, false, true,  false, true,  false], // x=v
+    [true,  true, true,  false, false, false, true ], // !x
+  ];
+  for (let i = 0; i < forms.length; i++) {
+    for (let j = 0; j < forms.length; j++) {
+      const instForm = forms[i];
+      const pattForm = forms[j];
+      const instStr = instForm === '' ? 'cap:' : 'cap:' + instForm;
+      const pattStr = pattForm === '' ? 'cap:' : 'cap:' + pattForm;
+      const inst = CapUrn.fromString(instStr);
+      const patt = CapUrn.fromString(pattStr);
+      const actual = patt.accepts(inst);
+      assertEqual(actual, expected[i][j],
+        `cell (inst=${instForm}, patt=${pattForm}) expected ${expected[i][j]} got ${actual}`);
+    }
+  }
+}
+
+// TEST1843: Invalid qualifier combinations must be rejected.
+function test1843_rejectInvalidCombinations() {
+  const invalid = [
+    'cap:?x?=v', 'cap:!x!=v', 'cap:?!x', 'cap:!?x',
+    'cap:?x=*', 'cap:!x=*',
+    'cap:?x=?', 'cap:?x=!', 'cap:!x=?', 'cap:!x=!',
+    'cap:?', 'cap:!',
+  ];
+  for (const input of invalid) {
+    let threw = false;
+    try { CapUrn.fromString(input); } catch (_e) { threw = true; }
+    assert(threw, `input ${input} must be rejected`);
+  }
+}
+
+// TEST1844: out-axis difference dominates combined in+y differences.
+function test1844_axisWeightingOutDominates() {
+  const bigOut = CapUrn.fromString('cap:in=media:;out="media:record;textable"');
+  const bigInAndY = CapUrn.fromString(
+    'cap:in=media:pdf;out=media:record;!constrained;?target;extract;stage!=alpha;target2=metadata;ver?=draft'
+  );
+  assert(bigOut.specificity() > bigInAndY.specificity(),
+    'out-axis difference must dominate combined in+y differences');
+}
+
+// TEST1845: With equal out, in-axis dominates over y-axis.
+function test1845_axisWeightingInDominatesY() {
+  const bigIn = CapUrn.fromString('cap:in=media:pdf;out=media:record');
+  const bigY = CapUrn.fromString(
+    'cap:in=media:;out=media:record;!constrained;?target;extract;stage!=alpha;target2=metadata;ver?=draft'
+  );
+  assert(bigIn.specificity() > bigY.specificity(),
+    'in-axis difference must dominate y-axis');
+}
+
+// TEST1846: Decoded layout — 10000*out + 100*in + y.
+function test1846_axisWeightingDecodedLayout() {
+  const cap = CapUrn.fromString('cap:in="media:a;b";out="media:a;b;c;d";extract');
+  // out=4 markers (8), in=2 markers (4), y=1 marker (2)
+  // 10000*8 + 100*4 + 2 = 80402
+  assertEqual(cap.specificity(), 10000*8 + 100*4 + 2);
+}
+
 // ============================================================================
 // Test runner
 // ============================================================================
@@ -5651,6 +6032,39 @@ async function runTests() {
   runTest('RENDERER: buildResolvedMachine_dupNodeIdFails',         testRenderer_buildResolvedMachineGraphData_duplicateNodeIdAcrossStrandsFailsHard);
   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('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);
+  runTest('TEST1804: kind_transform_for_normal_processors', test1804_kindTransformForNormalDataProcessors);
+  runTest('TEST1805: kind_invariant_under_canonical',       test1805_kindInvariantUnderCanonicalSpellings);
+
+  console.log('\n--- media:void atomicity (test1810) ---');
+  runTest('TEST1810: media_void_is_atomic',                 test1810_mediaVoidIsAtomic);
+
+  console.log('\n--- Truth-table specificity (test1820–test1824) ---');
+  runTest('TEST1820: specificity_question_is_zero',         test1820_specificityQuestionIsZero);
+  runTest('TEST1821: specificity_must_not_have_is_five',    test1821_specificityMustNotHaveIsFive);
+  runTest('TEST1822: specificity_must_have_any_is_two',     test1822_specificityMustHaveAnyIsTwo);
+  runTest('TEST1823: specificity_exact_value_is_four',      test1823_specificityExactValueIsFour);
+  runTest('TEST1824: specificity_combined_y_axis',          test1824_specificityCombinedYAxis);
+
+  console.log('\n--- Six-form canonicalization (test1830–test1835) ---');
+  runTest('TEST1830: canonicalize_no_constraint',           test1830_canonicalizeNoConstraint);
+  runTest('TEST1831: canonicalize_absent_or_not_value',     test1831_canonicalizeAbsentOrNotValue);
+  runTest('TEST1832: canonicalize_must_have_any',           test1832_canonicalizeMustHaveAny);
+  runTest('TEST1833: canonicalize_present_not_value',       test1833_canonicalizePresentNotValue);
+  runTest('TEST1834: canonicalize_exact_value',             test1834_canonicalizeExactValue);
+  runTest('TEST1835: canonicalize_must_not_have',           test1835_canonicalizeMustNotHave);
+
+  console.log('\n--- Truth-table cross-product + axis weighting (test1842–test1846) ---');
+  runTest('TEST1842: truth_table_full_cross_product',       test1842_truthTableFullCrossProduct);
+  runTest('TEST1843: reject_invalid_combinations',          test1843_rejectInvalidCombinations);
+  runTest('TEST1844: axis_weighting_out_dominates',         test1844_axisWeightingOutDominates);
+  runTest('TEST1845: axis_weighting_in_dominates_y',        test1845_axisWeightingInDominatesY);
+  runTest('TEST1846: axis_weighting_decoded_layout',        test1846_axisWeightingDecodedLayout);
+
   // Summary
   console.log(`\n${passCount + failCount} tests: ${passCount} passed, ${failCount} failed`);
   if (failCount > 0) {

package/package.json

@@ -2,7 +2,7 @@
   "author": "Bahram Joharshamshiri",
   "dependencies": {
     "peggy": "^5.1.0",
-    "tagged-urn": "^0.35.86"
+    "tagged-urn": "^0.39.0"
   },
   "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.161.384"
+  "version": "0.165.398"
 }