capns 0.50.11396 → 0.58.11575

package/RULES.md

@@ -70,6 +70,39 @@ Examples:
 | 11 | MISSING_OUT_SPEC | Cap URN missing required `out` tag |
 | 12 | INVALID_MEDIA_URN | Direction spec value is not a valid Media URN |
 
+## Validation Rules
+
+### XV5: No Redefinition of Registry Media Specs
+
+Inline media specs in a capability's `media_specs` table must not redefine media specs that already exist in the global registry or built-in specs.
+
+```javascript
+const { validateNoMediaSpecRedefinitionSync, MEDIA_STRING } = require('capns');
+
+// This will fail - MEDIA_STRING is a built-in spec
+const mediaSpecs = {
+  [MEDIA_STRING]: { media_type: 'text/plain', title: 'My String' }
+};
+const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+// result: { valid: false, error: 'XV5: ...', redefines: ['media:textable;form=scalar'] }
+
+// This is allowed - custom spec that doesn't exist
+const customSpecs = {
+  'media:my-custom-type': { media_type: 'application/json', title: 'My Type' }
+};
+const customResult = validateNoMediaSpecRedefinitionSync(customSpecs);
+// result: { valid: true }
+```
+
+For server-side validation with registry access, use the async version:
+```javascript
+const { validateNoMediaSpecRedefinition } = require('capns');
+
+const result = await validateNoMediaSpecRedefinition(mediaSpecs, {
+  registryLookup: async (urn) => await mediaStore.get(urn) !== null
+});
+```
+
 ## Cross-Language Compatibility
 
 This JavaScript implementation follows the same rules as:

package/capns.js

@@ -755,26 +755,28 @@ const MediaSpecErrorCodes = {
  * Well-known built-in media URN constants
  * These media URNs are implicitly available and do not need to be declared in mediaSpecs
  */
-const MEDIA_STRING = 'media:string;textable;scalar';
-const MEDIA_INTEGER = 'media:integer;textable;numeric;scalar';
-const MEDIA_NUMBER = 'media:number;textable;numeric;scalar';
-const MEDIA_BOOLEAN = 'media:boolean;textable;scalar';
-const MEDIA_OBJECT = 'media:object;textable;keyed';
-const MEDIA_STRING_ARRAY = 'media:string-array;textable;sequence';
-const MEDIA_INTEGER_ARRAY = 'media:integer-array;textable;numeric;sequence';
-const MEDIA_NUMBER_ARRAY = 'media:number-array;textable;numeric;sequence';
-const MEDIA_BOOLEAN_ARRAY = 'media:boolean-array;textable;sequence';
-const MEDIA_OBJECT_ARRAY = 'media:object-array;textable;keyed;sequence';
-const MEDIA_BINARY = 'media:raw;binary';
+const MEDIA_STRING = 'media:textable;form=scalar';
+const MEDIA_INTEGER = 'media:integer;textable;numeric;form=scalar';
+const MEDIA_NUMBER = 'media:textable;numeric;form=scalar';
+const MEDIA_BOOLEAN = 'media:bool;textable;form=scalar';
+const MEDIA_OBJECT = 'media:form=map;textable';
+const MEDIA_STRING_ARRAY = 'media:textable;form=list';
+const MEDIA_INTEGER_ARRAY = 'media:integer;textable;numeric;form=list';
+const MEDIA_NUMBER_ARRAY = 'media:textable;numeric;form=list';
+const MEDIA_BOOLEAN_ARRAY = 'media:bool;textable;form=list';
+const MEDIA_OBJECT_ARRAY = 'media:form=list;textable';
+const MEDIA_BINARY = 'media:bytes';
 const MEDIA_VOID = 'media:void';
 // Semantic content types
-const MEDIA_PNG = 'media:png;binary';
-const MEDIA_AUDIO = 'media:wav;audio;binary;';
-const MEDIA_VIDEO = 'media:video;binary';
-const MEDIA_TEXT = 'media:text;textable';
+const MEDIA_PNG = 'media:image;png;bytes';
+const MEDIA_AUDIO = 'media:wav;audio;bytes;';
+const MEDIA_VIDEO = 'media:video;bytes';
+// Semantic AI input types
+const MEDIA_AUDIO_SPEECH = 'media:audio;wav;bytes;speech';
+const MEDIA_IMAGE_THUMBNAIL = 'media:image;png;bytes;thumbnail';
 // Document types (PRIMARY naming - type IS the format)
-const MEDIA_PDF = 'media:pdf;binary';
-const MEDIA_EPUB = 'media:epub;binary';
+const MEDIA_PDF = 'media:pdf;bytes';
+const MEDIA_EPUB = 'media:epub;bytes';
 // Text format types (PRIMARY naming - type IS the format)
 const MEDIA_MD = 'media:md;textable';
 const MEDIA_TXT = 'media:txt;textable';
@@ -782,8 +784,16 @@ const MEDIA_RST = 'media:rst;textable';
 const MEDIA_LOG = 'media:log;textable';
 const MEDIA_HTML = 'media:html;textable';
 const MEDIA_XML = 'media:xml;textable';
-const MEDIA_JSON = 'media:json;textable;keyed';
-const MEDIA_YAML = 'media:yaml;textable;keyed';
+const MEDIA_JSON = 'media:json;textable;form=map';
+const MEDIA_JSON_SCHEMA = 'media:json;json-schema;textable;form=map';
+const MEDIA_YAML = 'media:yaml;textable;form=map';
+// Semantic input types
+const MEDIA_MODEL_SPEC = 'media:model-spec;textable;form=scalar';
+const MEDIA_MODEL_REPO = 'media:model-repo;textable;form=map';
+// Semantic output types
+const MEDIA_MODEL_DIM = 'media:model-dim;integer;textable;numeric;form=scalar';
+const MEDIA_DECISION = 'media:decision;bool;textable;form=scalar';
+const MEDIA_DECISION_ARRAY = 'media:decision;bool;textable;form=list';
 
 // =============================================================================
 // SCHEMA URL CONFIGURATION
@@ -851,7 +861,6 @@ const BUILTIN_SPECS = {
   [MEDIA_PNG]: 'image/png; profile=https://capns.org/schema/image',
   [MEDIA_AUDIO]: 'audio/wav; profile=https://capns.org/schema/audio',
   [MEDIA_VIDEO]: 'video/mp4; profile=https://capns.org/schema/video',
-  [MEDIA_TEXT]: 'text/plain; profile=https://capns.org/schema/text',
   // Document types (PRIMARY naming)
   [MEDIA_PDF]: 'application/pdf',
   [MEDIA_EPUB]: 'application/epub+zip',
@@ -867,7 +876,7 @@ const BUILTIN_SPECS = {
 };
 
 /**
- * Check if a media URN has a marker tag (e.g., binary, keyed, textable).
+ * Check if a media URN has a marker tag (e.g., bytes, json, textable).
  * Uses TaggedUrn parsing for proper tag detection.
  * @param {string} mediaUrn - The media URN
  * @param {string} tagName - The marker tag name to check
@@ -879,6 +888,20 @@ function hasMediaUrnTag(mediaUrn, tagName) {
   return parsed.getTag(tagName) !== undefined;
 }
 
+/**
+ * Check if a media URN has a tag with a specific value (e.g., form=map).
+ * Uses TaggedUrn parsing for proper tag detection.
+ * @param {string} mediaUrn - The media URN
+ * @param {string} tagName - The tag key to check
+ * @param {string} tagValue - The expected tag value
+ * @returns {boolean} True if the tag has the expected value
+ */
+function hasMediaUrnTagValue(mediaUrn, tagName, tagValue) {
+  if (!mediaUrn) return false;
+  const parsed = TaggedUrn.fromString(mediaUrn);
+  return parsed.getTag(tagName) === tagValue;
+}
+
 /**
  * Parsed MediaSpec structure
  *
@@ -996,23 +1019,63 @@ class MediaSpec {
   }
 
   /**
-   * Check if this media spec represents binary output.
-   * Returns true if the "binary" marker tag is present in the source media URN.
+   * Check if this media spec represents binary data.
+   * Returns true if the "bytes" marker tag is present in the source media URN.
    * @returns {boolean} True if binary
    */
   isBinary() {
     if (!this.mediaUrn) return false;
-    return hasMediaUrnTag(this.mediaUrn, 'binary');
+    return hasMediaUrnTag(this.mediaUrn, 'bytes');
+  }
+
+  /**
+   * Check if this media spec represents a map/object structure (form=map).
+   * This indicates a key-value structure, regardless of representation format.
+   * @returns {boolean} True if map
+   */
+  isMap() {
+    if (!this.mediaUrn) return false;
+    return hasMediaUrnTagValue(this.mediaUrn, 'form', 'map');
+  }
+
+  /**
+   * Check if this media spec represents a scalar value (form=scalar).
+   * @returns {boolean} True if scalar
+   */
+  isScalar() {
+    if (!this.mediaUrn) return false;
+    return hasMediaUrnTagValue(this.mediaUrn, 'form', 'scalar');
   }
 
   /**
-   * Check if this media spec represents JSON/keyed output.
-   * Returns true if the "keyed" marker tag is present in the source media URN.
-   * @returns {boolean} True if JSON/keyed
+   * Check if this media spec represents a list/array structure (form=list).
+   * @returns {boolean} True if list
+   */
+  isList() {
+    if (!this.mediaUrn) return false;
+    return hasMediaUrnTagValue(this.mediaUrn, 'form', 'list');
+  }
+
+  /**
+   * Check if this media spec represents structured data (map or list).
+   * Structured data can be serialized as JSON when transmitted as text.
+   * Note: This does NOT check for the explicit `json` tag - use isJSON() for that.
+   * @returns {boolean} True if structured (map or list)
+   */
+  isStructured() {
+    return this.isMap() || this.isList();
+  }
+
+  /**
+   * Check if this media spec represents JSON representation specifically.
+   * Returns true if the "json" marker tag is present in the source media URN.
+   * Note: This only checks for explicit JSON format marker.
+   * For checking if data is structured (map/list), use isStructured().
+   * @returns {boolean} True if JSON representation
    */
   isJSON() {
     if (!this.mediaUrn) return false;
-    return hasMediaUrnTag(this.mediaUrn, 'keyed');
+    return hasMediaUrnTag(this.mediaUrn, 'json');
   }
 
   /**
@@ -1138,6 +1201,88 @@ function isBuiltinMediaUrn(mediaUrn) {
   return BUILTIN_SPECS.hasOwnProperty(mediaUrn);
 }
 
+/**
+ * XV5: Validate that inline media_specs don't redefine built-in/registry specs.
+ *
+ * For capns-js (client-side), we check against BUILTIN_SPECS.
+ * Server-side validation (capns_dot_org) should check against the full registry.
+ *
+ * @param {Object} mediaSpecs - The inline media_specs object from a capability
+ * @param {Object} [options] - Validation options
+ * @param {Function} [options.registryLookup] - Optional async function to check registry (for server-side)
+ * @returns {Promise<{valid: boolean, error?: string, redefines?: string[]}>}
+ */
+async function validateNoMediaSpecRedefinition(mediaSpecs, options = {}) {
+  if (!mediaSpecs || typeof mediaSpecs !== 'object' || Object.keys(mediaSpecs).length === 0) {
+    return { valid: true };
+  }
+
+  const { registryLookup } = options;
+  const redefines = [];
+
+  for (const mediaUrn of Object.keys(mediaSpecs)) {
+    // Check against built-in specs first (always available)
+    if (isBuiltinMediaUrn(mediaUrn)) {
+      redefines.push(mediaUrn);
+      continue;
+    }
+
+    // If a registry lookup function is provided (server-side), check against it
+    if (registryLookup && typeof registryLookup === 'function') {
+      try {
+        const existsInRegistry = await registryLookup(mediaUrn);
+        if (existsInRegistry) {
+          redefines.push(mediaUrn);
+        }
+      } catch (err) {
+        // Network/registry unavailable - log warning and allow (graceful degradation)
+        console.warn(`[WARN] XV5: Could not verify inline spec '${mediaUrn}' against registry: ${err.message}. Allowing operation in offline mode.`);
+      }
+    }
+  }
+
+  if (redefines.length > 0) {
+    return {
+      valid: false,
+      error: `XV5: Inline media specs redefine existing registry specs: ${redefines.join(', ')}`,
+      redefines
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * XV5: Synchronous version for checking against built-in specs only.
+ * Use this for client-side validation where registry lookup isn't available.
+ *
+ * @param {Object} mediaSpecs - The inline media_specs object from a capability
+ * @returns {{valid: boolean, error?: string, redefines?: string[]}}
+ */
+function validateNoMediaSpecRedefinitionSync(mediaSpecs) {
+  if (!mediaSpecs || typeof mediaSpecs !== 'object' || Object.keys(mediaSpecs).length === 0) {
+    return { valid: true };
+  }
+
+  const redefines = [];
+
+  for (const mediaUrn of Object.keys(mediaSpecs)) {
+    if (isBuiltinMediaUrn(mediaUrn)) {
+      redefines.push(mediaUrn);
+    }
+  }
+
+  if (redefines.length > 0) {
+    return {
+      valid: false,
+      error: `XV5: Inline media specs redefine existing built-in specs: ${redefines.join(', ')}`,
+      redefines
+    };
+  }
+
+  return { valid: true };
+}
+
 /**
  * Check if a CapUrn represents binary output.
  * Throws error if the output spec cannot be resolved - no fallbacks.
@@ -1153,10 +1298,11 @@ function isBinaryCapUrn(capUrn, mediaSpecs = {}) {
 
 /**
  * Check if a CapUrn represents JSON output.
+ * Note: This checks for explicit JSON format marker only.
  * Throws error if the output spec cannot be resolved - no fallbacks.
  * @param {CapUrn} capUrn - The cap URN
  * @param {Object} mediaSpecs - Optional mediaSpecs lookup table
- * @returns {boolean} True if JSON
+ * @returns {boolean} True if explicit JSON tag present
  * @throws {MediaSpecError} If 'out' tag is missing or spec ID cannot be resolved
  */
 function isJSONCapUrn(capUrn, mediaSpecs = {}) {
@@ -1164,6 +1310,20 @@ function isJSONCapUrn(capUrn, mediaSpecs = {}) {
   return mediaSpec.isJSON();
 }
 
+/**
+ * Check if a CapUrn represents structured output (map or list).
+ * Structured data can be serialized as JSON when transmitted as text.
+ * Throws error if the output spec cannot be resolved - no fallbacks.
+ * @param {CapUrn} capUrn - The cap URN
+ * @param {Object} mediaSpecs - Optional mediaSpecs lookup table
+ * @returns {boolean} True if structured (map or list)
+ * @throws {MediaSpecError} If 'out' tag is missing or spec ID cannot be resolved
+ */
+function isStructuredCapUrn(capUrn, mediaSpecs = {}) {
+  const mediaSpec = MediaSpec.fromCapUrn(capUrn, mediaSpecs);
+  return mediaSpec.isStructured();
+}
+
 /**
  * Registration attribution - who registered a capability and when
  */
@@ -1758,7 +1918,7 @@ class ValidationError extends Error {
           return `Cap '${capUrn}' argument '${details.argumentName}' expects media_spec '${details.expectedMediaSpec}' but ${errors} for value: ${JSON.stringify(details.actualValue)}`;
         }
         return `Cap '${capUrn}' argument '${details.argumentName}' expects type '${details.expectedType}' but received '${details.actualType}' with value: ${JSON.stringify(details.actualValue)}`;
-      case 'ArgumentValidationFailed':
+      case 'MediaValidationFailed':
         return `Cap '${capUrn}' argument '${details.argumentName}' failed validation rule '${details.validationRule}' with value: ${JSON.stringify(details.actualValue)}`;
       case 'MediaSpecValidationFailed':
         return `Cap '${capUrn}' argument '${details.argumentName}' failed media spec '${details.mediaUrn}' validation rule '${details.validationRule}' with value: ${JSON.stringify(details.actualValue)}`;
@@ -3346,8 +3506,11 @@ module.exports = {
   MediaSpecErrorCodes,
   isBinaryCapUrn,
   isJSONCapUrn,
+  isStructuredCapUrn,
   resolveMediaUrn,
   isBuiltinMediaUrn,
+  validateNoMediaSpecRedefinition,
+  validateNoMediaSpecRedefinitionSync,
   BUILTIN_SPECS,
   getSchemaBaseURL,
   getProfileURL,
@@ -3366,7 +3529,8 @@ module.exports = {
   MEDIA_PNG,
   MEDIA_AUDIO,
   MEDIA_VIDEO,
-  MEDIA_TEXT,
+  MEDIA_AUDIO_SPEECH,
+  MEDIA_IMAGE_THUMBNAIL,
   // Document types (PRIMARY naming)
   MEDIA_PDF,
   MEDIA_EPUB,
@@ -3378,7 +3542,13 @@ module.exports = {
   MEDIA_HTML,
   MEDIA_XML,
   MEDIA_JSON,
+  MEDIA_JSON_SCHEMA,
   MEDIA_YAML,
+  MEDIA_MODEL_SPEC,
+  MEDIA_MODEL_REPO,
+  MEDIA_MODEL_DIM,
+  MEDIA_DECISION,
+  MEDIA_DECISION_ARRAY,
   CapMatrixError,
   CapMatrix,
   BestCapSetMatch,

package/capns.test.js

@@ -33,7 +33,9 @@ const {
   CapGraph,
   // StdinSource
   StdinSource,
-  StdinSourceKind
+  StdinSourceKind,
+  // XV5 validation
+  validateNoMediaSpecRedefinitionSync
 } = require('./capns.js');
 
 // Test assertion utility
@@ -68,13 +70,14 @@ function assertThrows(fn, expectedErrorCode, message) {
  */
 function testUrn(tags) {
   if (!tags || tags === '') {
-    return 'cap:in="media:void";out="media:object"';
+    return 'cap:in="media:void";out="media:form=map"';
   }
-  return 'cap:in="media:void";out="media:object";' + tags;
+  return 'cap:in="media:void";out="media:form=map";' + tags;
 }
 
 // Test suite - defined at the end of file
 
+// TEST001: Test that cap URN is created with tags parsed correctly and direction specs accessible
 function testCapUrnCreation() {
   console.log('Testing Cap URN creation...');
 
@@ -83,16 +86,17 @@ function testCapUrnCreation() {
   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');
-  assertEqual(cap.getOutSpec(), 'media:object', 'Should get outSpec');
+  assertEqual(cap.getOutSpec(), 'media:form=map', 'Should get outSpec');
 
   console.log('  ✓ Cap URN creation');
 }
 
+// TEST002: Test that tag keys and values are normalized to lowercase for case-insensitive comparison
 function testCaseInsensitive() {
   console.log('Testing case insensitive behavior...');
 
   // Test that different casing produces the same URN
-  const cap1 = CapUrn.fromString('cap:IN="media:void";OUT="media:object";OP=Generate;EXT=PDF;Target=Thumbnail');
+  const cap1 = CapUrn.fromString('cap:IN="media:void";OUT="media:form=map";OP=Generate;EXT=PDF;Target=Thumbnail');
   const cap2 = CapUrn.fromString(testUrn('op=generate;ext=pdf;target=thumbnail'));
 
   // Both should be normalized to lowercase
@@ -114,7 +118,7 @@ function testCaseInsensitive() {
 
   // Case-insensitive in/out lookup
   assertEqual(cap1.getTag('IN'), 'media:void', 'Should lookup in with case-insensitive key');
-  assertEqual(cap1.getTag('OUT'), 'media:object', 'Should lookup out with case-insensitive key');
+  assertEqual(cap1.getTag('OUT'), 'media:form=map', 'Should lookup out with case-insensitive key');
 
   // Matching should work case-insensitively
   assert(cap1.matches(cap2), 'Should match case-insensitively');
@@ -123,6 +127,7 @@ function testCaseInsensitive() {
   console.log('  ✓ Case insensitive behavior');
 }
 
+// TEST003: Test that URN without cap prefix is rejected with MISSING_CAP_PREFIX error
 function testCapPrefixRequired() {
   console.log('Testing cap: prefix requirement...');
 
@@ -140,6 +145,7 @@ function testCapPrefixRequired() {
   console.log('  ✓ Cap prefix requirement');
 }
 
+// TEST004: Test that URNs with and without trailing semicolon are equivalent
 function testTrailingSemicolonEquivalence() {
   console.log('Testing trailing semicolon equivalence...');
 
@@ -160,18 +166,20 @@ function testTrailingSemicolonEquivalence() {
   console.log('  ✓ Trailing semicolon equivalence');
 }
 
+// TEST005: Test that toString produces canonical form with alphabetically sorted tags
 function testCanonicalStringFormat() {
   console.log('Testing canonical string format...');
 
   const cap = CapUrn.fromString(testUrn('op=generate;target=thumbnail;ext=pdf'));
   // Should be sorted alphabetically and have no trailing semicolon in canonical form
   // in/out are included in alphabetical order: 'ext' < 'in' < 'op' < 'out' < 'target'
-  // Colons don't need quoting - media:void and media:object are valid unquoted values
-  assertEqual(cap.toString(), 'cap:ext=pdf;in=media:void;op=generate;out=media:object;target=thumbnail', 'Should be alphabetically sorted');
+  // Values with '=' need quoting - media:form=map requires quotes
+  assertEqual(cap.toString(), 'cap:ext=pdf;in=media:void;op=generate;out="media:form=map";target=thumbnail', 'Should be alphabetically sorted');
 
   console.log('  ✓ Canonical string format');
 }
 
+// TEST006: Test that cap matches request with exact tags, subset tags, and wildcards
 function testTagMatching() {
   console.log('Testing tag matching...');
 
@@ -200,6 +208,7 @@ function testTagMatching() {
   console.log('  ✓ Tag matching');
 }
 
+// TEST007: Test that missing tags are treated as wildcards for matching
 function testMissingTagHandling() {
   console.log('Testing missing tag handling...');
 
@@ -217,6 +226,7 @@ function testMissingTagHandling() {
   console.log('  ✓ Missing tag handling');
 }
 
+// TEST008: Test that specificity counts non-wildcard tags including in and out
 function testSpecificity() {
   console.log('Testing specificity...');
 
@@ -239,6 +249,7 @@ function testSpecificity() {
   console.log('  ✓ Specificity');
 }
 
+// TEST009: Test that compatibility checks if caps can handle same requests
 function testCompatibility() {
   console.log('Testing compatibility...');
 
@@ -262,6 +273,7 @@ function testCompatibility() {
   console.log('  ✓ Compatibility');
 }
 
+// TEST010: Test that CapUrnBuilder creates valid URN with tags and direction specs
 function testBuilder() {
   console.log('Testing builder...');
 
@@ -295,6 +307,7 @@ function testBuilder() {
   console.log('  ✓ Builder');
 }
 
+// TEST011: Test convenience methods withTag, withoutTag, withInSpec, withOutSpec, merge, subset, withWildcardTag
 function testConvenienceMethods() {
   console.log('Testing convenience methods...');
 
@@ -305,7 +318,7 @@ function testConvenienceMethods() {
   assertEqual(modified.getTag('op'), 'generate', 'Should preserve original tag');
   assertEqual(modified.getTag('ext'), 'pdf', 'Should add new tag');
   assertEqual(modified.getInSpec(), 'media:void', 'Should preserve inSpec');
-  assertEqual(modified.getOutSpec(), 'media:object', 'Should preserve outSpec');
+  assertEqual(modified.getOutSpec(), 'media:form=map', 'Should preserve outSpec');
 
   // Test withTag silently ignores in/out
   const modified2 = original.withTag('in', 'media:string');
@@ -357,6 +370,7 @@ function testConvenienceMethods() {
   console.log('  ✓ Convenience methods');
 }
 
+// TEST012: Test that CapMatcher finds best and all matches from cap list
 function testCapMatcher() {
   console.log('Testing CapMatcher...');
 
@@ -371,7 +385,8 @@ function testCapMatcher() {
 
   // Most specific cap that can handle the request (ext=pdf is more specific)
   // Canonical order is alphabetical: ext, in, op, out
-  assertEqual(best.toString(), 'cap:ext=pdf;in=media:void;op=generate;out=media:object', 'Should find most specific match');
+  // Note: media:form=map needs quotes because it contains '='
+  assertEqual(best.toString(), 'cap:ext=pdf;in=media:void;op=generate;out="media:form=map"', 'Should find most specific match');
 
   // Test findAllMatches - now only 2 match because first has wildcard in/out
   const matches = CapMatcher.findAllMatches(caps, request);
@@ -382,6 +397,7 @@ function testCapMatcher() {
   console.log('  ✓ CapMatcher');
 }
 
+// TEST013: Test that cap URN serializes to and deserializes from JSON
 function testJSONSerialization() {
   console.log('Testing JSON serialization...');
 
@@ -392,11 +408,12 @@ function testJSONSerialization() {
 
   assert(original.equals(restored), 'Should serialize/deserialize correctly');
   assertEqual(restored.getInSpec(), 'media:void', 'Should preserve inSpec');
-  assertEqual(restored.getOutSpec(), 'media:object', 'Should preserve outSpec');
+  assertEqual(restored.getOutSpec(), 'media:form=map', 'Should preserve outSpec');
 
   console.log('  ✓ JSON serialization');
 }
 
+// TEST014: Test that empty cap URN without in/out fails, minimal URN with just in/out succeeds
 function testEmptyCapUrn() {
   console.log('Testing empty cap URN now fails (in/out required)...');
 
@@ -418,7 +435,7 @@ function testEmptyCapUrn() {
   const minimal = CapUrn.fromString(testUrn(''));
   assertEqual(Object.keys(minimal.tags).length, 0, 'Should have no other tags');
   assertEqual(minimal.getInSpec(), 'media:void', 'Should have inSpec');
-  assertEqual(minimal.getOutSpec(), 'media:object', 'Should have outSpec');
+  assertEqual(minimal.getOutSpec(), 'media:form=map', 'Should have outSpec');
 
   // For "match anything" behavior, use wildcards
   const wildcard = CapUrn.fromString('cap:in=*;out=*');
@@ -429,6 +446,7 @@ function testEmptyCapUrn() {
   console.log('  ✓ Empty cap URN now fails (in/out required)');
 }
 
+// TEST015: Test that URN supports forward slashes and colons in tag values
 function testExtendedCharacterSupport() {
   console.log('Testing extended character support...');
 
@@ -440,6 +458,7 @@ function testExtendedCharacterSupport() {
   console.log('  ✓ Extended character support');
 }
 
+// TEST016: Test that wildcard is rejected in keys but accepted in values
 function testWildcardRestrictions() {
   console.log('Testing wildcard restrictions...');
 
@@ -462,6 +481,7 @@ function testWildcardRestrictions() {
   console.log('  ✓ Wildcard restrictions');
 }
 
+// TEST017: Test that duplicate keys in URN are rejected with DUPLICATE_KEY error
 function testDuplicateKeyRejection() {
   console.log('Testing duplicate key rejection...');
 
@@ -475,6 +495,7 @@ function testDuplicateKeyRejection() {
   console.log('  ✓ Duplicate key rejection');
 }
 
+// TEST018: Test that pure numeric keys are rejected but mixed alphanumeric keys are allowed
 function testNumericKeyRestriction() {
   console.log('Testing numeric key restriction...');
 
@@ -503,6 +524,7 @@ function testNumericKeyRestriction() {
 // NEW FORMAT TESTS - Spec ID Resolution and MediaSpec
 // ============================================================================
 
+// TEST057: Test MediaSpec parses canonical format without content-type prefix
 function testMediaSpecCanonicalFormat() {
   console.log('Testing MediaSpec canonical format...');
 
@@ -523,6 +545,7 @@ function testMediaSpecCanonicalFormat() {
   console.log('  ✓ MediaSpec canonical format');
 }
 
+// TEST058: Test MediaSpec fails hard on legacy content-type prefix format
 function testMediaSpecLegacyFormatRejection() {
   console.log('Testing legacy format rejection...');
 
@@ -542,6 +565,7 @@ function testMediaSpecLegacyFormatRejection() {
   console.log('  ✓ Legacy format rejection');
 }
 
+// TEST059: Test built-in media URNs are recognized by isBuiltinMediaUrn
 function testBuiltinSpecIds() {
   console.log('Testing built-in spec IDs...');
 
@@ -559,6 +583,7 @@ function testBuiltinSpecIds() {
   console.log('  ✓ Built-in spec IDs');
 }
 
+// TEST060: Test resolveMediaUrn resolves built-in media URNs to MediaSpec
 function testSpecIdResolution() {
   console.log('Testing spec ID resolution...');
 
@@ -581,6 +606,7 @@ function testSpecIdResolution() {
   console.log('  ✓ Spec ID resolution');
 }
 
+// TEST061: Test resolveMediaUrn resolves custom media URNs from mediaSpecs table
 function testMediaUrnResolutionWithMediaSpecs() {
   console.log('Testing media URN resolution with custom mediaSpecs...');
 
@@ -612,6 +638,7 @@ function testMediaUrnResolutionWithMediaSpecs() {
   console.log('  ✓ Media URN resolution with custom mediaSpecs');
 }
 
+// TEST062: Test resolveMediaUrn fails hard on unresolvable media URN
 function testMediaUrnResolutionFailHard() {
   console.log('Testing media URN resolution fail hard...');
 
@@ -631,6 +658,7 @@ function testMediaUrnResolutionFailHard() {
   console.log('  ✓ Media URN resolution fail hard');
 }
 
+// TEST063: Test metadata is propagated from object form media spec definition
 function testMetadataPropagation() {
   console.log('Testing metadata propagation...');
 
@@ -661,6 +689,7 @@ function testMetadataPropagation() {
   console.log('  ✓ Metadata propagation from object definition');
 }
 
+// TEST064: Test string form media spec definition has no metadata
 function testMetadataForStringDef() {
   console.log('Testing metadata for string definition...');
 
@@ -675,6 +704,7 @@ function testMetadataForStringDef() {
   console.log('  ✓ String form has no metadata');
 }
 
+// TEST065: Test built-in media URNs have no metadata
 function testMetadataForBuiltin() {
   console.log('Testing metadata for built-in...');
 
@@ -685,6 +715,7 @@ function testMetadataForBuiltin() {
   console.log('  ✓ Built-in has no metadata');
 }
 
+// TEST066: Test metadata and validation coexist in media spec definition
 function testMetadataWithValidation() {
   console.log('Testing metadata with validation...');
 
@@ -720,6 +751,7 @@ function testMetadataWithValidation() {
   console.log('  ✓ Metadata coexists with validation');
 }
 
+// TEST108: Test Cap with mediaSpecs resolves custom and built-in media URNs
 function testCapWithMediaSpecs() {
   console.log('Testing Cap with mediaSpecs...');
 
@@ -754,6 +786,7 @@ function testCapWithMediaSpecs() {
   console.log('  ✓ Cap with mediaSpecs');
 }
 
+// TEST109: Test Cap JSON serialization includes mediaSpecs and direction specs
 function testCapJSONSerialization() {
   console.log('Testing Cap JSON serialization with mediaSpecs...');
 
@@ -774,18 +807,19 @@ function testCapJSONSerialization() {
   assertEqual(json.media_specs['media:custom'], 'text/plain; profile=https://example.com', 'Should serialize mediaSpecs');
   // URN tags should include in and out
   assertEqual(json.urn.tags['in'], 'media:void', 'Should serialize inSpec in tags');
-  assertEqual(json.urn.tags['out'], 'media:object', 'Should serialize outSpec in tags');
+  assertEqual(json.urn.tags['out'], 'media:form=map', 'Should serialize outSpec in tags');
 
   // Deserialize from JSON
   const restored = Cap.fromJSON(json);
   assert(restored.mediaSpecs !== undefined, 'Should restore mediaSpecs');
   assertEqual(restored.mediaSpecs['media:custom'], 'text/plain; profile=https://example.com', 'Should restore mediaSpecs content');
   assertEqual(restored.urn.getInSpec(), 'media:void', 'Should restore inSpec');
-  assertEqual(restored.urn.getOutSpec(), 'media:object', 'Should restore outSpec');
+  assertEqual(restored.urn.getOutSpec(), 'media:form=map', 'Should restore outSpec');
 
   console.log('  ✓ Cap JSON serialization with mediaSpecs');
 }
 
+// TEST019: Test op tag is used instead of deprecated action tag
 function testOpTagRename() {
   console.log('Testing op tag (renamed from action)...');
 
@@ -812,6 +846,7 @@ function testOpTagRename() {
 // All implementations (Rust, Go, JS, ObjC) must pass these identically
 // ============================================================================
 
+// TEST020: Test matching semantics - exact match including in/out
 function testMatchingSemantics_Test1_ExactMatch() {
   console.log('Testing Matching Semantics Test 1: Exact match...');
   // Test 1: Exact match (including in/out)
@@ -824,6 +859,7 @@ function testMatchingSemantics_Test1_ExactMatch() {
   console.log('  ✓ Test 1: Exact match');
 }
 
+// TEST021: Test matching semantics - cap missing tag treated as implicit wildcard
 function testMatchingSemantics_Test2_CapMissingTag() {
   console.log('Testing Matching Semantics Test 2: Cap missing tag...');
   // Test 2: Cap missing tag (implicit wildcard for other tags, not in/out)
@@ -836,6 +872,7 @@ function testMatchingSemantics_Test2_CapMissingTag() {
   console.log('  ✓ Test 2: Cap missing tag');
 }
 
+// TEST022: Test matching semantics - cap with extra tag matches request
 function testMatchingSemantics_Test3_CapHasExtraTag() {
   console.log('Testing Matching Semantics Test 3: Cap has extra tag...');
   // Test 3: Cap has extra tag
@@ -848,6 +885,7 @@ function testMatchingSemantics_Test3_CapHasExtraTag() {
   console.log('  ✓ Test 3: Cap has extra tag');
 }
 
+// TEST023: Test matching semantics - request with wildcard matches specific cap
 function testMatchingSemantics_Test4_RequestHasWildcard() {
   console.log('Testing Matching Semantics Test 4: Request has wildcard...');
   // Test 4: Request has wildcard
@@ -860,6 +898,7 @@ function testMatchingSemantics_Test4_RequestHasWildcard() {
   console.log('  ✓ Test 4: Request has wildcard');
 }
 
+// TEST024: Test matching semantics - cap with wildcard matches specific request
 function testMatchingSemantics_Test5_CapHasWildcard() {
   console.log('Testing Matching Semantics Test 5: Cap has wildcard...');
   // Test 5: Cap has wildcard
@@ -872,6 +911,7 @@ function testMatchingSemantics_Test5_CapHasWildcard() {
   console.log('  ✓ Test 5: Cap has wildcard');
 }
 
+// TEST025: Test matching semantics - value mismatch does not match
 function testMatchingSemantics_Test6_ValueMismatch() {
   console.log('Testing Matching Semantics Test 6: Value mismatch...');
   // Test 6: Value mismatch
@@ -884,6 +924,7 @@ function testMatchingSemantics_Test6_ValueMismatch() {
   console.log('  ✓ Test 6: Value mismatch');
 }
 
+// TEST026: Test matching semantics - fallback pattern with missing tag as implicit wildcard
 function testMatchingSemantics_Test7_FallbackPattern() {
   console.log('Testing Matching Semantics Test 7: Fallback pattern...');
   // Test 7: Fallback pattern
@@ -896,6 +937,7 @@ function testMatchingSemantics_Test7_FallbackPattern() {
   console.log('  ✓ Test 7: Fallback pattern');
 }
 
+// TEST027: Test matching semantics - wildcard cap with in=* out=* matches anything
 function testMatchingSemantics_Test8_WildcardCapMatchesAnything() {
   console.log('Testing Matching Semantics Test 8: Wildcard cap matches anything...');
   // Test 8: Wildcard cap matches anything (replaces empty cap test)
@@ -908,6 +950,7 @@ function testMatchingSemantics_Test8_WildcardCapMatchesAnything() {
   console.log('  ✓ Test 8: Wildcard cap matches anything');
 }
 
+// TEST028: Test matching semantics - cross-dimension independence for other tags
 function testMatchingSemantics_Test9_CrossDimensionIndependence() {
   console.log('Testing Matching Semantics Test 9: Cross-dimension independence...');
   // Test 9: Cross-dimension independence (for other tags, not in/out)
@@ -920,6 +963,7 @@ function testMatchingSemantics_Test9_CrossDimensionIndependence() {
   console.log('  ✓ Test 9: Cross-dimension independence');
 }
 
+// TEST029: Test matching semantics - direction mismatch in/out does not match
 function testMatchingSemantics_Test10_DirectionMismatch() {
   console.log('Testing Matching Semantics Test 10: Direction mismatch...');
   // Test 10: Direction mismatch (in/out must match)
@@ -964,6 +1008,7 @@ function makeCap(urnString, title) {
   return new Cap(capUrn, title, 'test', title);
 }
 
+// TEST117: Test CapCube finds more specific cap across registries
 function testCapCubeMoreSpecificWins() {
   console.log('Testing CapCube: More specific wins...');
 
@@ -1002,6 +1047,7 @@ function testCapCubeMoreSpecificWins() {
   console.log('  ✓ More specific wins');
 }
 
+// TEST118: Test CapCube tie-breaking prefers first registry in order
 function testCapCubeTieGoesToFirst() {
   console.log('Testing CapCube: Tie goes to first...');
 
@@ -1029,6 +1075,7 @@ function testCapCubeTieGoesToFirst() {
   console.log('  ✓ Tie goes to first');
 }
 
+// TEST119: Test CapCube polls all registries to find best match
 function testCapCubePollsAll() {
   console.log('Testing CapCube: Polls all registries...');
 
@@ -1063,6 +1110,7 @@ function testCapCubePollsAll() {
   console.log('  ✓ Polls all registries');
 }
 
+// TEST120: Test CapCube returns error when no cap matches request
 function testCapCubeNoMatch() {
   console.log('Testing CapCube: No match error...');
 
@@ -1081,6 +1129,7 @@ function testCapCubeNoMatch() {
   console.log('  ✓ No match error');
 }
 
+// TEST121: Test CapCube fallback scenario where generic cap handles unknown file types
 function testCapCubeFallbackScenario() {
   console.log('Testing CapCube: Fallback scenario...');
 
@@ -1125,6 +1174,7 @@ function testCapCubeFallbackScenario() {
   console.log('  ✓ Fallback scenario');
 }
 
+// TEST122: Test CapCube can method returns execution info and canHandle checks capability
 function testCapCubeCanMethod() {
   console.log('Testing CapCube: can() method...');
 
@@ -1149,6 +1199,7 @@ function testCapCubeCanMethod() {
   console.log('  ✓ can() method');
 }
 
+// TEST123: Test CapCube registry management add, get, remove operations
 function testCapCubeRegistryManagement() {
   console.log('Testing CapCube: Registry management...');
 
@@ -1190,6 +1241,7 @@ function makeGraphCap(inUrn, outUrn, title) {
   return new Cap(capUrn, title, 'convert', title);
 }
 
+// TEST124: Test CapGraph basic construction builds nodes and edges from caps
 function testCapGraphBasicConstruction() {
   console.log('Testing CapGraph: Basic construction...');
 
@@ -1223,6 +1275,7 @@ function testCapGraphBasicConstruction() {
   console.log('  ✓ Basic construction');
 }
 
+// TEST125: Test CapGraph getOutgoing and getIncoming return correct edges for media URN
 function testCapGraphOutgoingIncoming() {
   console.log('Testing CapGraph: Outgoing and incoming edges...');
 
@@ -1255,6 +1308,7 @@ function testCapGraphOutgoingIncoming() {
   console.log('  ✓ Outgoing and incoming edges');
 }
 
+// TEST126: Test CapGraph canConvert checks direct and transitive conversion paths
 function testCapGraphCanConvert() {
   console.log('Testing CapGraph: Can convert...');
 
@@ -1289,6 +1343,7 @@ function testCapGraphCanConvert() {
   console.log('  ✓ Can convert');
 }
 
+// TEST127: Test CapGraph findPath returns shortest path between media URNs
 function testCapGraphFindPath() {
   console.log('Testing CapGraph: Find path...');
 
@@ -1330,6 +1385,7 @@ function testCapGraphFindPath() {
   console.log('  ✓ Find path');
 }
 
+// TEST128: Test CapGraph findAllPaths returns all paths sorted by length
 function testCapGraphFindAllPaths() {
   console.log('Testing CapGraph: Find all paths...');
 
@@ -1361,6 +1417,7 @@ function testCapGraphFindAllPaths() {
   console.log('  ✓ Find all paths');
 }
 
+// TEST129: Test CapGraph getDirectEdges returns edges sorted by specificity
 function testCapGraphGetDirectEdges() {
   console.log('Testing CapGraph: Get direct edges...');
 
@@ -1397,6 +1454,7 @@ function testCapGraphGetDirectEdges() {
   console.log('  ✓ Get direct edges');
 }
 
+// TEST130: Test CapGraph stats returns node count, edge count, input/output URN counts
 function testCapGraphStats() {
   console.log('Testing CapGraph: Stats...');
 
@@ -1432,6 +1490,7 @@ function testCapGraphStats() {
   console.log('  ✓ Stats');
 }
 
+// TEST131: Test CapGraph with CapCube builds graph from multiple registries
 function testCapGraphWithCapCube() {
   console.log('Testing CapGraph: With CapCube...');
 
@@ -1473,6 +1532,7 @@ function testCapGraphWithCapCube() {
 // StdinSource Tests
 // ============================================================================
 
+// TEST156: Test creating StdinSource Data variant with byte vector
 function testStdinSourceFromData() {
   console.log('Testing StdinSource: From data...');
 
@@ -1488,13 +1548,14 @@ function testStdinSourceFromData() {
   console.log('  ✓ From data');
 }
 
+// TEST157: Test creating StdinSource FileReference variant with all required fields
 function testStdinSourceFromFileReference() {
   console.log('Testing StdinSource: From file reference...');
 
   const trackedFileId = 'tracked-file-123';
   const originalPath = '/path/to/original.pdf';
   const securityBookmark = new Uint8Array([0x62, 0x6f, 0x6f, 0x6b]); // "book"
-  const mediaUrn = 'media:pdf;binary';
+  const mediaUrn = 'media:pdf;bytes';
 
   const source = StdinSource.fromFileReference(trackedFileId, originalPath, securityBookmark, mediaUrn);
 
@@ -1510,6 +1571,7 @@ function testStdinSourceFromFileReference() {
   console.log('  ✓ From file reference');
 }
 
+// TEST158: Test StdinSource Data with empty vector stores and retrieves correctly
 function testStdinSourceWithEmptyData() {
   console.log('Testing StdinSource: With empty data...');
 
@@ -1523,6 +1585,7 @@ function testStdinSourceWithEmptyData() {
   console.log('  ✓ With empty data');
 }
 
+// TEST030: Test StdinSource with null data creates valid Data source
 function testStdinSourceWithNullData() {
   console.log('Testing StdinSource: With null data...');
 
@@ -1535,6 +1598,7 @@ function testStdinSourceWithNullData() {
   console.log('  ✓ With null data');
 }
 
+// TEST159: Test StdinSource Data with binary content like PNG header bytes
 function testStdinSourceWithBinaryContent() {
   console.log('Testing StdinSource: With binary content...');
 
@@ -1551,6 +1615,7 @@ function testStdinSourceWithBinaryContent() {
   console.log('  ✓ With binary content');
 }
 
+// TEST031: Test StdinSourceKind constants are defined and distinct
 function testStdinSourceKindConstants() {
   console.log('Testing StdinSource: Kind constants...');
 
@@ -1561,6 +1626,7 @@ function testStdinSourceKindConstants() {
   console.log('  ✓ Kind constants');
 }
 
+// TEST032: Test StdinSource Data is passed correctly to executeCap
 function testStdinSourcePassedToExecuteCap() {
   console.log('Testing StdinSource: Passed to executeCap...');
 
@@ -1605,6 +1671,7 @@ function testStdinSourcePassedToExecuteCap() {
   });
 }
 
+// TEST033: Test StdinSource FileReference is passed correctly to executeCap
 function testStdinSourceFileReferencePassedToExecuteCap() {
   console.log('Testing StdinSource: File reference passed to executeCap...');
 
@@ -1636,7 +1703,7 @@ function testStdinSourceFileReferencePassedToExecuteCap() {
     'tracked-123',
     '/path/to/file.pdf',
     new Uint8Array([0x42, 0x4f, 0x4f, 0x4b]),
-    'media:pdf;binary'
+    'media:pdf;bytes'
   );
 
   const { compositeHost } = cube.can('cap:in="media:void";op=test;out="media:string"');
@@ -1652,11 +1719,76 @@ function testStdinSourceFileReferencePassedToExecuteCap() {
     assert(receivedSource.isFileReference(), 'Should receive file reference source');
     assertEqual(receivedSource.trackedFileId, 'tracked-123', 'Should have correct trackedFileId');
     assertEqual(receivedSource.originalPath, '/path/to/file.pdf', 'Should have correct originalPath');
-    assertEqual(receivedSource.mediaUrn, 'media:pdf;binary', 'Should have correct mediaUrn');
+    assertEqual(receivedSource.mediaUrn, 'media:pdf;bytes', 'Should have correct mediaUrn');
     console.log('  ✓ File reference passed to executeCap');
   });
 }
 
+// ============================================================================
+// XV5 VALIDATION TESTS
+// TEST054-056: Validate that inline media_specs don't redefine registry specs
+// ============================================================================
+
+// TEST054: Test XV5 validation detects inline media spec redefinition of built-in spec
+function testXV5InlineSpecRedefinitionDetected() {
+  console.log('Testing XV5: Inline spec redefinition detected...');
+
+  // Try to redefine MEDIA_STRING which is a built-in spec
+  const mediaSpecs = {
+    [MEDIA_STRING]: {
+      media_type: 'text/plain',
+      title: 'My Custom String',
+      description: 'Trying to redefine string'
+    }
+  };
+
+  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+
+  assert(!result.valid, 'Should fail validation when redefining built-in spec');
+  assert(result.error && result.error.includes('XV5'), 'Error should mention XV5');
+  assert(result.redefines && result.redefines.includes(MEDIA_STRING), 'Should identify MEDIA_STRING as redefined');
+
+  console.log('  ✓ Inline spec redefinition detected');
+}
+
+// TEST055: Test XV5 validation allows new inline media spec not in built-ins
+function testXV5NewInlineSpecAllowed() {
+  console.log('Testing XV5: New inline spec allowed...');
+
+  // Define a completely new media spec that doesn't exist in built-ins
+  const mediaSpecs = {
+    'media:my-unique-custom-type-xyz123': {
+      media_type: 'application/json',
+      title: 'My Custom Output',
+      description: 'A custom output type'
+    }
+  };
+
+  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+
+  assert(result.valid, 'Should pass validation for new spec not in built-ins');
+  assert(!result.error, 'Should not have error message');
+
+  console.log('  ✓ New inline spec allowed');
+}
+
+// TEST056: Test XV5 validation passes for empty or null media_specs
+function testXV5EmptyMediaSpecsAllowed() {
+  console.log('Testing XV5: Empty media_specs allowed...');
+
+  // Empty or null media_specs should pass
+  let result = validateNoMediaSpecRedefinitionSync({});
+  assert(result.valid, 'Empty object should pass validation');
+
+  result = validateNoMediaSpecRedefinitionSync(null);
+  assert(result.valid, 'Null should pass validation');
+
+  result = validateNoMediaSpecRedefinitionSync(undefined);
+  assert(result.valid, 'Undefined should pass validation');
+
+  console.log('  ✓ Empty media_specs allowed');
+}
+
 // Update runTests to include new tests
 async function runTests() {
   console.log('Running Cap URN JavaScript tests...\n');
@@ -1737,6 +1869,11 @@ async function runTests() {
   await testStdinSourcePassedToExecuteCap();
   await testStdinSourceFileReferencePassedToExecuteCap();
 
+  // XV5 validation tests
+  testXV5InlineSpecRedefinitionDetected();
+  testXV5NewInlineSpecAllowed();
+  testXV5EmptyMediaSpecsAllowed();
+
   console.log('OK All tests passed!');
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "author": "Bahram Joharshamshiri",
   "dependencies": {
-    "tagged-urn": "^0.16.3139"
+    "tagged-urn": "^0.18.2934"
   },
   "description": "JavaScript implementation of Cap URN (Capability Uniform Resource Names) with strict validation and matching",
   "engines": {
@@ -32,5 +32,5 @@
   "scripts": {
     "test": "node capns.test.js"
   },
-  "version": "0.50.11396"
+  "version": "0.58.11575"
 }