capdag 0.126.278 → 0.137.303

package/capdag.js

@@ -27,47 +27,102 @@ const ErrorCodes = {
   UNTERMINATED_QUOTE: 8,
   INVALID_ESCAPE_SEQUENCE: 9,
   MISSING_IN_SPEC: 10,
-  MISSING_OUT_SPEC: 11
+  MISSING_OUT_SPEC: 11,
+  EMPTY_VALUE: 12,
+  INVALID_IN_SPEC: 13,
+  INVALID_OUT_SPEC: 14
 };
 
 // Note: All parsing is delegated to TaggedUrn from tagged-urn-js
 // No duplicate state machine or parsing helpers needed here
 
 /**
- * Cap URN implementation with required direction (in/out) and optional tags
+ * Cap URN implementation with direction specs and optional tags.
  *
- * Direction is now a REQUIRED first-class field:
- * - inSpec: The input media URN (required, must start with "media:")
- * - outSpec: The output media URN (required, must start with "media:")
+ * Direction rules match the Rust reference:
+ * - missing `in` or `out` defaults to `media:`
+ * - `in=*` and `out=*` normalize to `media:`
+ * - empty `in=` / `out=` are rejected
  * - tags: Other optional tags (no longer contains in/out)
  */
 /**
- * Check if a value is a valid media URN or wildcard
- * @param {string} value - The value to check
- * @returns {boolean} True if valid media URN or wildcard
+ * Normalize a parsed direction tag to canonical wildcard semantics.
+ * Missing tags and `*` both become `media:`.
+ *
+ * @param {TaggedUrn} taggedUrn - Parsed tagged URN
+ * @param {string} tagName - `in` or `out`
+ * @returns {string} Normalized direction spec
+ */
+function processDirectionTag(taggedUrn, tagName) {
+  const rawValue = taggedUrn.getTag(tagName);
+  if (rawValue === undefined || rawValue === '*') {
+    return 'media:';
+  }
+  if (rawValue === '') {
+    throw new CapUrnError(
+      tagName === 'in' ? ErrorCodes.INVALID_IN_SPEC : ErrorCodes.INVALID_OUT_SPEC,
+      `Empty value for '${tagName}' tag is not allowed`
+    );
+  }
+  return rawValue;
+}
+
+/**
+ * Canonicalize a direction spec via MediaUrn parsing.
+ *
+ * @param {string} spec - Media URN string
+ * @param {string} tagName - `in` or `out`
+ * @returns {string} Canonical media URN string
  */
-function isValidMediaUrnOrWildcard(value) {
-  return value === '*' || (value && value.startsWith('media:'));
+function canonicalizeDirectionSpec(spec, tagName) {
+  if (spec === 'media:' || spec === '*') {
+    return spec;
+  }
+
+  try {
+    return MediaUrn.fromString(spec).toString();
+  } catch (error) {
+    throw new CapUrnError(
+      tagName === 'in' ? ErrorCodes.INVALID_IN_SPEC : ErrorCodes.INVALID_OUT_SPEC,
+      `Invalid media URN for ${tagName} spec '${spec}': ${error.message}`
+    );
+  }
+}
+
+/**
+ * Validate a direction spec while preserving the caller-provided string.
+ * This matches the reference `with_in_spec` / `with_out_spec` behavior.
+ *
+ * @param {string} spec - Media URN string
+ * @param {string} tagName - `in` or `out`
+ * @returns {string} The original spec when valid
+ */
+function validatePreservedDirectionSpec(spec, tagName) {
+  if (spec === 'media:' || spec === '*') {
+    return spec;
+  }
+
+  try {
+    MediaUrn.fromString(spec);
+    return spec;
+  } catch (error) {
+    throw new CapUrnError(
+      tagName === 'in' ? ErrorCodes.INVALID_IN_SPEC : ErrorCodes.INVALID_OUT_SPEC,
+      `Invalid media URN for ${tagName} spec '${spec}': ${error.message}`
+    );
+  }
 }
 
 class CapUrn {
   /**
-   * Create a new CapUrn with required direction specs
-   * @param {string} inSpec - Required input media URN (e.g., "media:void") or wildcard "*"
-   * @param {string} outSpec - Required output media URN (e.g., "media:object") or wildcard "*"
+   * Create a new CapUrn with direction specs.
+   * @param {string} inSpec - Input media URN (e.g., "media:void")
+   * @param {string} outSpec - Output media URN (e.g., "media:object")
    * @param {Object} tags - Other tags (must NOT contain 'in' or 'out')
    */
   constructor(inSpec, outSpec, tags = {}) {
-    // Validate in/out are media URNs or wildcards
-    if (!isValidMediaUrnOrWildcard(inSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'in' media URN: ${inSpec}. Must start with 'media:' or be '*'`);
-    }
-    if (!isValidMediaUrnOrWildcard(outSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'out' media URN: ${outSpec}. Must start with 'media:' or be '*'`);
-    }
-
-    this.inSpec = inSpec;
-    this.outSpec = outSpec;
+    this.inSpec = canonicalizeDirectionSpec(inSpec, 'in');
+    this.outSpec = canonicalizeDirectionSpec(outSpec, 'out');
     this.tags = {};
     // Copy tags, filtering out any 'in' or 'out' that might have slipped through
     for (const [key, value] of Object.entries(tags)) {
@@ -116,13 +171,14 @@ class CapUrn {
    * Create a Cap URN from string representation
    * Format: cap:in="<media-urn>";out="<media-urn>";key1=value1;key2=value2;...
    *
-   * IMPORTANT: 'in' and 'out' tags are REQUIRED and must be valid media URNs.
+   * Missing `in` / `out` default to `media:`. `in=*` / `out=*` are also
+   * normalized to `media:`.
    *
    * Uses TaggedUrn for parsing to ensure consistent behavior across implementations.
    *
    * @param {string} s - The Cap URN string
    * @returns {CapUrn} The parsed Cap URN
-   * @throws {CapUrnError} If parsing fails or in/out are missing/invalid
+   * @throws {CapUrnError} If parsing fails or direction specs are invalid
    */
   static fromString(s) {
     if (!s || typeof s !== 'string') {
@@ -162,24 +218,8 @@ class CapUrn {
       throw new CapUrnError(ErrorCodes.MISSING_CAP_PREFIX, `Expected 'cap:' prefix, got '${taggedUrn.getPrefix()}:'`);
     }
 
-    // Extract required 'in' and 'out' tags
-    const inSpec = taggedUrn.getTag('in');
-    const outSpec = taggedUrn.getTag('out');
-
-    if (!inSpec) {
-      throw new CapUrnError(ErrorCodes.MISSING_IN_SPEC, "Cap URN requires 'in' tag for input media URN");
-    }
-    if (!outSpec) {
-      throw new CapUrnError(ErrorCodes.MISSING_OUT_SPEC, "Cap URN requires 'out' tag for output media URN");
-    }
-
-    // Validate in/out are media URNs or wildcards
-    if (!isValidMediaUrnOrWildcard(inSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'in' media URN: ${inSpec}. Must start with 'media:' or be '*'`);
-    }
-    if (!isValidMediaUrnOrWildcard(outSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'out' media URN: ${outSpec}. Must start with 'media:' or be '*'`);
-    }
+    const inSpec = processDirectionTag(taggedUrn, 'in');
+    const outSpec = processDirectionTag(taggedUrn, 'out');
 
     // Build remaining tags (excluding in/out)
     const remainingTags = {};
@@ -193,12 +233,12 @@ class CapUrn {
   }
 
   /**
-   * Create a Cap URN from a tags object
-   * Extracts 'in' and 'out' from tags (required), stores rest as regular tags
+   * Create a Cap URN from a tags object.
+   * Unlike string parsing, this path requires explicit `in` and `out` tags.
    *
    * @param {Object} tags - Object containing all tags including 'in' and 'out'
    * @returns {CapUrn} The parsed Cap URN
-   * @throws {CapUrnError} If 'in' or 'out' tags are missing or invalid
+   * @throws {CapUrnError} If `in` or `out` tags are missing or invalid
    */
   static fromTags(tags) {
     const inSpec = tags['in'] || tags['IN'];
@@ -211,12 +251,11 @@ class CapUrn {
       throw new CapUrnError(ErrorCodes.MISSING_OUT_SPEC, "Cap URN requires 'out' tag for output media URN");
     }
 
-    // Validate in/out are media URNs or wildcards
-    if (!isValidMediaUrnOrWildcard(inSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'in' media URN: ${inSpec}. Must start with 'media:' or be '*'`);
+    if (inSpec === '') {
+      throw new CapUrnError(ErrorCodes.INVALID_IN_SPEC, "Empty value for 'in' tag is not allowed");
     }
-    if (!isValidMediaUrnOrWildcard(outSpec)) {
-      throw new CapUrnError(ErrorCodes.INVALID_FORMAT, `Invalid 'out' media URN: ${outSpec}. Must start with 'media:' or be '*'`);
+    if (outSpec === '') {
+      throw new CapUrnError(ErrorCodes.INVALID_OUT_SPEC, "Empty value for 'out' tag is not allowed");
     }
 
     // Build remaining tags (excluding in/out)
@@ -289,15 +328,18 @@ class CapUrn {
   }
 
   /**
-   * Create a new cap URN with an added or updated tag
-   * Key is normalized to lowercase; value is preserved as-is
-   * SILENTLY IGNORES attempts to set "in" or "out" - use withInSpec/withOutSpec instead
+   * Create a new cap URN with an added or updated tag.
+   * Attempts to set `in` / `out` through `withTag` are ignored; use
+   * `withInSpec` / `withOutSpec` instead.
    *
    * @param {string} key - The tag key
    * @param {string} value - The tag value
    * @returns {CapUrn} A new CapUrn instance with the tag added/updated
    */
   withTag(key, value) {
+    if (value === '') {
+      throw new CapUrnError(ErrorCodes.EMPTY_VALUE, `Empty value for key '${key}' (use '*' for wildcard)`);
+    }
     const keyLower = key.toLowerCase();
     // Silently ignore attempts to set in/out via withTag
     if (keyLower === 'in' || keyLower === 'out') {
@@ -315,7 +357,9 @@ class CapUrn {
    * @returns {CapUrn} A new CapUrn instance with the updated inSpec
    */
   withInSpec(inSpec) {
-    return new CapUrn(inSpec, this.outSpec, this.tags);
+    const updated = new CapUrn(this.inSpec, this.outSpec, this.tags);
+    updated.inSpec = validatePreservedDirectionSpec(inSpec, 'in');
+    return updated;
   }
 
   /**
@@ -325,7 +369,9 @@ class CapUrn {
    * @returns {CapUrn} A new CapUrn instance with the updated outSpec
    */
   withOutSpec(outSpec) {
-    return new CapUrn(this.inSpec, outSpec, this.tags);
+    const updated = new CapUrn(this.inSpec, this.outSpec, this.tags);
+    updated.outSpec = validatePreservedDirectionSpec(outSpec, 'out');
+    return updated;
   }
 
   /**
@@ -366,11 +412,9 @@ class CapUrn {
       return true;
     }
 
-    // Direction specs: TaggedUrn semantic matching via MediaUrn
-    // Check in_urn: cap's input spec (pattern) accepts request's input (instance).
-    // "media:" on the PATTERN side (this.inSpec) means "I accept any input" — skip check.
-    // "*" is also treated as wildcard. "media:" on the instance side still participates.
-    if (this.inSpec !== '*' && this.inSpec !== 'media:' && request.inSpec !== '*') {
+    // Input direction: pattern accepts instance. `media:` on the pattern side is
+    // the wildcard top and skips the check.
+    if (this.inSpec !== 'media:' && this.inSpec !== '*') {
       const capIn = TaggedUrn.fromString(this.inSpec);
       const requestIn = TaggedUrn.fromString(request.inSpec);
       if (!capIn.accepts(requestIn)) {
@@ -378,10 +422,9 @@ class CapUrn {
       }
     }
 
-    // Check out_urn: cap's output (instance) conforms to request's output (pattern).
-    // "media:" on the PATTERN side (this.outSpec) means "I accept any output" — skip check.
-    // "*" is also treated as wildcard. "media:" on the instance side still participates.
-    if (this.outSpec !== '*' && this.outSpec !== 'media:' && request.outSpec !== '*') {
+    // Output direction: provider output must conform to requested output.
+    // `media:` on the pattern side is wildcard top and skips the check.
+    if (this.outSpec !== 'media:' && this.outSpec !== '*') {
       const capOut = TaggedUrn.fromString(this.outSpec);
       const requestOut = TaggedUrn.fromString(request.outSpec);
       if (!capOut.conformsTo(requestOut)) {
@@ -389,33 +432,23 @@ class CapUrn {
       }
     }
 
-    // Check all other tags that the request specifies
-    for (const [requestKey, requestValue] of Object.entries(request.tags)) {
-      const capValue = this.tags[requestKey];
-
-      if (capValue === undefined) {
-        // Missing tag in cap is treated as wildcard - can handle any value
-        continue;
-      }
+    // Check all tags required by the pattern. Missing tags in the instance reject.
+    for (const [patternKey, patternValue] of Object.entries(this.tags)) {
+      const requestValue = request.tags[patternKey];
 
-      if (capValue === '*') {
-        // Cap has wildcard - can handle any value
-        continue;
+      if (requestValue === undefined) {
+        return false;
       }
 
-      if (requestValue === '*') {
-        // Request accepts any value - cap's specific value matches
+      if (patternValue === '*' || requestValue === '*') {
         continue;
       }
 
-      if (capValue !== requestValue) {
-        // Cap has specific value that doesn't match request's specific value
+      if (patternValue !== requestValue) {
         return false;
       }
     }
 
-    // If cap has additional specific tags that request doesn't specify, that's fine
-    // The cap is just more specific than needed
     return true;
   }
 
@@ -441,12 +474,13 @@ class CapUrn {
    */
   specificity() {
     let count = 0;
-    // Direction specs contribute their MediaUrn tag count
-    if (this.inSpec !== '*') {
+    // Direction specs contribute their MediaUrn tag count. `media:` is the
+    // wildcard top and contributes zero.
+    if (this.inSpec !== 'media:' && this.inSpec !== '*') {
       const inMedia = TaggedUrn.fromString(this.inSpec);
       count += Object.keys(inMedia.tags).length;
     }
-    if (this.outSpec !== '*') {
+    if (this.outSpec !== 'media:' && this.outSpec !== '*') {
       const outMedia = TaggedUrn.fromString(this.outSpec);
       count += Object.keys(outMedia.tags).length;
     }
@@ -686,7 +720,7 @@ class CapMatcher {
     let bestSpecificity = -1;
 
     for (const cap of caps) {
-      if (cap.accepts(request)) {
+      if (request.accepts(cap)) {
         const specificity = cap.specificity();
         if (specificity > bestSpecificity) {
           best = cap;
@@ -706,7 +740,7 @@ class CapMatcher {
    * @returns {CapUrn[]} Array of matching caps sorted by specificity (most specific first)
    */
   static findAllMatches(caps, request) {
-    const matches = caps.filter(cap => cap.accepts(request));
+    const matches = caps.filter(cap => request.accepts(cap));
 
     // Sort by specificity (most specific first)
     matches.sort((a, b) => b.specificity() - a.specificity());
@@ -789,18 +823,22 @@ const MEDIA_OBJECT = 'media:record';
 // Media URN for binary data - the most general media type (no constraints)
 const MEDIA_IDENTITY = 'media:';
 
-// Array types - URNs must match base.toml definitions
-// Media URN for string array type - textable with list marker
-const MEDIA_STRING_ARRAY = 'media:list;textable';
-// Media URN for integer array type - textable, numeric with list marker
-const MEDIA_INTEGER_ARRAY = 'media:integer;list;textable;numeric';
-// Media URN for number array type - textable, numeric with list marker
-const MEDIA_NUMBER_ARRAY = 'media:list;textable;numeric';
-// Media URN for boolean array type - uses "bool" with list marker
-const MEDIA_BOOLEAN_ARRAY = 'media:bool;list;textable';
-// Media URN for object array type - list of records (NOT textable)
-// Use a specific format like JSON array for textable object arrays.
-const MEDIA_OBJECT_ARRAY = 'media:list;record';
+// List types - URNs must match base.toml definitions
+// Media URN for generic list type
+const MEDIA_LIST = 'media:list';
+// Media URN for textable list type
+const MEDIA_TEXTABLE_LIST = 'media:list;textable';
+// Media URN for string list type - textable with list marker
+const MEDIA_STRING_LIST = 'media:list;textable';
+// Media URN for integer list type - textable, numeric with list marker
+const MEDIA_INTEGER_LIST = 'media:integer;list;textable;numeric';
+// Media URN for number list type - textable, numeric with list marker
+const MEDIA_NUMBER_LIST = 'media:list;numeric;textable';
+// Media URN for boolean list type - uses "bool" with list marker
+const MEDIA_BOOLEAN_LIST = 'media:bool;list;textable';
+// Media URN for object list type - list of records (NOT textable)
+// Use a specific format like JSON array for textable object lists.
+const MEDIA_OBJECT_LIST = 'media:list;record';
 
 // Semantic media types for specialized content
 // Media URN for PNG image data
@@ -813,8 +851,6 @@ const MEDIA_VIDEO = 'media:video';
 // Semantic AI input types - distinguished by their purpose/context
 // Media URN for audio input containing speech for transcription (Whisper)
 const MEDIA_AUDIO_SPEECH = 'media:audio;wav;speech';
-// Media URN for thumbnail image output
-const MEDIA_IMAGE_THUMBNAIL = 'media:image;png;thumbnail';
 
 // Document types (PRIMARY naming - type IS the format)
 // Media URN for PDF documents
@@ -842,6 +878,18 @@ const MEDIA_JSON_SCHEMA = 'media:json;json-schema;record;textable';
 // Media URN for YAML data - has record marker (structured key-value)
 const MEDIA_YAML = 'media:record;textable;yaml';
 
+// Format-specific variants for JSON, YAML, CSV
+const MEDIA_JSON_VALUE = 'media:json;textable';
+const MEDIA_JSON_RECORD = 'media:json;record;textable';
+const MEDIA_JSON_LIST = 'media:json;list;textable';
+const MEDIA_JSON_LIST_RECORD = 'media:json;list;record;textable';
+const MEDIA_YAML_VALUE = 'media:textable;yaml';
+const MEDIA_YAML_RECORD = 'media:record;textable;yaml';
+const MEDIA_YAML_LIST = 'media:list;textable;yaml';
+const MEDIA_YAML_LIST_RECORD = 'media:list;record;textable;yaml';
+const MEDIA_CSV = 'media:csv;list;record;textable';
+const MEDIA_CSV_LIST = 'media:csv;list;textable';
+
 // File path types - for arguments that represent filesystem paths
 // Media URN for a single file path - textable, scalar by default (no list marker)
 const MEDIA_FILE_PATH = 'media:file-path;textable';
@@ -849,8 +897,6 @@ const MEDIA_FILE_PATH = 'media:file-path;textable';
 const MEDIA_FILE_PATH_ARRAY = 'media:file-path;list;textable';
 
 // Semantic text input types - distinguished by their purpose/context
-// Media URN for frontmatter text (book metadata) - scalar by default
-const MEDIA_FRONTMATTER_TEXT = 'media:frontmatter;textable';
 // Media URN for model spec (provider:model format, HuggingFace name, etc.) - scalar by default
 const MEDIA_MODEL_SPEC = 'media:model-spec;textable';
 // Media URN for MLX model path - scalar by default
@@ -877,20 +923,19 @@ const MEDIA_PATH_OUTPUT = 'media:model-path;record;textable';
 const MEDIA_EMBEDDING_VECTOR = 'media:embedding-vector;record;textable';
 // Media URN for LLM inference output - has record marker
 const MEDIA_LLM_INFERENCE_OUTPUT = 'media:generated-text;record;textable';
-// Media URN for extracted metadata - has record marker
-const MEDIA_FILE_METADATA = 'media:file-metadata;record;textable';
-// Media URN for extracted outline - has record marker
-const MEDIA_DOCUMENT_OUTLINE = 'media:document-outline;record;textable';
-// Media URN for disbound page - has list marker (array of page objects)
-const MEDIA_DISBOUND_PAGE = 'media:disbound-page;list;textable';
 // Media URN for vision inference output - textable, scalar by default
 const MEDIA_IMAGE_DESCRIPTION = 'media:image-description;textable';
 // Media URN for transcription output - has record marker
 const MEDIA_TRANSCRIPTION_OUTPUT = 'media:record;textable;transcription';
-// Media URN for decision output (bit choice) - scalar by default
-const MEDIA_DECISION = 'media:bool;decision;textable';
-// Media URN for decision array output (bit choices) - has list marker
-const MEDIA_DECISION_ARRAY = 'media:bool;decision;list;textable';
+// Media URN for decision output - JSON record with textable
+const MEDIA_DECISION = 'media:decision;json;record;textable';
+// Media URN for textable page output
+const MEDIA_TEXTABLE_PAGE = 'media:textable;page';
+// Collection types
+const MEDIA_COLLECTION = 'media:collection;record';
+const MEDIA_COLLECTION_LIST = 'media:collection;list;record';
+// Media URN for adapter selection output - JSON record
+const MEDIA_ADAPTER_SELECTION = 'media:adapter-selection;json;record';
 
 // =============================================================================
 // STANDARD CAP URN CONSTANTS
@@ -900,6 +945,10 @@ const MEDIA_DECISION_ARRAY = 'media:bool;decision;list;textable';
 // Accepts any media type as input and outputs any media type
 const CAP_IDENTITY = 'cap:in=media:;out=media:';
 
+// Adapter-selection capability. Default implementation returns empty END (no match).
+// Cartridges that inspect file content override this with a handler that returns {"media_urns": [...]}.
+const CAP_ADAPTER_SELECTION = 'cap:in="media:";out="media:adapter-selection;json;record"';
+
 // =============================================================================
 // MEDIA URN CLASS
 // =============================================================================
@@ -956,8 +1005,10 @@ class MediaUrn {
   // =========================================================================
 
   /**
-   * Returns true if this media is a list (has `list` marker tag).
-   * Returns false if scalar (no `list` marker = default).
+   * Returns true if this media URN describes list-type data (has `list` marker tag).
+   * This is a semantic type check — it means "the data format IS a list/array".
+   * This does NOT indicate input cardinality (single vs multiple items).
+   * Cardinality is tracked by is_sequence on the wire protocol, not by URN tags.
    * @returns {boolean}
    */
   isList() { return this._hasMarkerTag('list'); }
@@ -1027,6 +1078,22 @@ class MediaUrn {
   /** @returns {boolean} True if the "bool" marker tag is present */
   isBool() { return this._urn.getTag('bool') !== undefined; }
 
+  /**
+   * Returns true if this media URN describes YAML representation.
+   * @returns {boolean}
+   */
+  isYaml() {
+    return this._hasMarkerTag('yaml');
+  }
+
+  /**
+   * Returns true if this media URN describes CSV representation.
+   * @returns {boolean}
+   */
+  isCsv() {
+    return this._hasMarkerTag('csv');
+  }
+
   /**
    * Check if this represents a single file path type (not array).
    * Returns true if the "file-path" marker tag is present AND no list marker.
@@ -1048,6 +1115,13 @@ class MediaUrn {
    */
   isAnyFilePath() { return this._hasMarkerTag('file-path'); }
 
+  /**
+   * Check if this represents a collection type.
+   * Returns true if the "collection" marker tag is present.
+   * @returns {boolean}
+   */
+  isCollection() { return this._hasMarkerTag('collection'); }
+
   /**
    * Check if this media URN conforms to another (pattern).
    * @param {MediaUrn} pattern
@@ -1123,20 +1197,67 @@ class MediaUrn {
 // =============================================================================
 
 /**
- * Build URN for LLM conversation capability
- * @param {string} langCode - Language code (e.g., "en", "fr")
+ * Build URN for LLM generate-text capability
  * @returns {CapUrn}
  */
-function llmConversationUrn(langCode) {
+function llmGenerateTextUrn() {
   return new CapUrnBuilder()
-    .tag('op', 'conversation')
-    .tag('unconstrained', '*')
-    .tag('language', langCode)
+    .tag('op', 'generate_text')
+    .tag('llm', '*')
+    .tag('ml-model', '*')
     .inSpec(MEDIA_STRING)
-    .outSpec(MEDIA_LLM_INFERENCE_OUTPUT)
+    .outSpec(MEDIA_STRING)
+    .build();
+}
+
+/**
+ * Build URN for render-page-image capability
+ * @param {string} inputMedia - The input media URN string
+ * @returns {CapUrn}
+ */
+function renderPageImageUrn(inputMedia) {
+  return new CapUrnBuilder()
+    .tag('op', 'render_page_image')
+    .inSpec(inputMedia)
+    .outSpec(MEDIA_PNG)
     .build();
 }
 
+/**
+ * Build URN for format conversion capability
+ * @param {string} inMedia - The input media URN string
+ * @param {string} outMedia - The output media URN string
+ * @returns {CapUrn}
+ */
+function formatConversionUrn(inMedia, outMedia) {
+  return new CapUrnBuilder()
+    .tag('op', 'convert_format')
+    .inSpec(inMedia)
+    .outSpec(outMedia)
+    .build();
+}
+
+/**
+ * Map a primitive type name to the corresponding media URN string.
+ * @param {string} typeName - The type name (e.g., 'string', 'integer', 'string-list')
+ * @returns {string|null} The media URN string, or null if not recognized
+ */
+function mediaUrnForType(typeName) {
+  switch (typeName) {
+    case 'string': return MEDIA_STRING;
+    case 'integer': return MEDIA_INTEGER;
+    case 'number': return MEDIA_NUMBER;
+    case 'boolean': return MEDIA_BOOLEAN;
+    case 'object': return MEDIA_OBJECT;
+    case 'string-list': return MEDIA_STRING_LIST;
+    case 'integer-list': return MEDIA_INTEGER_LIST;
+    case 'number-list': return MEDIA_NUMBER_LIST;
+    case 'boolean-list': return MEDIA_BOOLEAN_LIST;
+    case 'object-list': return MEDIA_OBJECT_LIST;
+    default: return null;
+  }
+}
+
 /**
  * Build URN for model-availability capability
  * @returns {CapUrn}
@@ -2392,6 +2513,23 @@ function validateCapArgs(cap) {
     }
   }
 
+  // RULE11: Stdin source consistency with in= spec
+  // If in= is media:void, no args may have stdin sources.
+  // If in= is anything other than media:void, at least one arg must have a stdin source.
+  const inMediaUrn = cap.urn.inMediaUrn();
+  const voidUrn = MediaUrn.fromString(MEDIA_VOID);
+  const inIsVoid = inMediaUrn.isEquivalent(voidUrn);
+  if (inIsVoid && stdinUrns.length > 0) {
+    throw new ValidationError('InvalidCapSchema', capUrn, {
+      issue: `RULE11: Cap has in="${MEDIA_VOID}" but argument(s) declare stdin source`
+    });
+  }
+  if (!inIsVoid && stdinUrns.length === 0 && args.length > 0) {
+    throw new ValidationError('InvalidCapSchema', capUrn, {
+      issue: `RULE11: Cap has non-void in= spec but no argument declares a stdin source`
+    });
+  }
+
   // RULE5: No two args may have same position
   const positionSet = new Set();
   for (const { position, mediaUrn } of positions) {
@@ -2426,9 +2564,6 @@ function validateCapArgs(cap) {
     flagSet.add(flag);
   }
 
-  // RULE8: No unknown keys in source objects - this is handled in ArgSource.fromJSON()
-  // RULE11: cli_flag used verbatim as specified - enforced by design
-  // RULE12: media_urn is the key, no name field - enforced by CapArg structure
 }
 
 /**
@@ -2933,6 +3068,56 @@ class CapValidator {
 // CAP ARGUMENT VALUE - Unified argument type
 // ============================================================================
 
+/**
+ * Result from a cap execution.
+ *
+ * Scalar outputs carry raw materialized bytes (e.g. UTF-8 text, raw binary).
+ * List outputs carry a CBOR sequence of values, one per list item.
+ * Empty represents a void cap with no output.
+ */
+class CapResult {
+  static KIND_SCALAR = 'scalar';
+  static KIND_LIST = 'list';
+  static KIND_EMPTY = 'empty';
+
+  /**
+   * @param {'scalar'|'list'|'empty'} kind
+   * @param {Uint8Array|null} data - Bytes for scalar or CBOR sequence for list, null for empty
+   */
+  constructor(kind, data = null) {
+    this.kind = kind;
+    this.data = data;
+  }
+
+  /** Create a CapResult carrying raw bytes (scalar output). */
+  static scalar(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data || []);
+    return new CapResult(CapResult.KIND_SCALAR, bytes);
+  }
+
+  /** Create a CapResult carrying a CBOR sequence (list output). */
+  static list(cborSequence) {
+    const bytes = cborSequence instanceof Uint8Array ? cborSequence : new Uint8Array(cborSequence || []);
+    return new CapResult(CapResult.KIND_LIST, bytes);
+  }
+
+  /** Create a CapResult for void caps. */
+  static empty() {
+    return new CapResult(CapResult.KIND_EMPTY, null);
+  }
+
+  /** Returns true if this is a scalar result. */
+  isScalar() { return this.kind === CapResult.KIND_SCALAR; }
+
+  /** Returns true if this is a list result. */
+  isList() { return this.kind === CapResult.KIND_LIST; }
+
+  /** Returns true if this is an empty result. */
+  isEmpty() { return this.kind === CapResult.KIND_EMPTY; }
+}
+
+// ============================================================================
+
 /**
  * Unified argument type - arguments are identified by media_urn.
  * The cap definition's sources specify how to extract values (stdin, position, cli_flag).
@@ -3189,7 +3374,7 @@ class CompositeCapSet {
    * Execute a capability by finding the best match and delegating
    * @param {string} capUrn - The capability URN to execute
    * @param {CapArgumentValue[]} args - Arguments identified by media_urn
-   * @returns {Promise<{binaryOutput: Uint8Array|null, textOutput: string|null}>}
+   * @returns {Promise<CapResult>}
    */
   async executeCap(capUrn, args) {
     let request;
@@ -5435,18 +5620,20 @@ module.exports = {
   MEDIA_NUMBER,
   MEDIA_BOOLEAN,
   MEDIA_OBJECT,
-  MEDIA_STRING_ARRAY,
-  MEDIA_INTEGER_ARRAY,
-  MEDIA_NUMBER_ARRAY,
-  MEDIA_BOOLEAN_ARRAY,
-  MEDIA_OBJECT_ARRAY,
+  // List types
+  MEDIA_LIST,
+  MEDIA_TEXTABLE_LIST,
+  MEDIA_STRING_LIST,
+  MEDIA_INTEGER_LIST,
+  MEDIA_NUMBER_LIST,
+  MEDIA_BOOLEAN_LIST,
+  MEDIA_OBJECT_LIST,
   MEDIA_IDENTITY,
   MEDIA_VOID,
   MEDIA_PNG,
   MEDIA_AUDIO,
   MEDIA_VIDEO,
   MEDIA_AUDIO_SPEECH,
-  MEDIA_IMAGE_THUMBNAIL,
   // Document types (PRIMARY naming)
   MEDIA_PDF,
   MEDIA_EPUB,
@@ -5460,11 +5647,22 @@ module.exports = {
   MEDIA_JSON,
   MEDIA_JSON_SCHEMA,
   MEDIA_YAML,
+  // Format-specific variants
+  MEDIA_JSON_VALUE,
+  MEDIA_JSON_RECORD,
+  MEDIA_JSON_LIST,
+  MEDIA_JSON_LIST_RECORD,
+  MEDIA_YAML_VALUE,
+  MEDIA_YAML_RECORD,
+  MEDIA_YAML_LIST,
+  MEDIA_YAML_LIST_RECORD,
+  MEDIA_CSV,
+  MEDIA_CSV_LIST,
   MEDIA_MODEL_SPEC,
   MEDIA_MODEL_REPO,
   MEDIA_MODEL_DIM,
   MEDIA_DECISION,
-  MEDIA_DECISION_ARRAY,
+  MEDIA_TEXTABLE_PAGE,
   // Semantic output types - model management
   MEDIA_DOWNLOAD_OUTPUT,
   MEDIA_LIST_OUTPUT,
@@ -5475,21 +5673,27 @@ module.exports = {
   // Semantic output types - inference
   MEDIA_EMBEDDING_VECTOR,
   MEDIA_LLM_INFERENCE_OUTPUT,
-  MEDIA_FILE_METADATA,
-  MEDIA_DOCUMENT_OUTLINE,
-  MEDIA_DISBOUND_PAGE,
   MEDIA_IMAGE_DESCRIPTION,
   MEDIA_TRANSCRIPTION_OUTPUT,
   // File path types
   MEDIA_FILE_PATH,
   MEDIA_FILE_PATH_ARRAY,
-  // Semantic text input types
-  MEDIA_FRONTMATTER_TEXT,
   MEDIA_MLX_MODEL_PATH,
+  // Collection types
+  MEDIA_COLLECTION,
+  MEDIA_COLLECTION_LIST,
+  MEDIA_ADAPTER_SELECTION,
+  // Standard cap URN constants
+  CAP_ADAPTER_SELECTION,
+  // Cap execution result
+  CapResult,
   // Unified argument type
   CapArgumentValue,
   // Standard cap URN builders
-  llmConversationUrn,
+  llmGenerateTextUrn,
+  renderPageImageUrn,
+  formatConversionUrn,
+  mediaUrnForType,
   modelAvailabilityUrn,
   modelPathUrn,
   CapMatrixError,