capns 0.58.11575 → 0.60.11938

package/capns.js

@@ -834,46 +834,11 @@ function getProfileURL(profileName) {
 }
 
 // =============================================================================
-// BUILTIN MEDIA SPECS
+// MEDIA URN TAG UTILITIES
 // =============================================================================
-
-/**
- * Built-in media URN definitions - canonical media spec strings
- * Maps media URN to canonical format: <media-type>; profile=<url>
- *
- * NOTE: These use hardcoded URLs for static initialization.
- * Use getSchemaBaseURL() and getProfileURL() for dynamic resolution.
- */
-const BUILTIN_SPECS = {
-  [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str',
-  [MEDIA_INTEGER]: 'text/plain; profile=https://capns.org/schema/int',
-  [MEDIA_NUMBER]: 'text/plain; profile=https://capns.org/schema/num',
-  [MEDIA_BOOLEAN]: 'text/plain; profile=https://capns.org/schema/bool',
-  [MEDIA_OBJECT]: 'application/json; profile=https://capns.org/schema/obj',
-  [MEDIA_STRING_ARRAY]: 'application/json; profile=https://capns.org/schema/str-array',
-  [MEDIA_INTEGER_ARRAY]: 'application/json; profile=https://capns.org/schema/int-array',
-  [MEDIA_NUMBER_ARRAY]: 'application/json; profile=https://capns.org/schema/num-array',
-  [MEDIA_BOOLEAN_ARRAY]: 'application/json; profile=https://capns.org/schema/bool-array',
-  [MEDIA_OBJECT_ARRAY]: 'application/json; profile=https://capns.org/schema/obj-array',
-  [MEDIA_BINARY]: 'application/octet-stream',
-  [MEDIA_VOID]: 'application/x-void; profile=https://capns.org/schema/void',
-  // Semantic content types
-  [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',
-  // Document types (PRIMARY naming)
-  [MEDIA_PDF]: 'application/pdf',
-  [MEDIA_EPUB]: 'application/epub+zip',
-  // Text format types (PRIMARY naming)
-  [MEDIA_MD]: 'text/markdown',
-  [MEDIA_TXT]: 'text/plain',
-  [MEDIA_RST]: 'text/x-rst',
-  [MEDIA_LOG]: 'text/plain',
-  [MEDIA_HTML]: 'text/html',
-  [MEDIA_XML]: 'application/xml',
-  [MEDIA_JSON]: 'application/json',
-  [MEDIA_YAML]: 'application/x-yaml'
-};
+// NOTE: The MEDIA_X constants above are convenience values for referencing
+// common media URNs in code. Resolution must go through mediaSpecs tables -
+// there is NO built-in resolution.
 
 /**
  * Check if a media URN has a marker tag (e.g., bytes, json, textable).
@@ -1137,18 +1102,16 @@ class MediaSpec {
 /**
  * Resolve a media URN to a MediaSpec
  *
- * Resolution algorithm:
- * 1. Look up mediaUrn in mediaSpecs table
- * 2. If not found AND mediaUrn is a known built-in: use built-in definition
- * 3. If not found and not a built-in: FAIL HARD
+ * Resolution: Look up mediaUrn in mediaSpecs table, FAIL HARD if not found.
+ * There is no built-in resolution - all media URNs must be in mediaSpecs.
  *
- * @param {string} mediaUrn - The media URN (e.g., "media:string")
- * @param {Object} mediaSpecs - The mediaSpecs lookup table
+ * @param {string} mediaUrn - The media URN (e.g., "media:textable;form=scalar")
+ * @param {Object} mediaSpecs - The mediaSpecs lookup table (required)
  * @returns {MediaSpec} The resolved MediaSpec
  * @throws {MediaSpecError} If media URN cannot be resolved
  */
 function resolveMediaUrn(mediaUrn, mediaSpecs = {}) {
-  // First check local mediaSpecs table
+  // Look up in mediaSpecs table
   if (mediaSpecs && mediaSpecs[mediaUrn]) {
     const def = mediaSpecs[mediaUrn];
 
@@ -1178,38 +1141,24 @@ function resolveMediaUrn(mediaUrn, mediaSpecs = {}) {
     }
   }
 
-  // Check built-in specs
-  if (BUILTIN_SPECS[mediaUrn]) {
-    const spec = MediaSpec.parse(BUILTIN_SPECS[mediaUrn]);
-    spec.mediaUrn = mediaUrn; // Attach source URN for tag-based checks
-    return spec;
-  }
-
-  // FAIL HARD - no fallbacks, no guessing
+  // FAIL HARD - media URN must be in mediaSpecs table
   throw new MediaSpecError(
     MediaSpecErrorCodes.UNRESOLVABLE_MEDIA_URN,
-    `Cannot resolve media URN: '${mediaUrn}'. Not found in mediaSpecs table and not a known built-in.`
+    `Cannot resolve media URN: '${mediaUrn}'. Not found in mediaSpecs table.`
   );
 }
 
 /**
- * Check if a media URN is a known built-in
- * @param {string} mediaUrn - The media URN to check
- * @returns {boolean} True if built-in
- */
-function isBuiltinMediaUrn(mediaUrn) {
-  return BUILTIN_SPECS.hasOwnProperty(mediaUrn);
-}
-
-/**
- * XV5: Validate that inline media_specs don't redefine built-in/registry specs.
+ * XV5: Validate that inline media_specs don't redefine existing registry specs.
  *
- * For capns-js (client-side), we check against BUILTIN_SPECS.
- * Server-side validation (capns_dot_org) should check against the full registry.
+ * Validation requires a registryLookup function to check if media URNs exist.
+ * If no registryLookup is provided, validation passes (graceful degradation).
  *
  * @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)
+ * @param {Function} [options.registryLookup] - Function to check if media URN exists in registry
+ *                                              Returns true if exists, false otherwise
+ *                                              Should handle errors gracefully (return false)
  * @returns {Promise<{valid: boolean, error?: string, redefines?: string[]}>}
  */
 async function validateNoMediaSpecRedefinition(mediaSpecs, options = {}) {
@@ -1218,26 +1167,23 @@ async function validateNoMediaSpecRedefinition(mediaSpecs, options = {}) {
   }
 
   const { registryLookup } = options;
+
+  // If no registry lookup provided, degrade gracefully and allow
+  if (!registryLookup || typeof registryLookup !== 'function') {
+    return { valid: true };
+  }
+
   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.`);
+    try {
+      const existsInRegistry = await registryLookup(mediaUrn);
+      if (existsInRegistry) {
+        redefines.push(mediaUrn);
       }
+    } catch (err) {
+      // Registry lookup failed - 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.`);
     }
   }
 
@@ -1253,21 +1199,28 @@ async function validateNoMediaSpecRedefinition(mediaSpecs, options = {}) {
 }
 
 /**
- * XV5: Synchronous version for checking against built-in specs only.
- * Use this for client-side validation where registry lookup isn't available.
+ * XV5: Synchronous version that checks against a provided lookup function.
+ * If no registryLookup is provided, validation passes (graceful degradation).
  *
  * @param {Object} mediaSpecs - The inline media_specs object from a capability
+ * @param {Function} [registryLookup] - Synchronous function to check if media URN exists
+ *                                       Returns true if exists, false otherwise
  * @returns {{valid: boolean, error?: string, redefines?: string[]}}
  */
-function validateNoMediaSpecRedefinitionSync(mediaSpecs) {
+function validateNoMediaSpecRedefinitionSync(mediaSpecs, registryLookup = null) {
   if (!mediaSpecs || typeof mediaSpecs !== 'object' || Object.keys(mediaSpecs).length === 0) {
     return { valid: true };
   }
 
+  // If no registry lookup provided, degrade gracefully and allow
+  if (!registryLookup || typeof registryLookup !== 'function') {
+    return { valid: true };
+  }
+
   const redefines = [];
 
   for (const mediaUrn of Object.keys(mediaSpecs)) {
-    if (isBuiltinMediaUrn(mediaUrn)) {
+    if (registryLookup(mediaUrn)) {
       redefines.push(mediaUrn);
     }
   }
@@ -1275,7 +1228,7 @@ function validateNoMediaSpecRedefinitionSync(mediaSpecs) {
   if (redefines.length > 0) {
     return {
       valid: false,
-      error: `XV5: Inline media specs redefine existing built-in specs: ${redefines.join(', ')}`,
+      error: `XV5: Inline media specs redefine existing registry specs: ${redefines.join(', ')}`,
       redefines
     };
   }
@@ -3508,10 +3461,8 @@ module.exports = {
   isJSONCapUrn,
   isStructuredCapUrn,
   resolveMediaUrn,
-  isBuiltinMediaUrn,
   validateNoMediaSpecRedefinition,
   validateNoMediaSpecRedefinitionSync,
-  BUILTIN_SPECS,
   getSchemaBaseURL,
   getProfileURL,
   MEDIA_STRING,

package/capns.test.js

@@ -12,15 +12,6 @@ const {
   MediaSpecError,
   MediaSpecErrorCodes,
   resolveMediaUrn,
-  isBuiltinMediaUrn,
-  BUILTIN_SPECS,
-  MEDIA_STRING,
-  MEDIA_INTEGER,
-  MEDIA_NUMBER,
-  MEDIA_BOOLEAN,
-  MEDIA_OBJECT,
-  MEDIA_BINARY,
-  MEDIA_VOID,
   // CapMatrix and CapCube
   CapMatrixError,
   CapMatrix,
@@ -38,6 +29,23 @@ const {
   validateNoMediaSpecRedefinitionSync
 } = require('./capns.js');
 
+// Media URN constants (previously exported from capns.js as built-ins)
+const MEDIA_STRING = 'media:string';
+const MEDIA_INTEGER = 'media:integer';
+const MEDIA_NUMBER = 'media:number';
+const MEDIA_BOOLEAN = 'media:boolean';
+const MEDIA_OBJECT = 'media:object';
+const MEDIA_BINARY = 'media:binary';
+const MEDIA_VOID = 'media:void';
+
+// Media spec definitions for tests (no longer built into capns.js)
+const TEST_MEDIA_SPECS = {
+  [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str',
+  [MEDIA_INTEGER]: 'text/plain; profile=https://capns.org/schema/int',
+  [MEDIA_OBJECT]: 'application/json; profile=https://capns.org/schema/obj',
+  [MEDIA_BINARY]: 'application/octet-stream'
+};
+
 // Test assertion utility
 function assert(condition, message) {
   if (!condition) {
@@ -565,45 +573,36 @@ 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...');
-
-  // Verify built-in spec IDs exist
-  assert(isBuiltinMediaUrn(MEDIA_STRING), 'MEDIA_STRING should be built-in');
-  assert(isBuiltinMediaUrn(MEDIA_INTEGER), 'MEDIA_INTEGER should be built-in');
-  assert(isBuiltinMediaUrn(MEDIA_NUMBER), 'MEDIA_NUMBER should be built-in');
-  assert(isBuiltinMediaUrn(MEDIA_BOOLEAN), 'MEDIA_BOOLEAN should be built-in');
-  assert(isBuiltinMediaUrn(MEDIA_OBJECT), 'MEDIA_OBJECT should be built-in');
-  assert(isBuiltinMediaUrn(MEDIA_BINARY), 'MEDIA_BINARY should be built-in');
 
-  // Non-existent spec should not be built-in
-  assert(!isBuiltinMediaUrn('media:nonexistent'), 'Non-existent spec should not be built-in');
-
-  console.log('  ✓ Built-in spec IDs');
-}
+// TEST060: Test resolveMediaUrn requires mediaSpecs table for resolution
+function testMediaUrnResolutionRequiresMediaSpecs() {
+  console.log('Testing media URN resolution requires mediaSpecs...');
 
-// TEST060: Test resolveMediaUrn resolves built-in media URNs to MediaSpec
-function testSpecIdResolution() {
-  console.log('Testing spec ID resolution...');
+  // Media specs table with definitions
+  const mediaSpecs = {
+    [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str',
+    [MEDIA_INTEGER]: 'text/plain; profile=https://capns.org/schema/int',
+    [MEDIA_OBJECT]: 'application/json; profile=https://capns.org/schema/obj',
+    [MEDIA_BINARY]: 'application/octet-stream'
+  };
 
-  // Should resolve built-in spec IDs
-  const strSpec = resolveMediaUrn(MEDIA_STRING);
+  // Should resolve spec IDs from mediaSpecs table
+  const strSpec = resolveMediaUrn(MEDIA_STRING, mediaSpecs);
   assertEqual(strSpec.contentType, 'text/plain', 'Should resolve str spec');
   assertEqual(strSpec.profile, 'https://capns.org/schema/str', 'Should have correct profile');
 
-  const intSpec = resolveMediaUrn(MEDIA_INTEGER);
+  const intSpec = resolveMediaUrn(MEDIA_INTEGER, mediaSpecs);
   assertEqual(intSpec.contentType, 'text/plain', 'Should resolve int spec');
   assertEqual(intSpec.profile, 'https://capns.org/schema/int', 'Should have correct profile');
 
-  const objSpec = resolveMediaUrn(MEDIA_OBJECT);
+  const objSpec = resolveMediaUrn(MEDIA_OBJECT, mediaSpecs);
   assertEqual(objSpec.contentType, 'application/json', 'Should resolve obj spec');
 
-  const binarySpec = resolveMediaUrn(MEDIA_BINARY);
+  const binarySpec = resolveMediaUrn(MEDIA_BINARY, mediaSpecs);
   assertEqual(binarySpec.contentType, 'application/octet-stream', 'Should resolve binary spec');
-  assert(binarySpec.isBinary(), 'Binary spec should report isBinary()');
+  // Note: isBinary() checks for 'bytes' tag in media URN, not content type
 
-  console.log('  ✓ Spec ID resolution');
+  console.log('  ✓ Media URN resolution requires mediaSpecs');
 }
 
 // TEST061: Test resolveMediaUrn resolves custom media URNs from mediaSpecs table
@@ -611,13 +610,15 @@ function testMediaUrnResolutionWithMediaSpecs() {
   console.log('Testing media URN resolution with custom mediaSpecs...');
 
   // Custom mediaSpecs table (using media URN format as keys)
+  // Includes MEDIA_STRING so resolution works
   const mediaSpecs = {
     'media:custom-json': 'application/json; profile=https://example.com/schema/custom',
     'media:rich-xml': {
       media_type: 'application/xml',
       profile_uri: 'https://example.com/schema/rich',
       schema: { type: 'object' }
-    }
+    },
+    [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str'
   };
 
   // Should resolve custom string form
@@ -631,9 +632,9 @@ function testMediaUrnResolutionWithMediaSpecs() {
   assertEqual(richSpec.profile, 'https://example.com/schema/rich', 'Should have rich profile');
   assert(richSpec.schema !== null, 'Should have schema from object form');
 
-  // Should still resolve built-ins when not in custom table
+  // Should resolve MEDIA_STRING from mediaSpecs table
   const strSpec = resolveMediaUrn(MEDIA_STRING, mediaSpecs);
-  assertEqual(strSpec.contentType, 'text/plain', 'Should still resolve built-in');
+  assertEqual(strSpec.contentType, 'text/plain', 'Should resolve string spec from mediaSpecs');
 
   console.log('  ✓ Media URN resolution with custom mediaSpecs');
 }
@@ -704,15 +705,19 @@ 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...');
+// TEST065: Test string form definitions have no metadata
+function testMetadataForSimpleStringDef() {
+  console.log('Testing metadata for simple string definition...');
 
-  // Built-in media URNs should have no metadata
-  const resolved = resolveMediaUrn(MEDIA_STRING, {});
-  assert(resolved.metadata === null, 'Built-in should have no metadata');
+  // String form definitions should have no metadata
+  const mediaSpecs = {
+    [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str'
+  };
+
+  const resolved = resolveMediaUrn(MEDIA_STRING, mediaSpecs);
+  assert(resolved.metadata === null, 'String form definition should have no metadata');
 
-  console.log('  ✓ Built-in has no metadata');
+  console.log('  ✓ String form definition has no metadata');
 }
 
 // TEST066: Test metadata and validation coexist in media spec definition
@@ -751,7 +756,7 @@ function testMetadataWithValidation() {
   console.log('  ✓ Metadata coexists with validation');
 }
 
-// TEST108: Test Cap with mediaSpecs resolves custom and built-in media URNs
+// TEST108: Test Cap with mediaSpecs resolves custom media URNs
 function testCapWithMediaSpecs() {
   console.log('Testing Cap with mediaSpecs...');
 
@@ -762,8 +767,9 @@ function testCapWithMediaSpecs() {
 
   const cap = new Cap(urn, 'Test Cap', 'test_command');
 
-  // Set custom mediaSpecs
+  // Set custom mediaSpecs - must include MEDIA_STRING for resolution to work
   cap.mediaSpecs = {
+    [MEDIA_STRING]: 'text/plain; profile=https://capns.org/schema/str',
     'media:custom': {
       media_type: 'application/json',
       profile_uri: 'https://example.com/schema/output',
@@ -774,9 +780,9 @@ function testCapWithMediaSpecs() {
     }
   };
 
-  // Should resolve built-in via cap.resolveMediaUrn
+  // Should resolve MEDIA_STRING from mediaSpecs via cap.resolveMediaUrn
   const strSpec = cap.resolveMediaUrn(MEDIA_STRING);
-  assertEqual(strSpec.contentType, 'text/plain', 'Should resolve built-in through cap');
+  assertEqual(strSpec.contentType, 'text/plain', 'Should resolve string spec through cap');
 
   // Should resolve custom spec via cap.resolveMediaUrn
   const outputSpec = cap.resolveMediaUrn('media:custom');
@@ -1729,11 +1735,14 @@ function testStdinSourceFileReferencePassedToExecuteCap() {
 // 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
+// TEST054: Test XV5 validation detects inline media spec redefinition of registry spec
 function testXV5InlineSpecRedefinitionDetected() {
   console.log('Testing XV5: Inline spec redefinition detected...');
 
-  // Try to redefine MEDIA_STRING which is a built-in spec
+  // Mock registry lookup that reports MEDIA_STRING as existing in registry
+  const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
+
+  // Try to redefine MEDIA_STRING which is in the registry
   const mediaSpecs = {
     [MEDIA_STRING]: {
       media_type: 'text/plain',
@@ -1742,20 +1751,23 @@ function testXV5InlineSpecRedefinitionDetected() {
     }
   };
 
-  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs, registryLookup);
 
-  assert(!result.valid, 'Should fail validation when redefining built-in spec');
+  assert(!result.valid, 'Should fail validation when redefining registry 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
+// TEST055: Test XV5 validation allows new inline media spec not in registry
 function testXV5NewInlineSpecAllowed() {
   console.log('Testing XV5: New inline spec allowed...');
 
-  // Define a completely new media spec that doesn't exist in built-ins
+  // Mock registry lookup that reports MEDIA_STRING as existing, but not custom specs
+  const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
+
+  // Define a completely new media spec that doesn't exist in registry
   const mediaSpecs = {
     'media:my-unique-custom-type-xyz123': {
       media_type: 'application/json',
@@ -1764,9 +1776,9 @@ function testXV5NewInlineSpecAllowed() {
     }
   };
 
-  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs);
+  const result = validateNoMediaSpecRedefinitionSync(mediaSpecs, registryLookup);
 
-  assert(result.valid, 'Should pass validation for new spec not in built-ins');
+  assert(result.valid, 'Should pass validation for new spec not in registry');
   assert(!result.error, 'Should not have error message');
 
   console.log('  ✓ New inline spec allowed');
@@ -1776,14 +1788,17 @@ function testXV5NewInlineSpecAllowed() {
 function testXV5EmptyMediaSpecsAllowed() {
   console.log('Testing XV5: Empty media_specs allowed...');
 
+  // Mock registry lookup function
+  const registryLookup = (mediaUrn) => mediaUrn === MEDIA_STRING;
+
   // Empty or null media_specs should pass
-  let result = validateNoMediaSpecRedefinitionSync({});
+  let result = validateNoMediaSpecRedefinitionSync({}, registryLookup);
   assert(result.valid, 'Empty object should pass validation');
 
-  result = validateNoMediaSpecRedefinitionSync(null);
+  result = validateNoMediaSpecRedefinitionSync(null, registryLookup);
   assert(result.valid, 'Null should pass validation');
 
-  result = validateNoMediaSpecRedefinitionSync(undefined);
+  result = validateNoMediaSpecRedefinitionSync(undefined, registryLookup);
   assert(result.valid, 'Undefined should pass validation');
 
   console.log('  ✓ Empty media_specs allowed');
@@ -1816,13 +1831,12 @@ async function runTests() {
   // New format tests
   testMediaSpecCanonicalFormat();
   testMediaSpecLegacyFormatRejection();
-  testBuiltinSpecIds();
-  testSpecIdResolution();
+  testMediaUrnResolutionRequiresMediaSpecs();
   testMediaUrnResolutionWithMediaSpecs();
   testMediaUrnResolutionFailHard();
   testMetadataPropagation();
   testMetadataForStringDef();
-  testMetadataForBuiltin();
+  testMetadataForSimpleStringDef();
   testMetadataWithValidation();
   testCapWithMediaSpecs();
   testCapJSONSerialization();

package/package.json

@@ -32,5 +32,5 @@
   "scripts": {
     "test": "node capns.test.js"
   },
-  "version": "0.58.11575"
+  "version": "0.60.11938"
 }