capdag 0.158.370 → 0.162.386

package/README.md

@@ -23,7 +23,7 @@ npm install capdag
 const { CapUrn, CapUrnBuilder, CapMatcher } = require('capdag');
 
 // Create from string (with required direction specifiers)
-const cap = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+const cap = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
 console.log(cap.toString());
 
 // Use builder pattern
@@ -35,14 +35,14 @@ const built = new CapUrnBuilder()
   .build();
 
 // Matching
-const request = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+const request = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
 console.log(cap.accepts(request)); // true
 
 // Find best match by specificity
 const caps = [
-  CapUrn.fromString('cap:in=*;op=extract;out=*'),
-  CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"'),
-  CapUrn.fromString('cap:ext=pdf;in="media:binary";op=extract;out="media:object"')
+  CapUrn.fromString('cap:in=*;extract;out=*'),
+  CapUrn.fromString('cap:in="media:binary";extract;out="media:object"'),
+  CapUrn.fromString('cap:ext=pdf;in="media:binary";extract;out="media:object"')
 ];
 const best = CapMatcher.findBestMatch(caps, request);
 console.log(best.toString()); // Most specific match

package/RULES.md

@@ -14,7 +14,7 @@ Cap URNs **must** include `in` and `out` tags that specify input/output media ty
 
 ```javascript
 // Valid cap URN with direction specifiers
-const cap = CapUrn.fromString('cap:in="media:binary";op=extract;out="media:object"');
+const cap = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
 
 // Invalid - missing direction specifiers
 CapUrn.fromString('cap:op=extract'); // throws ErrorCodes.MISSING_IN_SPEC
@@ -26,13 +26,13 @@ Direction specifier values must be valid Media URNs or special pattern values:
 
 ```javascript
 // Valid: Media URN value
-'cap:in="media:binary";op=extract;out="media:object"'
+'cap:in="media:binary";extract;out="media:object"'
 
 // Valid: Must-have-any (any media type)
-'cap:in=*;op=extract;out=*'
+'cap:in=*;extract;out=*'
 
 // Invalid: Not a Media URN or special value
-'cap:in=binary;op=extract;out=object' // throws ErrorCodes.INVALID_MEDIA_URN
+'cap:in=binary;extract;out=object' // throws ErrorCodes.INVALID_MEDIA_URN
 ```
 
 ### 3. Matching Semantics
@@ -59,8 +59,8 @@ Specificity uses graded scoring:
 | Unspecified (K=?) or missing | 0 |
 
 Examples:
-- `cap:in="media:binary";op=extract;out="media:object"` → 3+3+3 = 9
-- `cap:in=*;op=extract;out=*` → 2+3+2 = 7
+- `cap:in="media:binary";extract;out="media:object"` → 3+3+3 = 9
+- `cap:in=*;extract;out=*` → 2+3+2 = 7
 
 ## Cap-Specific Error Codes
 

package/capdag.js

@@ -922,7 +922,7 @@ 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';
+const MEDIA_CSV_LIST = 'media:csv;list;record;textable';
 
 // File path type — for arguments that represent filesystem paths.
 // There is a single media URN; cardinality (single file vs many files)
@@ -4528,6 +4528,24 @@ class CartridgeRepoServer {
  * Reasons why a cartridge attachment attempt failed.
  * Mirrors Rust CartridgeAttachmentErrorKind.
  */
+const CartridgeLifecycle = Object.freeze({
+  // Discovery scan has found the version directory and is about
+  // to inspect it. Transient.
+  DISCOVERED: 'discovered',
+  // Reading cartridge.json, computing directory hash, validating
+  // on-disk install context. Hashing can take seconds for large
+  // model cartridges; runs on a background queue so other
+  // cartridges' inspections proceed in parallel.
+  INSPECTING: 'inspecting',
+  // Inspection succeeded; awaiting a verdict from the registry
+  // verifier service. Skipped for dev cartridges
+  // (registry_url == null) and bundle cartridges.
+  VERIFYING: 'verifying',
+  // Cleared every gate. Caps are registered with the engine and
+  // dispatch can route requests to this cartridge.
+  OPERATIONAL: 'operational',
+});
+
 const CartridgeAttachmentErrorKind = Object.freeze({
   INCOMPATIBLE: 'incompatible',
   MANIFEST_INVALID: 'manifest_invalid',
@@ -4636,9 +4654,9 @@ class CartridgeRuntimeStats {
 /**
  * Full identity of an installed cartridge, including optional attachment error
  * and runtime statistics.
- * Mirrors Rust InstalledCartridgeIdentity.
+ * Mirrors Rust InstalledCartridgeRecord.
  */
-class InstalledCartridgeIdentity {
+class InstalledCartridgeRecord {
   /**
    * @param {Object} opts
    * @param {string|null} [opts.registryUrl=null]
@@ -4646,17 +4664,21 @@ class InstalledCartridgeIdentity {
    * @param {string} opts.id
    * @param {string} opts.version
    * @param {string} opts.sha256
+   * @param {Array<Object>} [opts.capGroups=[]] - Cartridge's manifest cap_groups; each element is `{name, caps, adapter_urns}`.
    * @param {CartridgeAttachmentError|null} [opts.attachmentError=null]
    * @param {CartridgeRuntimeStats|null} [opts.runtimeStats=null]
+   * @param {string} [opts.lifecycle='discovered'] - One of `discovered` | `inspecting` | `verifying` | `operational`. Mutually exclusive with attachmentError; see `machfab-mac/docs/cartridge state machine.md`.
    */
-  constructor({ registryUrl = null, channel, id, version, sha256, attachmentError = null, runtimeStats = null }) {
+  constructor({ registryUrl = null, channel, id, version, sha256, capGroups = [], attachmentError = null, runtimeStats = null, lifecycle = 'discovered' }) {
     this.registry_url = registryUrl;
     this.channel = channel;
     this.id = id;
     this.version = version;
     this.sha256 = sha256;
+    this.cap_groups = capGroups;
     this.attachment_error = attachmentError;
     this.runtime_stats = runtimeStats;
+    this.lifecycle = lifecycle;
   }
 
   toJSON() {
@@ -4665,24 +4687,50 @@ class InstalledCartridgeIdentity {
       id: this.id,
       version: this.version,
       sha256: this.sha256,
+      lifecycle: this.lifecycle,
     };
     if (this.registry_url !== null) obj.registry_url = this.registry_url;
+    if (this.cap_groups && this.cap_groups.length > 0) obj.cap_groups = this.cap_groups;
     if (this.attachment_error !== null) obj.attachment_error = this.attachment_error.toJSON();
     if (this.runtime_stats !== null) obj.runtime_stats = this.runtime_stats.toJSON();
     return obj;
   }
 
   static fromJSON(d) {
-    return new InstalledCartridgeIdentity({
+    return new InstalledCartridgeRecord({
       registryUrl: d.registry_url !== undefined ? d.registry_url : null,
       channel: d.channel,
       id: d.id,
       version: d.version,
       sha256: d.sha256,
+      capGroups: Array.isArray(d.cap_groups) ? d.cap_groups : [],
       attachmentError: d.attachment_error ? CartridgeAttachmentError.fromJSON(d.attachment_error) : null,
       runtimeStats: d.runtime_stats ? CartridgeRuntimeStats.fromJSON(d.runtime_stats) : null,
+      // Default to 'discovered' (the safe sentinel) — never
+      // 'operational' — when the field is missing from the wire.
+      lifecycle: typeof d.lifecycle === 'string' ? d.lifecycle : 'discovered',
     });
   }
+
+  /**
+   * Flat de-duplicated cap-URN view across this cartridge's groups,
+   * preserving first-seen order.
+   * @returns {Array<string>}
+   */
+  capUrns() {
+    const seen = new Set();
+    const out = [];
+    for (const group of this.cap_groups) {
+      const caps = (group && Array.isArray(group.caps)) ? group.caps : [];
+      for (const cap of caps) {
+        const urn = (cap && typeof cap.urn === 'string') ? cap.urn : '';
+        if (!urn || seen.has(urn)) continue;
+        seen.add(urn);
+        out.push(urn);
+      }
+    }
+    return out;
+  }
 }
 
 // ============================================================================
@@ -5942,10 +5990,11 @@ module.exports = {
   CartridgeRepoServer,
   CartridgeChannel,
   // Bifaci — cartridge attachment & runtime identity
+  CartridgeLifecycle,
   CartridgeAttachmentErrorKind,
   CartridgeAttachmentError,
   CartridgeRuntimeStats,
-  InstalledCartridgeIdentity,
+  InstalledCartridgeRecord,
   // Registry slug
   DEV_SLUG,
   SLUG_HEX_LEN,