capdag 0.127.280 → 0.138.305

package/capdag.test.js

@@ -12,7 +12,7 @@ const {
   CapGraphEdge, CapGraphStats, CapGraph,
   StdinSource, StdinSourceKind,
   validateNoMediaSpecRedefinitionSync,
-  CapArgumentValue,
+  CapArgumentValue, CapArg, ArgSource, validateCapArgs, ValidationError,
   llmGenerateTextUrn, modelAvailabilityUrn, modelPathUrn,
   MachineSyntaxError, MachineSyntaxErrorCodes, MachineEdge, Machine, MachineBuilder, parseMachine, parseMachineWithAST,
   CapRegistryEntry, MediaRegistryEntry, CapRegistryClient,
@@ -151,7 +151,7 @@ function matrixTestUrn(tags) {
 // cap_urn.rs: TEST001-TEST050, TEST890-TEST891
 // ============================================================================
 
-// TEST001: Cap URN created with tags, direction specs accessible
+// TEST001: Test that cap URN is created with tags parsed correctly and direction specs accessible
 function test001_capUrnCreation() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf;target=thumbnail'));
   assertEqual(cap.getTag('op'), 'generate', 'Should get op tag');
@@ -161,21 +161,18 @@ function test001_capUrnCreation() {
   assertEqual(cap.getOutSpec(), MEDIA_OBJECT, 'Should get outSpec');
 }
 
-// TEST002: Missing in -> MissingInSpec, missing out -> MissingOutSpec
+// TEST002: Test that missing 'in' or 'out' defaults to media: wildcard
 function test002_directionSpecsRequired() {
-  assertThrows(
-    () => CapUrn.fromString('cap:out="media:void";op=test'),
-    ErrorCodes.MISSING_IN_SPEC,
-    'Missing in should fail with MISSING_IN_SPEC'
-  );
-  assertThrows(
-    () => CapUrn.fromString('cap:in="media:void";op=test'),
-    ErrorCodes.MISSING_OUT_SPEC,
-    'Missing out should fail with MISSING_OUT_SPEC'
-  );
+  const missingIn = CapUrn.fromString('cap:out="media:void";op=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');
+  assertEqual(missingOut.getInSpec(), MEDIA_VOID, 'Explicit in should be preserved');
+  assertEqual(missingOut.getOutSpec(), MEDIA_IDENTITY, 'Missing out should default to media:');
 }
 
-// TEST003: Direction specs must match exactly; wildcard matches any
+// 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'));
@@ -190,7 +187,7 @@ function test003_directionMatching() {
   assert(wildcardCap.accepts(request), 'Wildcard direction should match any');
 }
 
-// TEST004: Unquoted keys/values normalized to lowercase
+// 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');
@@ -199,33 +196,33 @@ function test004_unquotedValuesLowercased() {
   assertEqual(cap.getTag('OP'), 'generate', 'Key lookup should be case-insensitive');
 }
 
-// TEST005: Quoted values preserve case
+// TEST005: Test that quoted values preserve case while unquoted are lowercased
 function test005_quotedValuesPreserveCase() {
   const cap = CapUrn.fromString('cap:in="media:void";key="HelloWorld";out="media:void"');
   assertEqual(cap.getTag('key'), 'HelloWorld', 'Quoted value should preserve case');
 }
 
-// TEST006: Semicolons, equals, spaces in quoted values
+// TEST006: Test that quoted values can contain special characters (semicolons, equals, spaces)
 function test006_quotedValueSpecialChars() {
   const cap = CapUrn.fromString('cap:in="media:void";key="val;ue=with spaces";out="media:void"');
   assertEqual(cap.getTag('key'), 'val;ue=with spaces', 'Quoted value should preserve special chars');
 }
 
-// TEST007: Escaped quotes and backslashes in quoted values
+// TEST007: Test that escape sequences in quoted values (\" and \\) are parsed correctly
 function test007_quotedValueEscapeSequences() {
   const s = String.raw`cap:in="media:void";key="val\"ue\\test";out="media:void"`;
   const cap = CapUrn.fromString(s);
   assertEqual(cap.getTag('key'), 'val"ue\\test', 'Escaped quote and backslash should be unescaped');
 }
 
-// TEST008: Mix of quoted and unquoted values
+// TEST008: Test that mixed quoted and unquoted values in same URN parse correctly
 function test008_mixedQuotedUnquoted() {
   const cap = CapUrn.fromString('cap:a=simple;b="Quoted";in="media:void";out="media:void"');
   assertEqual(cap.getTag('a'), 'simple', 'Unquoted value should be lowercase');
   assertEqual(cap.getTag('b'), 'Quoted', 'Quoted value should preserve case');
 }
 
-// TEST009: Unterminated quote produces error
+// TEST009: Test that unterminated quote produces UnterminatedQuote error
 function test009_unterminatedQuoteError() {
   let threw = false;
   try {
@@ -238,7 +235,7 @@ function test009_unterminatedQuoteError() {
   assert(threw, 'Unterminated quote should produce CapUrnError');
 }
 
-// TEST010: Invalid escape sequences produce error
+// TEST010: Test that invalid escape sequences (like \n, \x) produce InvalidEscapeSequence error
 function test010_invalidEscapeSequenceError() {
   let threw = false;
   try {
@@ -252,7 +249,7 @@ function test010_invalidEscapeSequenceError() {
   assert(threw, 'Invalid escape sequence should produce CapUrnError');
 }
 
-// TEST011: Smart quoting: no quotes for simple lowercase, quotes for special
+// TEST011: Test that serialization uses smart quoting (no quotes for simple lowercase, quotes for special chars/uppercase)
 function test011_serializationSmartQuoting() {
   const cap = CapUrn.fromString('cap:a=simple;b="Has Space";in="media:void";out="media:void"');
   const s = cap.toString();
@@ -261,7 +258,7 @@ function test011_serializationSmartQuoting() {
   assert(s.includes('b="Has Space"'), 'Value with space should be quoted');
 }
 
-// TEST012: Simple cap URN parse -> serialize -> parse equals original
+// TEST012: Test that simple cap URN round-trips (parse -> serialize -> parse equals original)
 function test012_roundTripSimple() {
   const original = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const serialized = original.toString();
@@ -269,7 +266,7 @@ function test012_roundTripSimple() {
   assert(original.equals(reparsed), 'Simple round-trip should produce equal URN');
 }
 
-// TEST013: Quoted values round-trip preserving case
+// TEST013: Test that quoted values round-trip preserving case and spaces
 function test013_roundTripQuoted() {
   const original = CapUrn.fromString('cap:in="media:void";key="HelloWorld";out="media:void"');
   const serialized = original.toString();
@@ -278,7 +275,7 @@ function test013_roundTripQuoted() {
   assertEqual(reparsed.getTag('key'), 'HelloWorld', 'Quoted value should survive round-trip');
 }
 
-// TEST014: Escape sequences round-trip correctly
+// TEST014: Test that escape sequences round-trip correctly
 function test014_roundTripEscapes() {
   const s = String.raw`cap:in="media:void";key="val\"ue\\test";out="media:void"`;
   const original = CapUrn.fromString(s);
@@ -288,7 +285,7 @@ function test014_roundTripEscapes() {
   assertEqual(reparsed.getTag('key'), 'val"ue\\test', 'Escaped value should survive round-trip');
 }
 
-// TEST015: cap: prefix required, case-insensitive
+// TEST015: Test that cap: prefix is required and case-insensitive
 function test015_capPrefixRequired() {
   assertThrows(
     () => CapUrn.fromString('in="media:void";out="media:void";op=generate'),
@@ -300,7 +297,7 @@ function test015_capPrefixRequired() {
   assertEqual(cap.getTag('op'), 'generate', 'Should parse with valid cap: prefix');
 }
 
-// TEST016: With/without trailing semicolon are equivalent
+// TEST016: Test that trailing semicolon is equivalent (same hash, same string, matches)
 function test016_trailingSemicolonEquivalence() {
   const cap1 = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const cap2 = CapUrn.fromString(testUrn('op=generate;ext=pdf') + ';');
@@ -308,49 +305,51 @@ function test016_trailingSemicolonEquivalence() {
   assertEqual(cap1.toString(), cap2.toString(), 'Canonical forms should match');
 }
 
-// TEST017: Exact match, subset match, wildcard match, value mismatch
+// TEST017: Test tag matching: exact match, subset match, wildcard match, value mismatch
 function test017_tagMatching() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf;target=thumbnail'));
 
-  // Exact match
+  // Exact match — both directions accept
   const exact = CapUrn.fromString(testUrn('op=generate;ext=pdf;target=thumbnail'));
   assert(cap.accepts(exact), 'Should accept exact match');
+  assert(exact.accepts(cap), 'Exact match should accept in reverse too');
 
-  // Subset match
+  // Routing direction: request(op=generate) accepts cap(op,ext,target)
   const subset = CapUrn.fromString(testUrn('op=generate'));
-  assert(cap.accepts(subset), 'Should accept subset request');
+  assert(subset.accepts(cap), 'General request should accept more specific instance');
+  assert(!cap.accepts(subset), 'Specific pattern should reject subset instance');
 
-  // Wildcard match
+  // Routing direction: request(ext=*) accepts cap(ext=pdf)
   const wildcard = CapUrn.fromString(testUrn('ext=*'));
-  assert(cap.accepts(wildcard), 'Should accept wildcard request');
+  assert(wildcard.accepts(cap), 'Wildcard request should accept specific instance');
 
-  // Value mismatch
+  // Conflicting value — neither direction accepts
   const mismatch = CapUrn.fromString(testUrn('op=extract'));
   assert(!cap.accepts(mismatch), 'Should not accept value mismatch');
+  assert(!mismatch.accepts(cap), 'Reverse mismatch should also reject');
 }
 
-// TEST018: Quoted uppercase values don't match lowercase (case sensitive)
+// TEST018: Test that quoted values with different case do NOT match (case-sensitive)
 function test018_matchingCaseSensitiveValues() {
   const cap = CapUrn.fromString('cap:in="media:void";key="HelloWorld";out="media:void"');
   const request = CapUrn.fromString('cap:in="media:void";key=helloworld;out="media:void"');
   assert(!cap.accepts(request), 'Quoted HelloWorld should not match unquoted helloworld');
 }
 
-// TEST019: Missing tags treated as wildcards
+// TEST019: Missing tag in instance causes rejection — pattern's tags are constraints
 function test019_missingTagHandling() {
   const cap = CapUrn.fromString(testUrn('op=generate'));
-
-  // Request with tag cap doesn't have -> cap's missing tag is implicit wildcard
   const request = CapUrn.fromString(testUrn('ext=pdf'));
-  assert(cap.accepts(request), 'Missing tag in cap should be treated as wildcard');
+  assert(!cap.accepts(request), 'Pattern requiring op should reject instance missing op');
+  assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
 
-  // Cap with extra tags can accept subset requests
   const cap2 = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const request2 = CapUrn.fromString(testUrn('op=generate'));
-  assert(cap2.accepts(request2), 'Cap with extra tags should accept subset request');
+  assert(!cap2.accepts(request2), 'Specific pattern should reject instance missing ext');
+  assert(request2.accepts(cap2), 'General request should accept more specific instance');
 }
 
-// TEST020: Direction specs use MediaUrn tag count, other tags count non-wildcard
+// TEST020: Test specificity calculation (direction specs use MediaUrn tag count, wildcards don't count)
 function test020_specificity() {
   // Direction specs contribute their MediaUrn tag count:
   // MEDIA_VOID = "media:void" -> 1 tag (void)
@@ -369,7 +368,7 @@ function test020_specificity() {
   assertEqual(cap4.specificity(), 2, 'record(1) + op(1) (in wildcard doesn\'t count)');
 }
 
-// TEST021: CapUrnBuilder creates valid URN
+// TEST021: Test builder creates cap URN with correct tags and direction specs
 function test021_builder() {
   const cap = new CapUrnBuilder()
     .inSpec('media:void')
@@ -383,7 +382,7 @@ function test021_builder() {
   assertEqual(cap.getOutSpec(), 'media:object', 'Builder should set outSpec');
 }
 
-// TEST022: Builder requires both inSpec and outSpec
+// TEST022: Test builder requires both in_spec and out_spec
 function test022_builderRequiresDirection() {
   assertThrows(
     () => new CapUrnBuilder().tag('op', 'test').build(),
@@ -397,7 +396,7 @@ function test022_builderRequiresDirection() {
   );
 }
 
-// TEST023: Builder lowercases keys but preserves value case
+// TEST023: Test builder lowercases keys but preserves value case
 function test023_builderPreservesCase() {
   const cap = new CapUrnBuilder()
     .inSpec('media:void')
@@ -408,27 +407,27 @@ function test023_builderPreservesCase() {
   assertEqual(cap.getTag('MyKey'), 'MyValue', 'getTag should be case-insensitive for keys');
 }
 
-// TEST024: Directional accepts checks
+// TEST024: Directional accepts — pattern's tags are constraints, instance must satisfy
 function test024_compatibility() {
-  // General cap accepts specific request (missing tags = wildcards)
-  const general = CapUrn.fromString(testUrn('op=generate'));
-  const specific = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
-  assert(general.accepts(specific), 'General cap should accept specific request');
-  // Specific cap also accepts general request (cap has extra tag, not blocking)
-  assert(specific.accepts(general), 'Specific cap accepts general request (extra tags ok)');
-
-  // Different op values: neither accepts the other
   const cap1 = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
+  const cap2 = CapUrn.fromString(testUrn('op=generate;format=*'));
   const cap3 = CapUrn.fromString(testUrn('type=image;op=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 (reverse)');
+  assert(!cap3.accepts(cap1), 'Different op should not accept in reverse');
 
-  // Different in/out should not accept
-  const cap5 = CapUrn.fromString('cap:in="media:textable";out="media:object";op=generate');
-  assert(!cap1.accepts(cap5), 'Different inSpec should not accept');
+  const general = CapUrn.fromString(testUrn('op=generate'));
+  assert(general.accepts(cap1), 'General request should accept more specific instance');
+  assert(!cap1.accepts(general), 'Specific pattern should reject general instance');
+
+  const broadIn = CapUrn.fromString('cap:in="media:";op=generate;out="media:record;textable"');
+  assert(!cap1.accepts(broadIn), 'Specific input should not accept broad wildcard input');
+  assert(broadIn.accepts(cap1), 'Wildcard input should accept specific input');
 }
 
-// TEST025: CapMatcher.findBestMatch returns most specific
+// TEST025: Test find_best_match returns most specific matching cap
 function test025_bestMatch() {
   const caps = [
     CapUrn.fromString('cap:in=*;out=*;op=*'),
@@ -441,7 +440,7 @@ function test025_bestMatch() {
   assertEqual(best.getTag('ext'), 'pdf', 'Best match should be the most specific (ext=pdf)');
 }
 
-// TEST026: merge combines tags, subset keeps only specified
+// TEST026: Test merge combines tags from both caps, subset keeps only specified tags
 function test026_mergeAndSubset() {
   const cap1 = CapUrn.fromString(testUrn('op=generate'));
   const cap2 = CapUrn.fromString('cap:in="media:textable";ext=pdf;format=binary;out="media:"');
@@ -460,7 +459,7 @@ function test026_mergeAndSubset() {
   assertEqual(sub.getInSpec(), 'media:textable', 'Subset should preserve inSpec');
 }
 
-// TEST027: withWildcardTag sets tag to wildcard including in/out
+// TEST027: Test with_wildcard_tag sets tag to wildcard, including in/out
 function test027_wildcardTag() {
   const cap = CapUrn.fromString(testUrn('ext=pdf'));
   const wildcardExt = cap.withWildcardTag('ext');
@@ -473,16 +472,14 @@ function test027_wildcardTag() {
   assertEqual(wildcardOut.getOutSpec(), '*', 'Should set out to wildcard');
 }
 
-// TEST028: Empty cap URN without in/out fails (MissingInSpec)
+// TEST028: Test empty cap URN defaults to media: wildcard
 function test028_emptyCapUrnNotAllowed() {
-  assertThrows(
-    () => CapUrn.fromString('cap:'),
-    ErrorCodes.MISSING_IN_SPEC,
-    'Empty cap URN should fail with MISSING_IN_SPEC'
-  );
+  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:');
 }
 
-// TEST029: Minimal valid cap URN: just in and out, empty tags
+// TEST029: Test minimal valid cap URN has just in and out, empty tags
 function test029_minimalCapUrn() {
   const minimal = CapUrn.fromString('cap:in="media:void";out="media:void"');
   assertEqual(Object.keys(minimal.tags).length, 0, 'Should have no other tags');
@@ -490,14 +487,14 @@ function test029_minimalCapUrn() {
   assertEqual(minimal.getOutSpec(), 'media:void', 'Should have outSpec');
 }
 
-// TEST030: Forward slashes and colons in tag values
+// TEST030: Test extended characters (forward slashes, colons) in tag values
 function test030_extendedCharacterSupport() {
   const cap = CapUrn.fromString(testUrn('url=https://example_org/api;path=/some/file'));
   assertEqual(cap.getTag('url'), 'https://example_org/api', 'Should support colons and slashes');
   assertEqual(cap.getTag('path'), '/some/file', 'Should support forward slashes');
 }
 
-// TEST031: Wildcard rejected in keys, accepted in values
+// TEST031: Test wildcard rejected in keys but accepted in values
 function test031_wildcardRestrictions() {
   assertThrows(
     () => CapUrn.fromString(testUrn('*=value')),
@@ -509,13 +506,13 @@ function test031_wildcardRestrictions() {
   const cap = CapUrn.fromString(testUrn('key=*'));
   assertEqual(cap.getTag('key'), '*', 'Should accept wildcard in value');
 
-  // Wildcard in in/out
+  // Wildcard in in/out normalizes to media:
   const capWild = CapUrn.fromString('cap:in=*;out=*;key=value');
-  assertEqual(capWild.getInSpec(), '*', 'Should accept wildcard in inSpec');
-  assertEqual(capWild.getOutSpec(), '*', 'Should accept wildcard in outSpec');
+  assertEqual(capWild.getInSpec(), MEDIA_IDENTITY, 'Wildcard inSpec should normalize to media:');
+  assertEqual(capWild.getOutSpec(), MEDIA_IDENTITY, 'Wildcard outSpec should normalize to media:');
 }
 
-// TEST032: Duplicate keys rejected
+// TEST032: Test duplicate keys are rejected with DuplicateKey error
 function test032_duplicateKeyRejection() {
   assertThrows(
     () => CapUrn.fromString(testUrn('key=value1;key=value2')),
@@ -524,7 +521,7 @@ function test032_duplicateKeyRejection() {
   );
 }
 
-// TEST033: Pure numeric keys rejected, mixed alphanumeric OK
+// TEST033: Test pure numeric keys rejected, mixed alphanumeric allowed, numeric values allowed
 function test033_numericKeyRestriction() {
   assertThrows(
     () => CapUrn.fromString(testUrn('123=value')),
@@ -538,7 +535,7 @@ function test033_numericKeyRestriction() {
   assertEqual(cap2.getTag('x123key'), 'value', 'Mixed alphanumeric key should be allowed');
 }
 
-// TEST034: key= (empty value) is rejected
+// TEST034: Test empty values are rejected
 function test034_emptyValueError() {
   let threw = false;
   try {
@@ -551,7 +548,7 @@ function test034_emptyValueError() {
   assert(threw, 'Empty value (key=) should be rejected');
 }
 
-// TEST035: hasTag case-sensitive for values, case-insensitive for keys, works for in/out
+// TEST035: Test has_tag is case-sensitive for values, case-insensitive for keys, works for in/out
 function test035_hasTagCaseSensitive() {
   const cap = CapUrn.fromString('cap:in="media:void";key="Value";out="media:void"');
   assert(cap.hasTag('key', 'Value'), 'hasTag should match exact value');
@@ -563,26 +560,24 @@ function test035_hasTagCaseSensitive() {
   assert(cap.hasTag('out', 'media:void'), 'hasTag should work for out');
 }
 
-// TEST036: withTag preserves value case
+// TEST036: Test with_tag preserves value case
 function test036_withTagPreservesValue() {
   const cap = CapUrn.fromString('cap:in="media:void";out="media:void"');
   const modified = cap.withTag('key', 'MyValue');
   assertEqual(modified.getTag('key'), 'MyValue', 'withTag should preserve value case');
 }
 
-// TEST037: withTag('key', '') -> error
-// Note: In JS, withTag does not currently reject empty values (it stores them).
-// The Rust implementation rejects empty values. We test the JS behavior as-is.
+// TEST037: Test with_tag rejects empty value
 function test037_withTagRejectsEmptyValue() {
-  // The JS implementation does not throw for empty values in withTag.
-  // This test verifies the current behavior: withTag stores empty string.
-  // If the implementation is updated to reject empty values, update this test.
   const cap = CapUrn.fromString('cap:in="media:void";out="media:void"');
-  const modified = cap.withTag('key', '');
-  assertEqual(modified.getTag('key'), '', 'withTag stores empty string (JS behavior)');
+  assertThrows(
+    () => cap.withTag('key', ''),
+    ErrorCodes.EMPTY_VALUE,
+    'withTag should reject empty string values'
+  );
 }
 
-// TEST038: Unquoted 'simple' == quoted '"simple"' (lowercase)
+// TEST038: Test semantic equivalence of unquoted and quoted simple lowercase values
 function test038_semanticEquivalence() {
   const c1 = CapUrn.fromString('cap:in="media:void";key=simple;out="media:void"');
   const c2 = CapUrn.fromString('cap:in="media:void";key="simple";out="media:void"');
@@ -590,7 +585,7 @@ function test038_semanticEquivalence() {
   assertEqual(c1.getTag('key'), c2.getTag('key'), 'Values should be identical');
 }
 
-// TEST039: getTag('in') and getTag('out') work, case-insensitive
+// TEST039: Test get_tag returns direction specs (in/out) with case-insensitive lookup
 function test039_getTagReturnsDirectionSpecs() {
   const cap = CapUrn.fromString(`cap:in="${MEDIA_VOID}";out="${MEDIA_OBJECT}"`);
   assertEqual(cap.getTag('in'), MEDIA_VOID, 'getTag(in) should return inSpec');
@@ -599,77 +594,81 @@ function test039_getTagReturnsDirectionSpecs() {
   assertEqual(cap.getTag('OUT'), MEDIA_OBJECT, 'getTag(OUT) should return outSpec (case-insensitive)');
 }
 
-// TEST040: Cap and request same tags -> accepts=true
+// TEST040: Matching semantics - exact match succeeds
 function test040_matchingSemanticsExactMatch() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   assert(cap.accepts(request), 'Exact match should accept');
 }
 
-// TEST041: Cap missing tag -> implicit wildcard -> accepts=true
+// TEST041: Matching semantics - cap missing tag matches (implicit wildcard)
 function test041_matchingSemanticsCapMissingTag() {
   const cap = CapUrn.fromString(testUrn('op=generate'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
-  assert(cap.accepts(request), 'Cap missing ext tag should accept (implicit wildcard)');
+  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');
 }
 
-// TEST042: Cap extra tag -> still matches
+// TEST042: Pattern rejects instance missing required tags
 function test042_matchingSemanticsCapHasExtraTag() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf;version=2'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
-  assert(cap.accepts(request), 'Cap with extra tag should still accept');
+  assert(!cap.accepts(request), 'Pattern requiring version should reject instance missing version');
+  assert(request.accepts(cap), 'General request should accept refined instance');
 }
 
-// TEST043: Request ext=* matches cap ext=pdf
+// TEST043: Matching semantics - request wildcard matches specific cap value
 function test043_matchingSemanticsRequestHasWildcard() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=*'));
   assert(cap.accepts(request), 'Request wildcard should match specific cap value');
 }
 
-// TEST044: Cap ext=* matches request ext=pdf
+// TEST044: Matching semantics - cap wildcard matches specific request value
 function test044_matchingSemanticsCapHasWildcard() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=*'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   assert(cap.accepts(request), 'Cap wildcard should match specific request value');
 }
 
-// TEST045: ext=pdf vs ext=docx -> no match
+// TEST045: Matching semantics - value mismatch does not match
 function test045_matchingSemanticsValueMismatch() {
   const cap = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   const request = CapUrn.fromString(testUrn('op=generate;ext=docx'));
   assert(!cap.accepts(request), 'Value mismatch should not accept');
 }
 
-// TEST046: Cap without ext matches request with ext=wav (uses media:binary directions)
+// TEST046: Matching semantics - fallback pattern (cap missing tag = implicit wildcard)
 function test046_matchingSemanticsFallbackPattern() {
   const cap = CapUrn.fromString('cap:in="media:binary";op=generate_thumbnail;out="media:binary"');
   const request = CapUrn.fromString('cap:ext=wav;in="media:binary";op=generate_thumbnail;out="media:binary"');
-  assert(cap.accepts(request), 'Cap missing ext should accept (implicit wildcard for ext)');
+  assert(cap.accepts(request), 'General pattern without ext should accept specific instance');
+  assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
 }
 
-// TEST047: Thumbnail with void input matches specific ext request
+// TEST047: Matching semantics - thumbnail fallback with void input
 function test047_matchingSemanticsThumbnailVoidInput() {
   const cap = CapUrn.fromString('cap:in="media:void";op=generate_thumbnail;out="media:image;png;thumbnail"');
   const request = CapUrn.fromString('cap:ext=pdf;in="media:void";op=generate_thumbnail;out="media:image"');
   assert(cap.accepts(request), 'Void input cap should accept request; cap output conforms to less-specific request output');
 }
 
-// TEST048: Cap in=* out=* matches any request
+// TEST048: Matching semantics - wildcard direction matches anything
 function test048_matchingSemanticsWildcardDirection() {
   const cap = CapUrn.fromString('cap:in=*;out=*');
   const request = CapUrn.fromString(testUrn('op=generate;ext=pdf'));
   assert(cap.accepts(request), 'Wildcard cap should accept any request');
 }
 
-// TEST049: Cap op=generate accepts request ext=pdf (independent tags)
+// TEST049: Non-overlapping tags — neither direction accepts
 function test049_matchingSemanticsCrossDimension() {
   const cap = CapUrn.fromString(testUrn('op=generate'));
   const request = CapUrn.fromString(testUrn('ext=pdf'));
-  assert(cap.accepts(request), 'Independent tags should not block matching');
+  assert(!cap.accepts(request), 'Pattern requiring op should reject instance missing op');
+  assert(!request.accepts(cap), 'Pattern requiring ext should reject instance missing ext');
 }
 
-// TEST050: media:string vs media: (wildcard) -> no match
+// TEST050: Matching semantics - direction mismatch prevents matching
 function test050_matchingSemanticsDirectionMismatch() {
   const cap = CapUrn.fromString(
     `cap:in="${MEDIA_STRING}";op=generate;out="${MEDIA_OBJECT}"`
@@ -758,7 +757,7 @@ function test891_directionSemanticSpecificity() {
 
 // TEST053: N/A for JS (Rust-only validation infrastructure)
 
-// TEST054: Inline media spec redefinition of registry spec is detected
+// TEST054: XV5 - Test inline media spec redefinition of existing registry spec is detected and rejected
 function test054_xv5InlineSpecRedefinitionDetected() {
   const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
   const mediaSpecs = [
@@ -775,7 +774,7 @@ function test054_xv5InlineSpecRedefinitionDetected() {
   assert(result.redefines && result.redefines.includes(MEDIA_STRING), 'Should identify MEDIA_STRING as redefined');
 }
 
-// TEST055: New inline media spec not in registry is allowed
+// TEST055: XV5 - Test new inline media spec (not in registry) is allowed
 function test055_xv5NewInlineSpecAllowed() {
   const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
   const mediaSpecs = [
@@ -790,7 +789,7 @@ function test055_xv5NewInlineSpecAllowed() {
   assert(result.valid, 'New spec not in registry should pass validation');
 }
 
-// TEST056: Empty/null media_specs passes validation
+// TEST056: XV5 - Test empty media_specs (no inline specs) passes XV5 validation
 function test056_xv5EmptyMediaSpecsAllowed() {
   const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
   assert(validateNoMediaSpecRedefinitionSync({}, registryLookup).valid, 'Empty object should pass');
@@ -802,7 +801,7 @@ function test056_xv5EmptyMediaSpecsAllowed() {
 // media_urn.rs: TEST060-TEST078
 // ============================================================================
 
-// TEST060: MediaUrn.fromString('cap:string') -> INVALID_PREFIX error
+// TEST060: Test wrong prefix fails with InvalidPrefix error showing expected and actual prefix
 function test060_wrongPrefixFails() {
   assertThrowsMediaUrn(
     () => MediaUrn.fromString('cap:string'),
@@ -811,7 +810,7 @@ function test060_wrongPrefixFails() {
   );
 }
 
-// TEST061: isBinary true when textable tag is absent (binary = not textable)
+// TEST061: Test is_binary returns true when textable tag is absent (binary = not textable)
 function test061_isBinary() {
   // Binary types: no textable tag
   assert(MediaUrn.fromString(MEDIA_IDENTITY).isBinary(), 'MEDIA_IDENTITY (media:) should be binary');
@@ -827,8 +826,7 @@ function test061_isBinary() {
   assert(!MediaUrn.fromString(MEDIA_MD).isBinary(), 'MEDIA_MD should not be binary');
 }
 
-// TEST062: isMap true for MEDIA_OBJECT (record); false for MEDIA_STRING (form=scalar), MEDIA_STRING_LIST (list)
-// TEST062: is_record returns true if record marker tag is present (key-value structure)
+// TEST062: Test is_record returns true when record marker tag is present indicating key-value structure
 function test062_isRecord() {
   assert(MediaUrn.fromString(MEDIA_OBJECT).isRecord(), 'MEDIA_OBJECT should be record');
   assert(MediaUrn.fromString('media:custom;record').isRecord(), 'custom;record should be record');
@@ -839,7 +837,7 @@ function test062_isRecord() {
   assert(!MediaUrn.fromString(MEDIA_STRING_LIST).isRecord(), 'MEDIA_STRING_LIST should not be record');
 }
 
-// TEST063: is_scalar returns true if NO list marker (scalar is default cardinality)
+// TEST063: Test is_scalar returns true when list marker tag is absent (scalar is default)
 function test063_isScalar() {
   assert(MediaUrn.fromString(MEDIA_STRING).isScalar(), 'MEDIA_STRING should be scalar');
   assert(MediaUrn.fromString(MEDIA_INTEGER).isScalar(), 'MEDIA_INTEGER should be scalar');
@@ -852,8 +850,7 @@ function test063_isScalar() {
   assert(!MediaUrn.fromString(MEDIA_OBJECT_LIST).isScalar(), 'MEDIA_OBJECT_LIST should not be scalar');
 }
 
-// TEST064: isList true for MEDIA_STRING_LIST, MEDIA_INTEGER_LIST, MEDIA_OBJECT_LIST;
-//          false for MEDIA_STRING, MEDIA_OBJECT
+// TEST064: Test is_list returns true when list marker tag is present indicating ordered collection
 function test064_isList() {
   assert(MediaUrn.fromString(MEDIA_STRING_LIST).isList(), 'MEDIA_STRING_LIST should be list');
   assert(MediaUrn.fromString(MEDIA_INTEGER_LIST).isList(), 'MEDIA_INTEGER_LIST should be list');
@@ -862,7 +859,7 @@ function test064_isList() {
   assert(!MediaUrn.fromString(MEDIA_OBJECT).isList(), 'MEDIA_OBJECT should not be list');
 }
 
-// TEST065: is_opaque returns true if NO record marker (opaque is default structure)
+// TEST065: Test is_opaque returns true when record marker is absent (opaque is default)
 function test065_isOpaque() {
   assert(MediaUrn.fromString(MEDIA_STRING).isOpaque(), 'MEDIA_STRING should be opaque');
   assert(MediaUrn.fromString(MEDIA_STRING_LIST).isOpaque(), 'MEDIA_STRING_LIST (list but no record) should be opaque');
@@ -873,13 +870,13 @@ function test065_isOpaque() {
   assert(!MediaUrn.fromString(MEDIA_JSON).isOpaque(), 'MEDIA_JSON should not be opaque');
 }
 
-// TEST066: isJson true for MEDIA_JSON; false for MEDIA_OBJECT (map but not json)
+// TEST066: Test is_json returns true only when json marker tag is present for JSON representation
 function test066_isJson() {
   assert(MediaUrn.fromString(MEDIA_JSON).isJson(), 'MEDIA_JSON should be json');
   assert(!MediaUrn.fromString(MEDIA_OBJECT).isJson(), 'MEDIA_OBJECT should not be json');
 }
 
-// TEST067: is_text returns true only if "textable" marker tag is present
+// TEST067: Test is_text returns true only when textable marker tag is present
 function test067_isText() {
   assert(MediaUrn.fromString(MEDIA_STRING).isText(), 'MEDIA_STRING should be text');
   assert(MediaUrn.fromString(MEDIA_INTEGER).isText(), 'MEDIA_INTEGER should be text');
@@ -890,7 +887,7 @@ function test067_isText() {
   assert(!MediaUrn.fromString(MEDIA_OBJECT).isText(), 'MEDIA_OBJECT (no textable) should not be text');
 }
 
-// TEST068: isVoid true for media:void; false for media:string
+// TEST068: Test is_void returns true when void flag or type=void tag is present
 function test068_isVoid() {
   assert(MediaUrn.fromString('media:void').isVoid(), 'media:void should be void');
   assert(!MediaUrn.fromString(MEDIA_STRING).isVoid(), 'MEDIA_STRING should not be void');
@@ -898,7 +895,7 @@ function test068_isVoid() {
 
 // TEST069-TEST070: N/A for JS (Rust-only binary_media_urn_for_ext/text_media_urn_for_ext)
 
-// TEST071: Parse -> toString -> parse equals original
+// TEST071: Test to_string roundtrip ensures serialization and deserialization preserve URN structure
 function test071_toStringRoundtrip() {
   const constants = [MEDIA_STRING, MEDIA_INTEGER, MEDIA_OBJECT, MEDIA_IDENTITY, MEDIA_PDF, MEDIA_JSON];
   for (const constant of constants) {
@@ -908,7 +905,7 @@ function test071_toStringRoundtrip() {
   }
 }
 
-// TEST072: All MEDIA_* constants parse as valid MediaUrns
+// TEST072: Test all media URN constants parse successfully as valid media URNs
 function test072_constantsParse() {
   const constants = [
     MEDIA_STRING, MEDIA_INTEGER, MEDIA_NUMBER, MEDIA_BOOLEAN,
@@ -928,7 +925,7 @@ function test072_constantsParse() {
 
 // TEST073: N/A for JS (Rust has binary_media_urn_for_ext/text_media_urn_for_ext)
 
-// TEST074: MEDIA_PDF (media:pdf) conformsTo media:pdf; MEDIA_MD conformsTo media:md; same URNs conform
+// TEST074: Test media URN conforms_to using tagged URN semantics with specific and generic requirements
 function test074_mediaUrnMatching() {
   const pdfUrn = MediaUrn.fromString(MEDIA_PDF);
   const pdfPattern = MediaUrn.fromString('media:pdf');
@@ -942,7 +939,7 @@ function test074_mediaUrnMatching() {
   assert(pdfUrn.conformsTo(pdfUrn), 'Same URN should conform to itself');
 }
 
-// TEST075: handler accepts same request, general handler accepts request
+// TEST075: Test accepts with implicit wildcards where handlers with fewer tags can handle more requests
 function test075_accepts() {
   const handler = MediaUrn.fromString(MEDIA_PDF);
   const sameReq = MediaUrn.fromString(MEDIA_PDF);
@@ -953,7 +950,7 @@ function test075_accepts() {
   assert(generalHandler.accepts(specificReq), 'General handler should accept specific request');
 }
 
-// TEST076: More tags = higher specificity
+// TEST076: Test specificity increases with more tags for ranking conformance
 function test076_specificity() {
   const s1 = MediaUrn.fromString('media:');
   const s2 = MediaUrn.fromString('media:pdf');
@@ -962,7 +959,7 @@ function test076_specificity() {
   assert(s3.specificity() > s2.specificity(), 'image;png;thumbnail should be more specific than pdf');
 }
 
-// TEST077: N/A for JS (Rust serde) - but we test JSON.stringify round-trip
+// TEST077: Test serde roundtrip serializes to JSON string and deserializes back correctly
 function test077_serdeRoundtrip() {
   const original = MediaUrn.fromString(MEDIA_PDF);
   const json = JSON.stringify({ urn: original.toString() });
@@ -971,7 +968,7 @@ function test077_serdeRoundtrip() {
   assert(original.equals(restored), 'JSON round-trip should preserve MediaUrn');
 }
 
-// TEST078: MEDIA_OBJECT does NOT conform to MEDIA_STRING
+// TEST078: conforms_to behavior between MEDIA_OBJECT and MEDIA_STRING
 function test078_debugMatchingBehavior() {
   const objUrn = MediaUrn.fromString(MEDIA_OBJECT);
   const strUrn = MediaUrn.fromString(MEDIA_STRING);
@@ -986,7 +983,7 @@ function test078_debugMatchingBehavior() {
 // TEST089: N/A for JS
 // TEST090: N/A for JS
 
-// TEST091: resolveMediaUrn resolves custom from local mediaSpecs
+// TEST091: Test resolving custom media URN from local media_specs takes precedence over registry
 function test091_resolveCustomMediaSpec() {
   const mediaSpecs = [
     { urn: 'media:custom-json', media_type: 'application/json', title: 'Custom JSON', profile_uri: 'https://example.com/schema/custom' }
@@ -996,7 +993,7 @@ function test091_resolveCustomMediaSpec() {
   assertEqual(spec.profile, 'https://example.com/schema/custom', 'Should have custom profile');
 }
 
-// TEST092: resolveMediaUrn resolves with schema from local mediaSpecs
+// TEST092: Test resolving custom record media spec with schema from local media_specs
 function test092_resolveCustomWithSchema() {
   const mediaSpecs = [
     {
@@ -1013,7 +1010,7 @@ function test092_resolveCustomWithSchema() {
   assertEqual(spec.schema.type, 'object', 'Schema should have correct type');
 }
 
-// TEST093: resolveMediaUrn fails hard on unknown URN
+// TEST093: Test resolving unknown media URN fails with UnresolvableMediaUrn error
 function test093_resolveUnresolvableFailsHard() {
   let caught = false;
   try {
@@ -1032,43 +1029,43 @@ function test093_resolveUnresolvableFailsHard() {
 // TEST097: N/A for JS (Rust validation function)
 // TEST098: N/A for JS
 
-// TEST099: MediaSpec with media: (no textable tag) -> isBinary() true
+// TEST099: Test ResolvedMediaSpec is_binary returns true when textable tag is absent
 function test099_resolvedIsBinary() {
   const spec = new MediaSpec('application/octet-stream', null, null, 'Binary', null, MEDIA_IDENTITY);
   assert(spec.isBinary(), 'Resolved binary spec should be binary');
 }
 
-// TEST100: MediaSpec with record -> isRecord() true
+// TEST100: Test ResolvedMediaSpec is_record returns true when record marker is present
 function test100_resolvedIsRecord() {
   const spec = new MediaSpec('application/json', null, null, 'Object', null, MEDIA_OBJECT);
   assert(spec.isRecord(), 'Resolved object spec should be record');
 }
 
-// TEST101: MediaSpec with form=scalar -> isScalar() true
+// TEST101: Test ResolvedMediaSpec is_scalar returns true when list marker is absent
 function test101_resolvedIsScalar() {
   const spec = new MediaSpec('text/plain', null, null, 'String', null, MEDIA_STRING);
   assert(spec.isScalar(), 'Resolved string spec should be scalar');
 }
 
-// TEST102: MediaSpec with list -> isList() true
+// TEST102: Test ResolvedMediaSpec is_list returns true when list marker is present
 function test102_resolvedIsList() {
   const spec = new MediaSpec('text/plain', null, null, 'String List', null, MEDIA_STRING_LIST);
   assert(spec.isList(), 'Resolved string_list spec should be list');
 }
 
-// TEST103: MediaSpec with json tag -> isJSON() true
+// TEST103: Test ResolvedMediaSpec is_json returns true when json tag is present
 function test103_resolvedIsJson() {
   const spec = new MediaSpec('application/json', null, null, 'JSON', null, MEDIA_JSON);
   assert(spec.isJSON(), 'Resolved json spec should be JSON');
 }
 
-// TEST104: MediaSpec with textable tag -> isText() true
+// TEST104: Test ResolvedMediaSpec is_text returns true when textable tag is present
 function test104_resolvedIsText() {
   const spec = new MediaSpec('text/plain', null, null, 'String', null, MEDIA_STRING);
   assert(spec.isText(), 'Resolved string spec should be text');
 }
 
-// TEST105: Metadata propagated from media spec definition
+// TEST105: Test metadata propagates from media spec def to resolved media spec
 function test105_metadataPropagation() {
   const mediaSpecs = [
     {
@@ -1091,7 +1088,7 @@ function test105_metadataPropagation() {
   assertEqual(resolved.metadata.display_index, 5, 'Should propagate display_index');
 }
 
-// TEST106: Metadata and validation coexist
+// TEST106: Test metadata and validation can coexist in media spec definition
 function test106_metadataWithValidation() {
   const mediaSpecs = [
     {
@@ -1110,7 +1107,7 @@ function test106_metadataWithValidation() {
   assertEqual(resolved.metadata.category_key, 'inference', 'Should have category_key');
 }
 
-// TEST107: Extensions field propagated
+// TEST107: Test extensions field propagates from media spec def to resolved
 function test107_extensionsPropagation() {
   const mediaSpecs = [
     {
@@ -1126,7 +1123,7 @@ function test107_extensionsPropagation() {
   assertEqual(resolved.extensions[0], 'pdf', 'Should have pdf extension');
 }
 
-// TEST108: N/A for JS (Rust serde) - but we test MediaSpec with extensions
+// TEST108: Test creating new cap with URN, title, and command verifies correct initialization
 function test108_extensionsSerialization() {
   // Test that MediaSpec can hold extensions correctly
   const spec = new MediaSpec('application/pdf', null, null, 'PDF', null, 'media:pdf', null, null, ['pdf']);
@@ -1134,7 +1131,7 @@ function test108_extensionsSerialization() {
   assertEqual(spec.extensions[0], 'pdf', 'Should have pdf extension');
 }
 
-// TEST109: Extensions coexist with metadata and validation
+// TEST109: Test creating cap with metadata initializes and retrieves metadata correctly
 function test109_extensionsWithMetadataAndValidation() {
   const mediaSpecs = [
     {
@@ -1153,7 +1150,7 @@ function test109_extensionsWithMetadataAndValidation() {
   assertEqual(resolved.extensions[0], 'json', 'Should have json extension');
 }
 
-// TEST110: Multiple extensions in a media spec
+// TEST110: Test cap matching with subset semantics for request fulfillment
 function test110_multipleExtensions() {
   const mediaSpecs = [
     {
@@ -1173,7 +1170,7 @@ function test110_multipleExtensions() {
 // cap_matrix.rs: TEST117-TEST131
 // ============================================================================
 
-// TEST117: CapBlock finds more specific cap across registries
+// TEST117: Test registering cap set and finding by exact and subset matching
 function test117_capBlockMoreSpecificWins() {
   const providerRegistry = new CapMatrix();
   const cartridgeRegistry = new CapMatrix();
@@ -1203,7 +1200,7 @@ function test117_capBlockMoreSpecificWins() {
   assertEqual(best.cap.title, 'Cartridge PDF Thumbnail Generator (specific)', 'Should get cartridge cap');
 }
 
-// TEST118: CapBlock tie-breaking prefers first registry in order
+// TEST118: Test selecting best cap set based on specificity ranking With is_dispatchable semantics: - Provider must satisfy ALL request constraints - General request matches specific provider (provider refines request) - Specific request does NOT match general provider (provider lacks constraints)
 function test118_capBlockTieGoesToFirst() {
   const registry1 = new CapMatrix();
   const registry2 = new CapMatrix();
@@ -1224,7 +1221,7 @@ function test118_capBlockTieGoesToFirst() {
   assertEqual(best.registryName, 'first', 'On tie, first registry should win');
 }
 
-// TEST119: CapBlock polls all registries to find best match
+// TEST119: Test invalid URN returns InvalidUrn error
 function test119_capBlockPollsAll() {
   const registry1 = new CapMatrix();
   const registry2 = new CapMatrix();
@@ -1251,7 +1248,7 @@ function test119_capBlockPollsAll() {
   assertEqual(best.registryName, 'r3', 'Most specific registry should win');
 }
 
-// TEST120: CapBlock returns error when no cap matches request
+// TEST120: Test accepts_request checks if registry can handle a capability request
 function test120_capBlockNoMatch() {
   const registry = new CapMatrix();
   const composite = new CapBlock();
@@ -1266,7 +1263,7 @@ function test120_capBlockNoMatch() {
   }
 }
 
-// TEST121: CapBlock fallback scenario where generic cap handles unknown file types
+// TEST121: Test CapBlock selects more specific cap over less specific regardless of registry order
 function test121_capBlockFallbackScenario() {
   const providerRegistry = new CapMatrix();
   const cartridgeRegistry = new CapMatrix();
@@ -1298,7 +1295,7 @@ function test121_capBlockFallbackScenario() {
   assertEqual(bestWav.registryName, 'providers', 'Provider should win for wav (fallback)');
 }
 
-// TEST122: CapBlock can method returns execution info and acceptsRequest checks capability
+// TEST122: Test CapBlock breaks specificity ties by first registered registry
 function test122_capBlockCanMethod() {
   const providerRegistry = new CapMatrix();
   const providerHost = new MockCapSet('test_provider');
@@ -1315,7 +1312,7 @@ function test122_capBlockCanMethod() {
   assert(!composite.acceptsRequest(matrixTestUrn('op=nonexistent')), 'Should not accept non-matching cap');
 }
 
-// TEST123: CapBlock registry management add, get, remove operations
+// TEST123: Test CapBlock polls all registries to find most specific match
 function test123_capBlockRegistryManagement() {
   const composite = new CapBlock();
   const registry1 = new CapMatrix();
@@ -1334,7 +1331,7 @@ function test123_capBlockRegistryManagement() {
   assertEqual(composite.getRegistry('nonexistent'), null, 'Should return null for non-existent');
 }
 
-// TEST124: CapGraph basic construction builds nodes and edges from caps
+// TEST124: Test CapBlock returns error when no registries match the request
 function test124_capGraphBasicConstruction() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1353,7 +1350,7 @@ function test124_capGraphBasicConstruction() {
   assertEqual(graph.stats().edgeCount, 2, 'Expected 2 edges in stats');
 }
 
-// TEST125: CapGraph getOutgoing and getIncoming return correct edges for media URN
+// TEST125: Test CapBlock prefers specific cartridge over generic provider fallback
 function test125_capGraphOutgoingIncoming() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1371,7 +1368,7 @@ function test125_capGraphOutgoingIncoming() {
   assertEqual(graph.getIncoming('media:object').length, 1, 'object should have 1 incoming');
 }
 
-// TEST126: CapGraph canConvert checks direct and transitive conversion paths
+// TEST126: Test composite can method returns CapCaller for capability execution
 function test126_capGraphCanConvert() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1392,7 +1389,7 @@ function test126_capGraphCanConvert() {
   assert(!graph.canConvert('media:nonexistent', 'media:string'), 'Nonexistent node');
 }
 
-// TEST127: CapGraph findPath returns shortest path between media URNs
+// TEST127: Test CapGraph adds nodes and edges from capability definitions
 function test127_capGraphFindPath() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1425,7 +1422,7 @@ function test127_capGraphFindPath() {
   assertEqual(path.length, 0, 'Same spec path should be empty');
 }
 
-// TEST128: CapGraph findAllPaths returns all paths sorted by length
+// TEST128: Test CapGraph tracks outgoing and incoming edges for spec conversions
 function test128_capGraphFindAllPaths() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1445,7 +1442,7 @@ function test128_capGraphFindAllPaths() {
   assertEqual(paths[1].length, 2, 'Longer path second (via string)');
 }
 
-// TEST129: CapGraph getDirectEdges returns edges sorted by specificity
+// TEST129: Test CapGraph detects direct and indirect conversion paths between specs
 function test129_capGraphGetDirectEdges() {
   const registry1 = new CapMatrix();
   const registry2 = new CapMatrix();
@@ -1470,7 +1467,7 @@ function test129_capGraphGetDirectEdges() {
   assert(edges[0].specificity > edges[1].specificity, 'First edge should have higher specificity');
 }
 
-// TEST130: CapGraph stats returns node count, edge count, input/output URN counts
+// TEST130: Test CapGraph finds shortest path for spec conversion chain
 function test130_capGraphStats() {
   const registry = new CapMatrix();
   const mockHost = { executeCap: async () => ({ textOutput: 'mock' }) };
@@ -1491,7 +1488,7 @@ function test130_capGraphStats() {
   assertEqual(stats.outputUrnCount, 3, '3 output URNs');
 }
 
-// TEST131: CapGraph with CapBlock builds graph from multiple registries
+// TEST131: Test CapGraph finds all conversion paths sorted by length
 function test131_capGraphWithCapBlock() {
   const providerRegistry = new CapMatrix();
   const cartridgeRegistry = new CapMatrix();
@@ -1525,7 +1522,7 @@ function test131_capGraphWithCapBlock() {
 // caller.rs: TEST156-TEST159
 // ============================================================================
 
-// TEST156: Creating StdinSource Data variant with byte vector
+// TEST156: Test creating StdinSource Data variant with byte vector
 function test156_stdinSourceFromData() {
   const testData = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
   const source = StdinSource.fromData(testData);
@@ -1536,7 +1533,7 @@ function test156_stdinSourceFromData() {
   assertEqual(source.data, testData, 'Should store data');
 }
 
-// TEST157: Creating StdinSource FileReference variant with all required fields
+// TEST157: Test creating StdinSource FileReference variant with all required fields
 function test157_stdinSourceFromFileReference() {
   const trackedFileId = 'tracked-file-123';
   const originalPath = '/path/to/original.pdf';
@@ -1553,7 +1550,7 @@ function test157_stdinSourceFromFileReference() {
   assertEqual(source.mediaUrn, mediaUrn, 'Should store mediaUrn');
 }
 
-// TEST158: StdinSource Data with empty vector stores and retrieves correctly
+// TEST158: Test StdinSource Data with empty vector stores and retrieves correctly
 function test158_stdinSourceWithEmptyData() {
   const emptyData = new Uint8Array(0);
   const source = StdinSource.fromData(emptyData);
@@ -1561,7 +1558,7 @@ function test158_stdinSourceWithEmptyData() {
   assertEqual(source.data.length, 0, 'Data length should be 0');
 }
 
-// TEST159: StdinSource Data with binary content like PNG header bytes
+// TEST159: Test StdinSource Data with binary content like PNG header bytes
 function test159_stdinSourceWithBinaryContent() {
   const pngHeader = new Uint8Array([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
   const source = StdinSource.fromData(pngHeader);
@@ -1575,27 +1572,27 @@ function test159_stdinSourceWithBinaryContent() {
 // caller.rs: TEST274-TEST283
 // ============================================================================
 
-// TEST274: CapArgumentValue constructor stores media_urn and raw byte value
+// TEST274: Test CapArgumentValue::new stores media_urn and raw byte value
 function test274_capArgumentValueNew() {
   const arg = new CapArgumentValue('media:model-spec;textable', new Uint8Array([103, 112, 116, 45, 52]));
   assertEqual(arg.mediaUrn, 'media:model-spec;textable', 'mediaUrn must match');
   assertEqual(arg.value.length, 5, 'value must have 5 bytes');
 }
 
-// TEST275: CapArgumentValue.fromStr converts string to UTF-8 bytes
+// TEST275: Test CapArgumentValue::from_str converts string to UTF-8 bytes
 function test275_capArgumentValueFromStr() {
   const arg = CapArgumentValue.fromStr('media:string;textable', 'hello world');
   assertEqual(arg.mediaUrn, 'media:string;textable', 'mediaUrn must match');
   assertEqual(new TextDecoder().decode(arg.value), 'hello world', 'value must decode correctly');
 }
 
-// TEST276: CapArgumentValue.valueAsStr succeeds for UTF-8 data
+// TEST276: Test CapArgumentValue::value_as_str succeeds for UTF-8 data
 function test276_capArgumentValueAsStrValid() {
   const arg = CapArgumentValue.fromStr('media:string', 'test');
   assertEqual(arg.valueAsStr(), 'test', 'valueAsStr must return test');
 }
 
-// TEST277: CapArgumentValue.valueAsStr fails for non-UTF-8 binary data
+// TEST277: Test CapArgumentValue::value_as_str fails for non-UTF-8 binary data
 function test277_capArgumentValueAsStrInvalidUtf8() {
   const arg = new CapArgumentValue('media:pdf', new Uint8Array([0xFF, 0xFE, 0x80]));
   let threw = false;
@@ -1607,7 +1604,7 @@ function test277_capArgumentValueAsStrInvalidUtf8() {
   assert(threw, 'non-UTF-8 data must fail on valueAsStr with fatal decoder');
 }
 
-// TEST278: CapArgumentValue with empty value stores empty Uint8Array
+// TEST278: Test CapArgumentValue::new with empty value stores empty vec
 function test278_capArgumentValueEmpty() {
   const arg = new CapArgumentValue('media:void', new Uint8Array([]));
   assertEqual(arg.value.length, 0, 'empty value must have 0 bytes');
@@ -1616,13 +1613,13 @@ function test278_capArgumentValueEmpty() {
 
 // TEST279-281: N/A for JS (Rust Debug/Clone/Send traits)
 
-// TEST282: CapArgumentValue.fromStr with Unicode string preserves all characters
+// TEST282: Test CapArgumentValue::from_str with Unicode string preserves all characters
 function test282_capArgumentValueUnicode() {
   const arg = CapArgumentValue.fromStr('media:string', 'hello \u4e16\u754c \ud83c\udf0d');
   assertEqual(arg.valueAsStr(), 'hello \u4e16\u754c \ud83c\udf0d', 'Unicode must roundtrip');
 }
 
-// TEST283: CapArgumentValue with large binary payload preserves all bytes
+// TEST283: Test CapArgumentValue with large binary payload preserves all bytes
 function test283_capArgumentValueLargeBinary() {
   const data = new Uint8Array(10000);
   for (let i = 0; i < 10000; i++) {
@@ -1641,7 +1638,7 @@ function test283_capArgumentValueLargeBinary() {
 
 const { TaggedUrn } = require('tagged-urn');
 
-// TEST304: MEDIA_AVAILABILITY_OUTPUT constant parses as valid media URN with correct tags
+// TEST304: Test MEDIA_AVAILABILITY_OUTPUT constant parses as valid media URN with correct tags
 function test304_mediaAvailabilityOutputConstant() {
   const urn = TaggedUrn.fromString(MEDIA_AVAILABILITY_OUTPUT);
   assert(urn.getTag('textable') !== undefined, 'model-availability must be textable');
@@ -1651,7 +1648,7 @@ function test304_mediaAvailabilityOutputConstant() {
   assert(urn.conformsTo(reparsed), 'roundtrip must match original');
 }
 
-// TEST305: MEDIA_PATH_OUTPUT constant parses as valid media URN with correct tags
+// TEST305: Test MEDIA_PATH_OUTPUT constant parses as valid media URN with correct tags
 function test305_mediaPathOutputConstant() {
   const urn = TaggedUrn.fromString(MEDIA_PATH_OUTPUT);
   assert(urn.getTag('textable') !== undefined, 'model-path must be textable');
@@ -1661,7 +1658,7 @@ function test305_mediaPathOutputConstant() {
   assert(urn.conformsTo(reparsed), 'roundtrip must match original');
 }
 
-// TEST306: MEDIA_AVAILABILITY_OUTPUT and MEDIA_PATH_OUTPUT are distinct URNs
+// TEST306: Test MEDIA_AVAILABILITY_OUTPUT and MEDIA_PATH_OUTPUT are distinct URNs
 function test306_availabilityAndPathOutputDistinct() {
   assert(MEDIA_AVAILABILITY_OUTPUT !== MEDIA_PATH_OUTPUT, 'Must be distinct');
   const avail = TaggedUrn.fromString(MEDIA_AVAILABILITY_OUTPUT);
@@ -1675,7 +1672,7 @@ function test306_availabilityAndPathOutputDistinct() {
   assert(!matchResult, 'availability must not conform to path');
 }
 
-// TEST307: model_availability_urn builds valid cap URN with correct op and media specs
+// 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');
@@ -1687,7 +1684,7 @@ function test307_modelAvailabilityUrn() {
   assert(outSpec.conformsTo(expectedOut), 'output must conform to MEDIA_AVAILABILITY_OUTPUT');
 }
 
-// TEST308: model_path_urn builds valid cap URN with correct op and media specs
+// 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');
@@ -1699,23 +1696,27 @@ function test308_modelPathUrn() {
   assert(outSpec.conformsTo(expectedOut), 'output must conform to MEDIA_PATH_OUTPUT');
 }
 
-// TEST309: model_availability_urn and model_path_urn produce distinct URNs
+// TEST309: Test model_availability_urn and model_path_urn produce distinct URNs
 function test309_modelAvailabilityAndPathAreDistinct() {
   const avail = modelAvailabilityUrn();
   const path = modelPathUrn();
   assert(avail.toString() !== path.toString(), 'availability and path must be distinct');
 }
 
-// TEST310: llm_generate_text_urn has correct op and ml-model tags
+// 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.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)),
+    'in_spec must conform to MEDIA_STRING');
+  assert(TaggedUrn.fromString(urn.getOutSpec()).conformsTo(TaggedUrn.fromString(MEDIA_STRING)),
+    'out_spec must conform to MEDIA_STRING');
 }
 
-// TEST311: llm_generate_text_urn in/out specs match MEDIA_STRING
-function test311_llmGenerateTextUrnSpecs() {
+// Mirror-specific coverage: llm_generate_text_urn input/output specs conform to MEDIA_STRING
+function testLlmGenerateTextUrnSpecs() {
   const urn = llmGenerateTextUrn();
   const inSpec = TaggedUrn.fromString(urn.getInSpec());
   const expectedIn = TaggedUrn.fromString(MEDIA_STRING);
@@ -1725,7 +1726,7 @@ function test311_llmGenerateTextUrnSpecs() {
   assert(outSpec.conformsTo(expectedOut), 'out_spec must conform to MEDIA_STRING');
 }
 
-// TEST312: All URN builders produce parseable cap URNs
+// TEST312: Test all URN builders produce parseable cap URNs
 function test312_allUrnBuildersProduceValidUrns() {
   const avail = modelAvailabilityUrn();
   const path = modelPathUrn();
@@ -2090,7 +2091,7 @@ const sampleRegistry = {
   }
 };
 
-// TEST320: Cartridge info construction
+// TEST320-335: CartridgeRepoServer and CartridgeRepoClient tests
 function test320_cartridgeInfoConstruction() {
   const data = {
     id: 'testcartridge',
@@ -2117,7 +2118,7 @@ function test320_cartridgeInfoConstruction() {
   assert(cartridge.caps[0].urn === 'cap:in="media:void";op=test;out="media:void"', 'Cap URN should match');
 }
 
-// TEST321: Cartridge info is signed check
+// TEST321: CartridgeInfo.is_signed() returns true when signature is present
 function test321_cartridgeInfoIsSigned() {
   const signed = new CartridgeInfo({id: 'test', teamId: 'TEAM', signedAt: '2026-01-01', caps: []});
   assert(signed.isSigned() === true, 'Cartridge with teamId and signedAt should be signed');
@@ -2129,7 +2130,7 @@ function test321_cartridgeInfoIsSigned() {
   assert(unsigned2.isSigned() === false, 'Cartridge without signedAt should not be signed');
 }
 
-// TEST322: Cartridge info build for platform and available platforms
+// TEST322: CartridgeInfo.build_for_platform() returns the build matching the current platform
 function test322_cartridgeInfoBuildForPlatform() {
   const withBuilds = new CartridgeInfo({
     id: 'test', version: '1.0.0', caps: [],
@@ -2163,7 +2164,7 @@ function test322_cartridgeInfoBuildForPlatform() {
   assert(noBuilds.availablePlatforms().length === 0, 'Should have no platforms');
 }
 
-// TEST323: CartridgeRepoServer validate registry
+// TEST323: CartridgeRepoServer validates registry JSON schema version
 function test323_cartridgeRepoServerValidateRegistry() {
   // Valid registry
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2190,7 +2191,7 @@ function test323_cartridgeRepoServerValidateRegistry() {
   assert(threw, 'Should throw for missing cartridges');
 }
 
-// TEST324: CartridgeRepoServer transform to array
+// TEST324: CartridgeRepoServer transforms v3 registry JSON into flat cartridge array
 function test324_cartridgeRepoServerTransformToArray() {
   const server = new CartridgeRepoServer(sampleRegistry);
   const cartridges = server.transformToCartridgeArray();
@@ -2215,7 +2216,7 @@ function test324_cartridgeRepoServerTransformToArray() {
   assert(pdf.caps.length === 2, 'Should have 2 caps');
 }
 
-// TEST325: CartridgeRepoServer get cartridges
+// TEST325: CartridgeRepoServer.get_cartridges() returns all parsed cartridges
 function test325_cartridgeRepoServerGetCartridges() {
   const server = new CartridgeRepoServer(sampleRegistry);
   const response = server.getCartridges();
@@ -2225,7 +2226,7 @@ function test325_cartridgeRepoServerGetCartridges() {
   assert(response.cartridges.length === 2, 'Should have 2 cartridges');
 }
 
-// TEST326: CartridgeRepoServer get cartridge by ID
+// TEST326: CartridgeRepoServer.get_cartridge() returns cartridge matching the given ID
 function test326_cartridgeRepoServerGetCartridgeById() {
   const server = new CartridgeRepoServer(sampleRegistry);
 
@@ -2237,7 +2238,7 @@ function test326_cartridgeRepoServerGetCartridgeById() {
   assert(notFound === undefined, 'Should return undefined for missing cartridge');
 }
 
-// TEST327: CartridgeRepoServer search cartridges
+// TEST327: CartridgeRepoServer.search_cartridges() filters by text query against name and description
 function test327_cartridgeRepoServerSearchCartridges() {
   const server = new CartridgeRepoServer(sampleRegistry);
 
@@ -2252,7 +2253,7 @@ function test327_cartridgeRepoServerSearchCartridges() {
   assert(noResults.length === 0, 'Should return empty for no matches');
 }
 
-// TEST328: CartridgeRepoServer get by category
+// TEST328: CartridgeRepoServer.get_by_category() filters cartridges by category tag
 function test328_cartridgeRepoServerGetByCategory() {
   const server = new CartridgeRepoServer(sampleRegistry);
 
@@ -2265,7 +2266,7 @@ function test328_cartridgeRepoServerGetByCategory() {
   assert(textCartridges[0].id === 'txtcartridge', 'Should be txtcartridge');
 }
 
-// TEST329: CartridgeRepoServer get by cap
+// TEST329: CartridgeRepoServer.get_suggestions_for_cap() finds cartridges providing a given cap URN
 function test329_cartridgeRepoServerGetByCap() {
   const server = new CartridgeRepoServer(sampleRegistry);
 
@@ -2280,7 +2281,7 @@ function test329_cartridgeRepoServerGetByCap() {
   assert(metadataCartridges.length === 1, 'Should find metadata cap');
 }
 
-// TEST330: CartridgeRepoClient update cache
+// TEST330: CartridgeRepoClient updates its local cache from server response
 function test330_cartridgeRepoClientUpdateCache() {
   const client = new CartridgeRepoClient(3600);
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2294,7 +2295,7 @@ function test330_cartridgeRepoClientUpdateCache() {
   assert(cache.capToCartridges.size > 0, 'Should have cap mappings');
 }
 
-// TEST331: CartridgeRepoClient get suggestions
+// TEST331: CartridgeRepoClient.get_suggestions_for_cap() returns cartridge suggestions for a cap URN
 function test331_cartridgeRepoClientGetSuggestions() {
   const client = new CartridgeRepoClient(3600);
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2311,7 +2312,7 @@ function test331_cartridgeRepoClientGetSuggestions() {
   assert(suggestions[0].capTitle === 'Disbind PDF', 'Should have cap title');
 }
 
-// TEST332: CartridgeRepoClient get cartridge
+// TEST332: CartridgeRepoClient.get_cartridge() retrieves a specific cartridge by ID from cache
 function test332_cartridgeRepoClientGetCartridge() {
   const client = new CartridgeRepoClient(3600);
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2327,7 +2328,7 @@ function test332_cartridgeRepoClientGetCartridge() {
   assert(notFound === null, 'Should return null for missing cartridge');
 }
 
-// TEST333: CartridgeRepoClient get all caps
+// TEST333: CartridgeRepoClient.get_all_caps() returns aggregate cap URNs from all cached cartridges
 function test333_cartridgeRepoClientGetAllCaps() {
   const client = new CartridgeRepoClient(3600);
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2341,7 +2342,7 @@ function test333_cartridgeRepoClientGetAllCaps() {
   assert(caps.every(c => typeof c === 'string'), 'All caps should be strings');
 }
 
-// TEST334: CartridgeRepoClient needs sync
+// TEST334: CartridgeRepoClient.needs_sync() returns true when cache TTL has expired
 function test334_cartridgeRepoClientNeedsSync() {
   const client = new CartridgeRepoClient(1); // 1 second TTL
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2362,7 +2363,7 @@ function test334_cartridgeRepoClientNeedsSync() {
   // Note: Can't test this synchronously, would need async test
 }
 
-// TEST335: CartridgeRepoServer and Client integration
+// TEST335: Server creates registry response and client consumes it end-to-end
 function test335_cartridgeRepoServerClientIntegration() {
   // Server creates API response
   const server = new CartridgeRepoServer(sampleRegistry);
@@ -2392,11 +2393,11 @@ function test335_cartridgeRepoServerClientIntegration() {
 }
 
 // ============================================================================
-// media_urn.rs: TEST546-TEST558 (MediaUrn predicates)
+// media_urn.rs: TEST1294-TEST1302 (MediaUrn predicates)
 // ============================================================================
 
-// TEST546: isImage returns true only when image marker tag is present
-function test546_isImage() {
+// TEST1312: is_image returns true only when image marker tag is present
+function test1312_isImage() {
   assert(MediaUrn.fromString(MEDIA_PNG).isImage(), 'MEDIA_PNG should be image');
   assert(MediaUrn.fromString('media:image;png;thumbnail').isImage(), 'media:image;png;thumbnail should be image');
   assert(MediaUrn.fromString('media:image;jpg').isImage(), 'media:image;jpg should be image');
@@ -2407,8 +2408,8 @@ function test546_isImage() {
   assert(!MediaUrn.fromString(MEDIA_VIDEO).isImage(), 'MEDIA_VIDEO should not be image');
 }
 
-// TEST547: isAudio returns true only when audio marker tag is present
-function test547_isAudio() {
+// TEST1313: is_audio returns true only when audio marker tag is present
+function test1313_isAudio() {
   assert(MediaUrn.fromString(MEDIA_AUDIO).isAudio(), 'MEDIA_AUDIO should be audio');
   assert(MediaUrn.fromString(MEDIA_AUDIO_SPEECH).isAudio(), 'MEDIA_AUDIO_SPEECH should be audio');
   assert(MediaUrn.fromString('media:audio;mp3').isAudio(), 'media:audio;mp3 should be audio');
@@ -2418,8 +2419,8 @@ function test547_isAudio() {
   assert(!MediaUrn.fromString(MEDIA_STRING).isAudio(), 'MEDIA_STRING should not be audio');
 }
 
-// TEST548: isVideo returns true only when video marker tag is present
-function test548_isVideo() {
+// TEST1314: is_video returns true only when video marker tag is present
+function test1314_isVideo() {
   assert(MediaUrn.fromString(MEDIA_VIDEO).isVideo(), 'MEDIA_VIDEO should be video');
   assert(MediaUrn.fromString('media:video;mp4').isVideo(), 'media:video;mp4 should be video');
   // Non-video types
@@ -2428,8 +2429,8 @@ function test548_isVideo() {
   assert(!MediaUrn.fromString(MEDIA_STRING).isVideo(), 'MEDIA_STRING should not be video');
 }
 
-// TEST549: isNumeric returns true only when numeric marker tag is present
-function test549_isNumeric() {
+// TEST1315: is_numeric returns true only when numeric marker tag is present
+function test1315_isNumeric() {
   assert(MediaUrn.fromString(MEDIA_INTEGER).isNumeric(), 'MEDIA_INTEGER should be numeric');
   assert(MediaUrn.fromString(MEDIA_NUMBER).isNumeric(), 'MEDIA_NUMBER should be numeric');
   assert(MediaUrn.fromString(MEDIA_INTEGER_LIST).isNumeric(), 'MEDIA_INTEGER_LIST should be numeric');
@@ -2440,8 +2441,8 @@ function test549_isNumeric() {
   assert(!MediaUrn.fromString(MEDIA_IDENTITY).isNumeric(), 'MEDIA_IDENTITY should not be numeric');
 }
 
-// TEST550: isBool returns true only when bool marker tag is present
-function test550_isBool() {
+// TEST1298: is_bool returns true only when bool marker tag is present
+function test1298_isBool() {
   assert(MediaUrn.fromString(MEDIA_BOOLEAN).isBool(), 'MEDIA_BOOLEAN should be bool');
   assert(MediaUrn.fromString(MEDIA_BOOLEAN_LIST).isBool(), 'MEDIA_BOOLEAN_LIST should be bool');
   // MEDIA_DECISION is now a JSON record type (not bool)
@@ -2452,8 +2453,8 @@ function test550_isBool() {
   assert(!MediaUrn.fromString(MEDIA_IDENTITY).isBool(), 'MEDIA_IDENTITY should not be bool');
 }
 
-// TEST551: isFilePath returns true for scalar file-path, false for array
-function test551_isFilePath() {
+// TEST1299: is_file_path returns true for scalar file-path, false for array
+function test1299_isFilePath() {
   assert(MediaUrn.fromString(MEDIA_FILE_PATH).isFilePath(), 'MEDIA_FILE_PATH should be file-path');
   // Array file-path is NOT isFilePath (it's isFilePathArray)
   assert(!MediaUrn.fromString(MEDIA_FILE_PATH_ARRAY).isFilePath(), 'MEDIA_FILE_PATH_ARRAY should not be isFilePath');
@@ -2462,8 +2463,8 @@ function test551_isFilePath() {
   assert(!MediaUrn.fromString(MEDIA_IDENTITY).isFilePath(), 'MEDIA_IDENTITY should not be file-path');
 }
 
-// TEST552: isFilePathArray returns true for list file-path, false for scalar
-function test552_isFilePathArray() {
+// TEST1300: is_file_path_array returns true for list file-path, false for scalar
+function test1300_isFilePathArray() {
   assert(MediaUrn.fromString(MEDIA_FILE_PATH_ARRAY).isFilePathArray(), 'MEDIA_FILE_PATH_ARRAY should be file-path-array');
   // Scalar file-path is NOT isFilePathArray
   assert(!MediaUrn.fromString(MEDIA_FILE_PATH).isFilePathArray(), 'MEDIA_FILE_PATH should not be isFilePathArray');
@@ -2471,8 +2472,8 @@ function test552_isFilePathArray() {
   assert(!MediaUrn.fromString(MEDIA_STRING_LIST).isFilePathArray(), 'MEDIA_STRING_LIST should not be file-path-array');
 }
 
-// TEST553: isAnyFilePath returns true for both scalar and array file-path
-function test553_isAnyFilePath() {
+// TEST1301: is_any_file_path returns true for both scalar and array file-path
+function test1301_isAnyFilePath() {
   assert(MediaUrn.fromString(MEDIA_FILE_PATH).isAnyFilePath(), 'MEDIA_FILE_PATH should be any-file-path');
   assert(MediaUrn.fromString(MEDIA_FILE_PATH_ARRAY).isAnyFilePath(), 'MEDIA_FILE_PATH_ARRAY should be any-file-path');
   // Non-file-path types
@@ -2480,9 +2481,9 @@ function test553_isAnyFilePath() {
   assert(!MediaUrn.fromString(MEDIA_STRING_LIST).isAnyFilePath(), 'MEDIA_STRING_LIST should not be any-file-path');
 }
 
-// TEST554: isCollection returns true when collection marker tag is present
-// TEST554: N/A for JS (MEDIA_COLLECTION constants removed - no longer exists)
-function test554_isCollection() {
+// Mirror-specific coverage: isCollection returns true when collection marker tag is present
+// Mirror-specific coverage: N/A for JS (MEDIA_COLLECTION constants removed - no longer exists)
+function testisCollection() {
   // Skip - collection types removed from capdag
 }
 
@@ -2492,8 +2493,8 @@ function test554_isCollection() {
 
 // TEST557: N/A for JS (audio_media_urn_for_ext helper not in JS)
 
-// TEST558: predicates are consistent with constants - every constant triggers exactly the expected predicates
-function test558_predicateConstantConsistency() {
+// TEST1302: predicates are consistent with constants — every constant triggers exactly the expected predicates
+function test1302_predicateConstantConsistency() {
   // MEDIA_INTEGER must be numeric, text, scalar, NOT binary/bool/image/audio/video
   const intUrn = MediaUrn.fromString(MEDIA_INTEGER);
   assert(intUrn.isNumeric(), 'MEDIA_INTEGER must be numeric');
@@ -2529,11 +2530,11 @@ function test558_predicateConstantConsistency() {
 }
 
 // ============================================================================
-// cap_urn.rs: TEST559-TEST567 (CapUrn tier tests)
+// cap_urn.rs: TEST1303-TEST1307 (CapUrn tier tests)
 // ============================================================================
 
-// TEST559: withoutTag removes tag, ignores in/out, case-insensitive for keys
-function test559_withoutTag() {
+// TEST1303: without_tag removes tag, ignores in/out, case-insensitive for keys
+function test1303_withoutTag() {
   const cap = CapUrn.fromString('cap:in="media:void";op=test;ext=pdf;out="media:void"');
   const removed = cap.withoutTag('ext');
   assertEqual(removed.getTag('ext'), undefined, 'withoutTag should remove ext');
@@ -2554,8 +2555,8 @@ function test559_withoutTag() {
   assert(same3.equals(cap), 'Removing non-existent tag is no-op');
 }
 
-// TEST560: withInSpec and withOutSpec change direction specs
-function test560_withInOutSpec() {
+// TEST1304: with_in_spec and with_out_spec change direction specs
+function test1304_withInOutSpec() {
   const cap = CapUrn.fromString('cap:in="media:void";op=test;out="media:void"');
 
   const changedIn = cap.withInSpec('media:');
@@ -2568,17 +2569,17 @@ function test560_withInOutSpec() {
   assertEqual(changedOut.getOutSpec(), 'media:string', 'withOutSpec should change outSpec');
 
   // Chain both
-  const changedBoth = cap.withInSpec('media:pdf').withOutSpec('media:txt;textable');
+  const changedBoth = cap.withInSpec('media:pdf').withOutSpec(MEDIA_TXT);
   assertEqual(changedBoth.getInSpec(), 'media:pdf', 'Chain should set inSpec');
-  assertEqual(changedBoth.getOutSpec(), 'media:txt;textable', 'Chain should set outSpec');
+  assertEqual(changedBoth.getOutSpec(), MEDIA_TXT, 'Chain should set outSpec');
 }
 
 // TEST561: N/A for JS (in_media_urn/out_media_urn not in JS CapUrn)
 
 // TEST562: N/A for JS (canonical_option not in JS CapUrn)
 
-// TEST563: CapMatcher.findAllMatches returns all matching caps sorted by specificity
-function test563_findAllMatches() {
+// TEST1305: CapMatcher::find_all_matches returns all matching caps sorted by specificity
+function test1305_findAllMatches() {
   const caps = [
     CapUrn.fromString('cap:in="media:void";op=test;out="media:void"'),
     CapUrn.fromString('cap:in="media:void";op=test;ext=pdf;out="media:void"'),
@@ -2595,8 +2596,8 @@ function test563_findAllMatches() {
   assertEqual(matches[0].getTag('ext'), 'pdf', 'Most specific match should have ext=pdf');
 }
 
-// TEST564: CapMatcher.areCompatible detects bidirectional overlap
-function test564_areCompatible() {
+// TEST1306: CapMatcher::are_compatible detects bidirectional overlap
+function test1306_areCompatible() {
   const caps1 = [
     CapUrn.fromString('cap:in="media:void";op=test;out="media:void"'),
   ];
@@ -2620,8 +2621,8 @@ function test564_areCompatible() {
 
 // TEST565: N/A for JS (tags_to_string not in JS CapUrn)
 
-// TEST566: withTag silently ignores in/out keys
-function test566_withTagIgnoresInOut() {
+// TEST1307: with_tag silently ignores in/out keys
+function test1307_withTagIgnoresInOut() {
   const cap = CapUrn.fromString('cap:in="media:void";op=test;out="media:void"');
   // Attempting to set in/out via withTag is silently ignored
   const same = cap.withTag('in', 'media:');
@@ -2631,41 +2632,129 @@ function test566_withTagIgnoresInOut() {
   assertEqual(same2.getOutSpec(), 'media:void', 'withTag must not change out_spec');
 }
 
+// TEST1294: RULE11 - void-input cap with stdin source rejected
+function test1294_rule11VoidInputWithStdinRejected() {
+  const urn = CapUrn.fromString('cap:in="media:void";op=test;out="media:string"');
+  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const stdinSource = ArgSource.fromJSON({ stdin: 'media:string' });
+  cap.args = [new CapArg('media:string', true, [stdinSource])];
+  try {
+    validateCapArgs(cap);
+    assert(false, 'Should have thrown RULE11 for void input with stdin');
+  } catch (e) {
+    assert(e instanceof ValidationError, 'Should be ValidationError');
+    assert(e.message.includes('RULE11'), 'Should mention RULE11: ' + e.message);
+  }
+}
+
+// TEST1295: RULE11 - non-void-input cap without stdin source rejected
+function test1295_rule11NonVoidInputWithoutStdinRejected() {
+  const urn = CapUrn.fromString('cap:in="media:string";op=test;out="media:string"');
+  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const posSource = ArgSource.fromJSON({ cli_flag: '--name' });
+  cap.args = [new CapArg('media:string', true, [posSource])];
+  try {
+    validateCapArgs(cap);
+    assert(false, 'Should have thrown RULE11 for non-void input without stdin');
+  } catch (e) {
+    assert(e instanceof ValidationError, 'Should be ValidationError');
+    assert(e.message.includes('RULE11'), 'Should mention RULE11: ' + e.message);
+  }
+}
+
+// TEST1296: RULE11 - void-input cap with only cli_flag sources passes
+function test1296_rule11VoidInputCliFlagOnly() {
+  const urn = CapUrn.fromString('cap:in="media:void";op=test;out="media:string"');
+  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const flagSource = ArgSource.fromJSON({ cli_flag: '--name' });
+  cap.args = [new CapArg('media:string', true, [flagSource])];
+  // Should not throw
+  validateCapArgs(cap);
+}
+
+// TEST1297: RULE11 - non-void-input cap with stdin source passes
+function test1297_rule11NonVoidInputWithStdin() {
+  const urn = CapUrn.fromString('cap:in="media:string";op=test;out="media:string"');
+  const cap = new Cap(urn, 'Test', 'test-cmd');
+  const stdinSource = ArgSource.fromJSON({ stdin: 'media:string' });
+  cap.args = [new CapArg('media:string', true, [stdinSource])];
+  // Should not throw
+  validateCapArgs(cap);
+}
+
 // TEST567: N/A for JS (conforms_to_str/accepts_str not in JS CapUrn)
 
 // ============================================================================
 // cap_urn.rs: TEST639-TEST653 (Cap URN wildcard tests)
 // ============================================================================
 
-// Note: Rust allows missing in/out to default to "media:" wildcard.
-// JS currently requires in/out (throws MISSING_IN_SPEC/MISSING_OUT_SPEC).
-// The following tests cover the wildcard behavior that IS applicable to JS.
+// 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-642: N/A for JS (JS requires in/out, does not default to media: wildcard)
+// 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:');
+}
 
-// TEST643: cap:in=*;out=* treated as wildcards
+// 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:');
+}
+
+// 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:');
+}
+
+// TEST643: cap:in=*;out=* becomes media:
 function test643_explicitAsteriskIsWildcard() {
   const cap = CapUrn.fromString('cap:in=*;out=*');
-  assertEqual(cap.getInSpec(), '*', 'in=* should be stored as wildcard');
-  assertEqual(cap.getOutSpec(), '*', 'out=* should be stored as wildcard');
+  assertEqual(cap.getInSpec(), MEDIA_IDENTITY, 'in=* should normalize to media:');
+  assertEqual(cap.getOutSpec(), MEDIA_IDENTITY, 'out=* should normalize to media:');
 }
 
 // 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(), '*', 'Should have wildcard out');
+  assertEqual(cap.getOutSpec(), 'media:', 'Wildcard out should normalize to media:');
 }
 
 // TEST645: cap:in=*;out=media:text has wildcard in, specific out
 function test645_wildcardInSpecificOut() {
   const cap = CapUrn.fromString('cap:in=*;out=media:text');
-  assertEqual(cap.getInSpec(), '*', 'Should have wildcard in');
+  assertEqual(cap.getInSpec(), 'media:', 'Wildcard in should normalize to media:');
   assertEqual(cap.getOutSpec(), 'media:text', 'Should have specific out');
 }
 
-// TEST646: N/A for JS (JS allows in=foo since it just checks for media: or *)
-// TEST647: N/A for JS (JS allows out=bar since it just checks for media: or *)
+// TEST646: cap:in=foo fails (invalid media URN)
+function test646_invalidInSpecFails() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=foo;out=media:'),
+    ErrorCodes.INVALID_IN_SPEC,
+    'Invalid in spec should fail hard'
+  );
+}
+
+// TEST647: cap:in=media:;out=bar fails (invalid media URN)
+function test647_invalidOutSpecFails() {
+  assertThrows(
+    () => CapUrn.fromString('cap:in=media:;out=bar'),
+    ErrorCodes.INVALID_OUT_SPEC,
+    'Invalid out spec should fail hard'
+  );
+}
 
 // TEST648: Wildcard in/out match specific caps
 function test648_wildcardAcceptsSpecific() {
@@ -2687,7 +2776,7 @@ function test649_specificityScoring() {
 
 // TEST650: N/A for JS (JS requires in/out, cap:in;out;op=test would fail parsing)
 
-// TEST651: All identity forms with explicit wildcards produce the same CapUrn
+// TEST651: All identity forms produce the same CapUrn
 function test651_identityFormsEquivalent() {
   const forms = [
     'cap:in=*;out=*',
@@ -2707,7 +2796,7 @@ function test651_identityFormsEquivalent() {
 
 // TEST652: N/A for JS (CAP_IDENTITY constant not in JS)
 
-// TEST653: Identity (no extra tags) does not steal routes from specific handlers
+// 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";op=test;out="media:void"');
@@ -4217,11 +4306,11 @@ function testRenderer_buildStrandGraphData_nestedForEachThrows() {
   // must throw the same error to surface the issue rather than
   // render a malformed graph.
   const payload = {
-    source_spec: 'media:a;list;list',
+    source_spec: 'media:a;list',
     target_spec: 'media:a',
     steps: [
-      makeForEachStep('media:a;list;list'),
       makeForEachStep('media:a;list'),
+      makeForEachStep('media:a'),
       makeCapStep('cap:in="media:a";op=x;out="media:a"', 'x', 'media:a', 'media:a', false, false),
     ],
   };
@@ -5409,7 +5498,7 @@ async function runTests() {
   runTest('TEST308: model_path_urn', test308_modelPathUrn);
   runTest('TEST309: model_availability_and_path_are_distinct', test309_modelAvailabilityAndPathAreDistinct);
   runTest('TEST310: llm_generate_text_urn', test310_llmGenerateTextUrn);
-  runTest('TEST311: llm_generate_text_urn_specs', test311_llmGenerateTextUrnSpecs);
+  runTest('llm_generate_text_urn_specs', testLlmGenerateTextUrnSpecs);
   runTest('TEST312: all_urn_builders_produce_valid_urns', test312_allUrnBuildersProduceValidUrns);
 
   // JS-specific tests (no Rust number)
@@ -5449,41 +5538,41 @@ async function runTests() {
   runTest('TEST334: cartridge_repo_client_needs_sync', test334_cartridgeRepoClientNeedsSync);
   runTest('TEST335: cartridge_repo_server_client_integration', test335_cartridgeRepoServerClientIntegration);
 
-  // media_urn.rs: TEST546-TEST558 (MediaUrn predicates)
+  // media_urn.rs: TEST1312-TEST1315, TEST1298-TEST1302 (MediaUrn predicates)
   console.log('\n--- media_urn.rs (predicates) ---');
-  runTest('TEST546: is_image', test546_isImage);
-  runTest('TEST547: is_audio', test547_isAudio);
-  runTest('TEST548: is_video', test548_isVideo);
-  runTest('TEST549: is_numeric', test549_isNumeric);
-  runTest('TEST550: is_bool', test550_isBool);
-  runTest('TEST551: is_file_path', test551_isFilePath);
-  runTest('TEST552: is_file_path_array', test552_isFilePathArray);
-  runTest('TEST553: is_any_file_path', test553_isAnyFilePath);
-  console.log('  SKIP TEST554: N/A for JS (collection types removed from capdag)');
-  console.log('  SKIP TEST555: N/A for JS (with_tag/without_tag on MediaUrn)');
-  console.log('  SKIP TEST556: N/A for JS (image_media_urn_for_ext helper)');
-  console.log('  SKIP TEST557: N/A for JS (audio_media_urn_for_ext helper)');
-  runTest('TEST558: predicate_constant_consistency', test558_predicateConstantConsistency);
-
-  // cap_urn.rs: TEST559-TEST567 (CapUrn tier tests)
+  runTest('TEST1312: is_image', test1312_isImage);
+  runTest('TEST1313: is_audio', test1313_isAudio);
+  runTest('TEST1314: is_video', test1314_isVideo);
+  runTest('TEST1315: is_numeric', test1315_isNumeric);
+  runTest('TEST1298: is_bool', test1298_isBool);
+  runTest('TEST1299: is_file_path', test1299_isFilePath);
+  runTest('TEST1300: is_file_path_array', test1300_isFilePathArray);
+  runTest('TEST1301: is_any_file_path', test1301_isAnyFilePath);
+  runTest('TEST1302: predicate_constant_consistency', test1302_predicateConstantConsistency);
+
+  // cap_urn.rs: TEST1303-TEST1307 (CapUrn tier tests)
   console.log('\n--- cap_urn.rs (tier tests) ---');
-  runTest('TEST559: without_tag', test559_withoutTag);
-  runTest('TEST560: with_in_out_spec', test560_withInOutSpec);
-  console.log('  SKIP TEST561: N/A for JS (in_media_urn/out_media_urn)');
-  console.log('  SKIP TEST562: N/A for JS (canonical_option)');
-  runTest('TEST563: find_all_matches', test563_findAllMatches);
-  runTest('TEST564: are_compatible', test564_areCompatible);
-  console.log('  SKIP TEST565: N/A for JS (tags_to_string)');
-  runTest('TEST566: with_tag_ignores_in_out', test566_withTagIgnoresInOut);
-  console.log('  SKIP TEST567: N/A for JS (conforms_to_str/accepts_str)');
+  runTest('TEST1303: without_tag', test1303_withoutTag);
+  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('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);
+  runTest('TEST1297: rule11_non_void_input_with_stdin', test1297_rule11NonVoidInputWithStdin);
 
   // cap_urn.rs: TEST639-TEST653 (Cap URN wildcard tests)
   console.log('\n--- cap_urn.rs (wildcard tests) ---');
-  console.log('  SKIP TEST639-642: N/A for JS (implicit wildcard defaults)');
+  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('TEST645: wildcard_in_specific_out', test645_wildcardInSpecificOut);
-  console.log('  SKIP TEST646-647: N/A for JS (invalid spec validation differs)');
+  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)');
@@ -5628,7 +5717,7 @@ async function runTests() {
   runTest('RENDERER: buildStrand_standaloneCollect',          testRenderer_buildStrandGraphData_standaloneCollect);
   runTest('RENDERER: buildStrand_unclosedForEachBody',        testRenderer_buildStrandGraphData_unclosedForEachBody);
   runTest('RENDERER: buildStrand_nestedForEachThrows',        testRenderer_buildStrandGraphData_nestedForEachThrows);
-  runTest('RENDERER: collapseStrand_singleCapBody',           testRenderer_collapseStrand_singleCapBodyShowsCapTitleWithIterCollectMarker);
+  runTest('RENDERER: collapseStrand_singleCapBody',           testRenderer_collapseStrand_singleCapBodyKeepsCapOwnLabel);
   runTest('RENDERER: collapseStrand_unclosedForEachBody',     testRenderer_collapseStrand_unclosedForEachBodyCollapses);
   runTest('RENDERER: collapseStrand_standaloneCollect',       testRenderer_collapseStrand_standaloneCollectCollapses);
   runTest('RENDERER: collapseStrand_seqCapBeforeForeach',     testRenderer_collapseStrand_sequenceProducingCapBeforeForeach);