capdag 1.248.10 → 1.255.27

package/README.md

@@ -1,131 +1,64 @@
-# Cap URN - JavaScript Implementation
+# CapDAG for JavaScript
 
-JavaScript implementation of Cap URN (Capability Uniform Resource Names), built on [Tagged URN](https://github.com/machinefabric/tagged-urn-js).
+This public package is CapDAG's JavaScript planning and notation mirror. Use it
+in browsers or Node.js for Tagged, Media, and Cap URNs, capability definitions,
+dispatch, Machine Notation, planning, and graph rendering.
 
-## Features
+JavaScript intentionally does not implement the cartridge runtime, host, relay,
+or Bifaci process surface. That boundary is part of the package design, not an
+unreported parity gap. Rust remains the behavioral reference for shared
+features.
 
-- **Required Direction Specifiers** - `in`/`out` tags for input/output media types
-- **Media URN Validation** - Validates direction spec values are valid Media URNs
-- **Special Pattern Values** - `*` (must-have-any), `?` (unspecified), `!` (must-not-have)
-- **Graded Specificity** - Exact values score higher than wildcards
-- **Cross-Language Compatible** - Identical behavior to Rust, Go, and Objective-C implementations
-- **Production Ready** - No fallbacks, fails hard on invalid input
-
-## Installation
+## Install the package
 
 ```bash
 npm install capdag
 ```
 
-## Quick Start
+Node.js 14 or newer is required by the package manifest.
 
-```javascript
-const { CapUrn, CapUrnBuilder, CapMatcher } = require('capdag');
+## Parse and build Cap URNs
 
-// Create from string (with required direction specifiers)
-const cap = CapUrn.fromString('cap:in="media:binary";extract;out="media:object"');
-console.log(cap.toString());
+```javascript
+const { CapUrn, CapUrnBuilder } = require("capdag");
 
-// Use builder pattern
+const parsed = CapUrn.fromString(
+  'cap:disbind;in="media:ext=pdf";out="media:enc=utf-8;page"'
+);
 const built = new CapUrnBuilder()
-  .inSpec('media:void')
-  .outSpec('media:object')
-  .tag('op', 'generate')
-  .tag('target', 'thumbnail')
-  .build();
-
-// Matching
-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=*;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
-```
-
-## API Reference
-
-### CapUrn Class
-
-#### Static Methods
-- `CapUrn.fromString(s)` - Parse Cap URN from string
-  - Throws `CapUrnError` on invalid format or missing direction specifiers
-
-#### Instance Methods
-- `toString()` - Get canonical string representation
-- `getTag(key)` - Get tag value (case-insensitive)
-- `getInSpec()` - Get input media type
-- `getOutSpec()` - Get output media type
-- `hasTag(key, value)` - Check if tag exists with value
-- `withTag(key, value)` - Add/update tag (returns new instance)
-- `withoutTag(key)` - Remove tag (returns new instance)
-- `accepts(request)` - Check if this cap (as pattern) accepts a request
-- `specificity()` - Get specificity score for matching
-- `isMoreSpecificThan(other)` - Compare specificity
-- `equals(other)` - Check equality
-
-### CapUrnBuilder Class
-
-Fluent builder for constructing Cap URNs:
-
-```javascript
-const cap = new CapUrnBuilder()
-  .inSpec('media:binary')
-  .outSpec('media:object')
-  .tag('op', 'extract')
-  .tag('target', 'metadata')
+  .inSpec("media:ext=pdf")
+  .outSpec("media:enc=utf-8;page")
+  .marker("disbind")
   .build();
-```
 
-### CapMatcher Class
-
-Utility for matching sets of caps:
-
-- `CapMatcher.findBestMatch(caps, request)` - Find most specific match
-- `CapMatcher.findAllMatches(caps, request)` - Find all matches (sorted by specificity)
-
-### Error Handling
-
-```javascript
-const { CapUrnError, ErrorCodes } = require('capdag');
-
-try {
-  const cap = CapUrn.fromString('cap:extract;in=media:;out=media:'); // Missing in/out
-} catch (error) {
-  if (error instanceof CapUrnError) {
-    console.log(`Error code: ${error.code}`); // MISSING_IN_SPEC
-  }
-}
+console.log(parsed.toString() === built.toString());
 ```
 
-Cap-specific error codes:
-- `ErrorCodes.MISSING_IN_SPEC` - Missing required `in` tag
-- `ErrorCodes.MISSING_OUT_SPEC` - Missing required `out` tag
-- `ErrorCodes.INVALID_MEDIA_URN` - Invalid Media URN in direction spec
+Treat URNs as opaque parsed values. Use the package's predicates for
+equivalence, conformance, dispatch, and ranking instead of string surgery.
 
-For base Tagged URN error codes, see [Tagged URN documentation](https://github.com/machinefabric/tagged-urn-js).
+## Find the relevant API
 
-## Documentation
+- `capdag.js` provides URNs, definitions, dispatch, and matching.
+- `machine-parser.js` is generated from `machine.pegjs`.
+- `planner.js` provides planning and Machine Notation structures.
+- `cap-fab-renderer.js` and the browser build support graph presentation.
+- [`RULES.md`](RULES.md) records package-specific construction rules.
 
-- [RULES.md](./RULES.md) - Cap-specific rules
-- [Tagged URN RULES.md](https://github.com/machinefabric/tagged-urn-js/blob/main/RULES.md) - Base format rules (case, quoting, wildcards, etc.)
+The normative semantics and terminology live in the
+[CapDAG specification](https://github.com/machinefabric/capdag/blob/main/docs/01-overview.md). Source comments and
+exports are the JavaScript API reference.
 
-## Testing
+## Build and verify changes
 
 ```bash
+npm run build:parser
 npm test
 ```
 
-## Cross-Language Compatibility
+`npm test` runs the parser build first. Shared behavior changes require the
+applicable reference test with the same substantive number and assertions.
 
-This JavaScript implementation produces identical results to:
-- [Rust reference implementation](https://github.com/machinefabric/capdag)
-- [Go implementation](https://github.com/machinefabric/capdag-go)
-- [Objective-C implementation](https://github.com/machinefabric/capdag-objc)
+## License
 
-All implementations pass the same test cases and follow identical rules.
+MIT

package/cap-fab-renderer.js

@@ -2234,8 +2234,7 @@ function buildRunGraphData(data) {
     };
   }
 
-  // Expanding. The plan mirrors the working
-  // `machfab-mac/.scrap/working_graph/.../RunGraphViewer.html`:
+  // Expanding. The plan uses the renderer's established fan-out layout:
   //
   //   pre-foreach backbone ... → [anchor]
   //                                 │

package/capdag.js

@@ -5603,9 +5603,12 @@ function slugForSync(registryUrl) {
 }
 
 /**
- * How a cartridge was installed. Pure metadata — never consulted for any host
- * or engine routing decision. Mirrors Rust CartridgeInstallSource; the
- * on-disk JSON uses snake_case values.
+ * How a cartridge was installed. Exactly ONE value is semantic: BUNDLE
+ * selects the bundled-cartridge integrity path at discovery. Every other
+ * value is provenance telemetry, and the vocabulary GROWS as installers do —
+ * so an unrecognized spelling is preserved verbatim on the record and
+ * round-trips, never failing the cartridge.json parse. Mirrors Rust
+ * CartridgeInstallSource; the on-disk JSON uses snake_case values.
  */
 const CartridgeInstallSource = Object.freeze({
   REGISTRY: 'registry',
@@ -5744,10 +5747,12 @@ class CartridgeJson {
     }
     let installedFrom = null;
     if (obj.installed_from !== undefined && obj.installed_from !== null) {
-      const valid = Object.values(CartridgeInstallSource);
-      if (!valid.includes(obj.installed_from)) {
-        throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, `cartridge.json unknown installed_from: ${obj.installed_from}`);
+      if (typeof obj.installed_from !== 'string') {
+        throw new CartridgeJsonError(CartridgeJsonErrorKind.INVALID_JSON, 'cartridge.json installed_from must be a string');
       }
+      // An unknown spelling is preserved VERBATIM: the provenance vocabulary
+      // grows as installers do, and a telemetry hint must never fail the
+      // parse and take the cartridge down with it. Only BUNDLE is semantic.
       installedFrom = obj.installed_from;
     }
     return new CartridgeJson({
@@ -6150,7 +6155,6 @@ function encodeHelloFrame() {
       ['max_reorder_buffer', BIFACI_DEFAULT_MAX_REORDER_BUFFER],
       ['initial_credit', BIFACI_DEFAULT_INITIAL_CREDIT],
       ['version', BIFACI_PROTOCOL_VERSION],
-      ['handler_capacity', 0],
     ],
   };
   const frame = {
@@ -6265,9 +6269,21 @@ function probeCartridgeCapGroups(entryPath) {
         finish(new Error(`cartridge ${entryPath} HELLO failed: meta.version ${metaVersion} does not match required version ${BIFACI_PROTOCOL_VERSION}`));
         return;
       }
-      const handlerCapacity = meta.get('handler_capacity');
-      if (!Number.isSafeInteger(handlerCapacity) || handlerCapacity < 0) {
-        finish(new Error(`cartridge ${entryPath} HELLO failed: missing required non-negative handler_capacity`));
+      // The concurrency-pool state map is MANDATORY on a cartridge HELLO
+      // (bifaci pools, protocol v4): JSON bytes under meta key "pools". A
+      // missing or malformed map is a protocol violation, never a default.
+      const poolsVal = meta.get('pools');
+      if (!poolsVal || poolsVal.__bytes === undefined) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: missing required concurrency-pool state map`));
+        return;
+      }
+      try {
+        const poolStates = JSON.parse(Buffer.from(poolsVal.__bytes).toString('utf8'));
+        if (poolStates === null || typeof poolStates !== 'object' || Array.isArray(poolStates)) {
+          throw new Error('pool-state map must be a JSON object');
+        }
+      } catch (e) {
+        finish(new Error(`cartridge ${entryPath} HELLO failed: malformed pool-state map: ${e.message}`));
         return;
       }
       const manifestVal = meta.get('manifest');

package/capdag.test.js

@@ -6965,6 +6965,40 @@ function assertThrowsPlanState(fn, message) {
 
 // TEST1450: a defaults-only request is AUTO with every knob at its default,
 // and the proto JSON carries the documented wire shape.
+// TEST1514: the provenance vocabulary grows with installers. A workspace
+// build install parses to its named value; a spelling this build does not
+// know parses, is preserved VERBATIM, round-trips, and is not BUNDLE (the
+// one semantic value) — an unknown telemetry hint can never fail the
+// cartridge.json parse and take the cartridge down with it.
+function test1514_installSourceVocabularyTolerance() {
+  const base = {
+    name: 'candlecartridge',
+    version: '1.227.800',
+    channel: 'nightly',
+    registry_url: 'https://cartridges-staging.machinefabric.com/v1/manifest',
+    entry: 'candlecartridge',
+    installed_at: '2026-08-14T22:26:59Z',
+    fabric_manifest_version: 4,
+  };
+  // A drifted installer's spelling is tolerated but NOT blessed: the
+  // protocol's vocabulary is registry/dev/bundle/app_installer, and a
+  // writer's mistake never becomes a named value.
+  const built = CartridgeJson.fromObject({ ...base, installed_from: 'build' });
+  assert(built.installedFrom === 'build',
+    `build is preserved verbatim like any unknown, got ${built.installedFrom}`);
+  assert(!Object.values(CartridgeInstallSource).includes('build'),
+    'build is not part of the protocol vocabulary');
+
+  const unknown = CartridgeJson.fromObject({ ...base, installed_from: 'quantum_courier' });
+  assert(unknown.installedFrom === 'quantum_courier',
+    `unknown spellings are preserved verbatim, got ${unknown.installedFrom}`);
+  assert(unknown.installedFrom !== CartridgeInstallSource.BUNDLE,
+    'an unknown spelling is never the semantic bundle value');
+  const rewritten = unknown.toObject ? unknown.toObject() : JSON.parse(JSON.stringify(unknown));
+  assert((rewritten.installed_from || rewritten.installedFrom) === 'quantum_courier',
+    'unknown spellings round-trip');
+}
+
 function test1450_planRequestDefaults() {
   const request = new plannerNS.PlanRequest({
     sources: [{ mediaUrn: 'media:ext=pdf', isSequence: false }],
@@ -7589,6 +7623,7 @@ async function runTests() {
 
   // planner.js: unified plan-space vocabulary
   console.log('--- planner.js ---');
+  runTest('TEST1514: install_source_vocabulary_tolerance', test1514_installSourceVocabularyTolerance);
   runTest('TEST1450: plan_request_defaults', test1450_planRequestDefaults);
   runTest('TEST1451: plan_request_knob_validation', test1451_planRequestKnobValidation);
   runTest('TEST1452: knob_proto_round_trip', test1452_knobProtoRoundTrip);

package/package.json

@@ -41,5 +41,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "1.248.10"
+  "version": "1.255.27"
 }