capdag 1.219.594 → 1.222.603

package/capdag.js

@@ -5876,10 +5876,11 @@ function unixSecondsNow() {
 }
 
 // Default protocol limits / version, mirroring capdag::bifaci::frame.
-const BIFACI_PROTOCOL_VERSION = 2;
+const BIFACI_PROTOCOL_VERSION = 3;
 const BIFACI_DEFAULT_MAX_FRAME = 3670016;
 const BIFACI_DEFAULT_MAX_CHUNK = 262144;
 const BIFACI_DEFAULT_MAX_REORDER_BUFFER = 64;
+const BIFACI_DEFAULT_INITIAL_CREDIT = 32;
 const BIFACI_FRAME_TYPE_HELLO = 0;
 // Frame CBOR integer keys (capdag::bifaci::frame::keys).
 const BIFACI_KEY_VERSION = 0;
@@ -6008,6 +6009,7 @@ function encodeHelloFrame() {
       ['max_frame', BIFACI_DEFAULT_MAX_FRAME],
       ['max_chunk', BIFACI_DEFAULT_MAX_CHUNK],
       ['max_reorder_buffer', BIFACI_DEFAULT_MAX_REORDER_BUFFER],
+      ['initial_credit', BIFACI_DEFAULT_INITIAL_CREDIT],
       ['version', BIFACI_PROTOCOL_VERSION],
     ],
   };
@@ -6825,6 +6827,88 @@ class Machine {
     return bracketed ? lines.join('') : lines.join('\n');
   }
 
+  /**
+   * Serialize to machine notation rendering each cap by its registered display
+   * alias (shortest name, ties alphabetical) when one exists, falling back to
+   * the canonical-URN `edge_N` header form otherwise. This is the "store
+   * aliased" form: generated and persisted machines use it so the saved
+   * notation reads in terms of aliases.
+   *
+   * Semantics (mirrors Rust Machine::to_machine_notation_aliased):
+   *  - A cap WITH a display alias is referenced DIRECTLY in the wiring's
+   *    cap-position by its alias name, with NO `[edge_N cap:...]` header (the
+   *    grammar forbids an alias in a header's cap position anyway, and a header
+   *    would be redundant).
+   *  - A cap WITHOUT an alias keeps the synthetic `edge_N` wiring token plus its
+   *    `[edge_N cap:...]` header binding it to the canonical cap URN.
+   *
+   * The canonical `edge_N` numbering and node naming are inherited unchanged
+   * from the canonical serializer, so an un-aliased machine produces byte-
+   * identical output to toMachineNotationFormatted.
+   *
+   * @param {FabricRegistryClient} registry - resolves URN → display alias
+   * @param {'bracketed' | 'line-based'} format
+   * @returns {string}
+   */
+  toMachineNotationAliased(registry, format) {
+    if (this._edges.length === 0) {
+      return '';
+    }
+
+    const { aliases, nodeNames, edgeOrder } = this._buildSerializationMaps();
+    const bracketed = format === 'bracketed';
+    const open = bracketed ? '[' : '';
+    const close = bracketed ? ']' : '';
+
+    // Resolve, per edge index, the cap-position token and whether it needs a
+    // header. An aliased cap uses its display alias directly (no header); an
+    // un-aliased cap keeps its synthetic `edge_N` token (with a header).
+    const edgeToken = new Map();   // edgeIdx → token used in the wiring
+    const edgeNeedsHeader = new Map(); // edgeIdx → bool
+    for (const [edgeAlias, info] of aliases) {
+      const edge = this._edges[info.edgeIdx];
+      const displayAlias = registry.displayAliasForUrn(edge.capUrn.toString());
+      if (displayAlias !== null && displayAlias !== undefined) {
+        edgeToken.set(info.edgeIdx, displayAlias);
+        edgeNeedsHeader.set(info.edgeIdx, false);
+      } else {
+        edgeToken.set(info.edgeIdx, edgeAlias);
+        edgeNeedsHeader.set(info.edgeIdx, true);
+      }
+    }
+
+    const lines = [];
+
+    // Headers only for edges that kept a synthetic `edge_N` token (un-aliased
+    // caps). Emit in alias-sorted order to match the canonical serializer.
+    const sortedAliases = Array.from(aliases.entries()).sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    for (const [, info] of sortedAliases) {
+      if (edgeNeedsHeader.get(info.edgeIdx)) {
+        const edge = this._edges[info.edgeIdx];
+        lines.push(`${open}${edgeToken.get(info.edgeIdx)} ${edge.capUrn}${close}`);
+      }
+    }
+
+    // Wirings in canonical edge order, using the resolved cap-position token.
+    for (const edgeIdx of edgeOrder) {
+      const edge = this._edges[edgeIdx];
+      const token = edgeToken.get(edgeIdx);
+
+      const sources = edge.sources.map(s => nodeNames.get(s.toString()));
+      const targetName = nodeNames.get(edge.target.toString());
+      const loopPrefix = edge.isLoop ? 'LOOP ' : '';
+
+      if (sources.length === 1) {
+        lines.push(`${open}${sources[0]} -> ${loopPrefix}${token} -> ${targetName}${close}`);
+      } else {
+        const group = sources.join(', ');
+        lines.push(`${open}(${group}) -> ${loopPrefix}${token} -> ${targetName}${close}`);
+      }
+    }
+
+    return bracketed ? lines.join('') : lines.join('\n');
+  }
+
   /**
    * Build the alias map, node name map, and edge ordering for serialization.
    *
@@ -7413,6 +7497,12 @@ class FabricRegistryClient {
     // canonical key only needs to be unique per equivalence class; we
     // store one entry per equivalence class.
     this._mediaCache = new Map();
+    // Normalized alias name → StoredAlias. Mirrors Rust
+    // FabricRegistry::cached_aliases. The display/serialization surfaces
+    // read this synchronously; it is warmed by insertCachedAliasForTest (and,
+    // in the heavier mirrors, a background prefetch this lightweight client
+    // does not implement).
+    this._cachedAliases = new Map();
   }
 
   /**
@@ -7542,12 +7632,88 @@ class FabricRegistryClient {
     return Array.from(ops).sort();
   }
 
+  /**
+   * Insert an alias directly into the in-memory cache, keyed by its
+   * normalized name. Mirrors Rust
+   * FabricRegistry::insert_cached_alias_for_test — it is the warm-cache seam
+   * the display/serialization primitives read from. The lightweight JS client
+   * has no background alias prefetch, so callers seed the cache through here.
+   *
+   * @param {StoredAlias} alias
+   */
+  insertCachedAliasForTest(alias) {
+    const normalized = normalizeAliasName(alias.name);
+    this._cachedAliases.set(normalized, alias);
+  }
+
+  /**
+   * Reverse lookup: the display alias for a `cap:`/`media:` URN, or null if no
+   * cached alias points at it. This is the canonical primitive every UI surface
+   * and notation generator uses to render an aliased name in place of a raw URN.
+   *
+   * The query URN is canonicalised through its own parser (cap vs media by
+   * prefix) before matching, because alias targets are stored canonically — a
+   * non-canonical query (different tag order, redundant whitespace) would
+   * otherwise miss. A URN that is neither a cap nor a media URN, or that fails
+   * to parse, returns null (it cannot have an alias).
+   *
+   * When multiple aliases target the same URN, the winner is the SHORTEST name,
+   * ties broken alphabetically (see selectDisplayAlias). This is deterministic
+   * and stable across processes for a given alias set.
+   *
+   * Mirrors Rust FabricRegistry::display_alias_for_urn.
+   * @param {string} urn
+   * @returns {string|null}
+   */
+  displayAliasForUrn(urn) {
+    // Canonicalise by kind. classifyAliasTarget keys off the parser (cap vs
+    // media), the same classifier the alias publisher uses for targets, so a
+    // query and a stored target canonicalise identically.
+    const kind = classifyAliasTarget(urn);
+    let canonical;
+    if (kind === ALIAS_TARGET_CAP) {
+      canonical = CapUrn.fromString(urn).toString();
+    } else if (kind === ALIAS_TARGET_MEDIA) {
+      canonical = MediaUrn.fromString(urn).toString();
+    } else {
+      return null;
+    }
+
+    const names = [];
+    for (const alias of this._cachedAliases.values()) {
+      if (alias.target === canonical) {
+        names.push(alias.name);
+      }
+    }
+    return selectDisplayAlias(names);
+  }
+
+  /**
+   * All cached aliases whose target is a CAP URN, as [name, capUrn] pairs.
+   * Used by the notation editor to offer registered cap aliases as wiring
+   * completions. Order is unspecified (the caller sorts/filters). Synchronous,
+   * cache-only — relies on the alias cache having been warmed.
+   *
+   * Mirrors Rust FabricRegistry::cached_cap_aliases.
+   * @returns {Array<[string, string]>}
+   */
+  cachedCapAliases() {
+    const pairs = [];
+    for (const alias of this._cachedAliases.values()) {
+      if (classifyAliasTarget(alias.target) === ALIAS_TARGET_CAP) {
+        pairs.push([alias.name, alias.target]);
+      }
+    }
+    return pairs;
+  }
+
   /**
    * Invalidate all caches. Next call to any method fetches fresh data.
    */
   invalidate() {
     this._capCache = null;
     this._mediaCache.clear();
+    this._cachedAliases.clear();
   }
 }
 
@@ -7620,6 +7786,34 @@ function classifyAliasTarget(target) {
   return null;
 }
 
+/**
+ * Pick the display alias from a set of alias names that all target the same
+ * URN: the SHORTEST name, ties broken alphabetically. Returns null for an
+ * empty set.
+ *
+ * The ordering is total and deterministic: (length, name) lexicographic. So
+ * `png` beats `png-image` (shorter), and between equal-length `a16` / `a09`
+ * the alphabetical-smaller `a09` wins. Stable across processes for a given
+ * alias set, which is what makes aliased UI/notation reproducible.
+ *
+ * Mirrors Rust select_display_alias.
+ * @param {Iterable<string>} names
+ * @returns {string|null}
+ */
+function selectDisplayAlias(names) {
+  let best = null;
+  for (const name of names) {
+    if (
+      best === null ||
+      name.length < best.length ||
+      (name.length === best.length && name < best)
+    ) {
+      best = name;
+    }
+  }
+  return best;
+}
+
 /**
  * The published wire/cache shape of a single fabric alias. Mirrors
  * fabric/alias.schema.json: { name, target, version }.
@@ -7682,6 +7876,7 @@ module.exports = {
   isAliasToken,
   normalizeAliasName,
   classifyAliasTarget,
+  selectDisplayAlias,
   StoredAlias,
   Manifest,
   CapUrn,

package/capdag.test.js

@@ -36,6 +36,7 @@ const {
   CAP_IDENTITY,
   ALIAS_TARGET_CAP, ALIAS_TARGET_MEDIA,
   tokenIsUrn, isAliasToken, normalizeAliasName, classifyAliasTarget,
+  selectDisplayAlias,
   StoredAlias, Manifest
 } = require('./capdag.js');
 
@@ -6383,6 +6384,107 @@ function test1887_manifestSerdeRoundTripsAliases() {
   assertEqual(JSON.stringify(a.toJSON()), '{"name":"pdf2text","target":"cap:effect=none","version":3}', 'alias wire shape');
 }
 
+// TEST1894: selectDisplayAlias picks the SHORTEST name, ties broken
+// alphabetically. This is the deterministic ordering every aliased-display
+// surface relies on; a regression here silently changes which alias the whole
+// UI renders.
+function test1894_selectDisplayAliasOrdering() {
+  // Shorter wins over longer regardless of alphabetical order.
+  assertEqual(selectDisplayAlias(['png-image', 'png', 'image-png']), 'png', 'shortest wins');
+  // Equal length → alphabetical (a09 < a16).
+  assertEqual(selectDisplayAlias(['a16', 'a09', 'a12']), 'a09', 'tie → alphabetical');
+  // Single candidate returns itself.
+  assertEqual(selectDisplayAlias(['solo']), 'solo', 'single candidate');
+  // Empty set → null.
+  assertEqual(selectDisplayAlias([]), null, 'empty → null');
+}
+
+// TEST1895: displayAliasForUrn reverse-resolves a URN to its display alias.
+// Proves: (1) the shortest-then-alphabetical winner among multiple aliases on
+// the same target, (2) a NON-canonical query URN (different tag order) still
+// resolves because the query is canonicalised before matching, (3) a URN with
+// no alias returns null, (4) a non-URN string returns null.
+function test1895_displayAliasForUrn() {
+  const registry = new FabricRegistryClient();
+  const capTarget = CapUrn.fromString('cap:coerce;in="media:integer;numeric";out="media:enc=utf-8"').toString();
+  // Two aliases on the same cap target; "i2s" is shorter than "int2str".
+  registry.insertCachedAliasForTest(new StoredAlias('int2str', capTarget, 1));
+  registry.insertCachedAliasForTest(new StoredAlias('i2s', capTarget, 1));
+  // A media alias too. Stored canonically.
+  const jsonTarget = MediaUrn.fromString('media:fmt=json;record').toString();
+  registry.insertCachedAliasForTest(new StoredAlias('json', jsonTarget, 1));
+
+  // Canonical query → shortest alias wins.
+  assertEqual(
+    registry.displayAliasForUrn('cap:coerce;in="media:integer;numeric";out="media:enc=utf-8"'),
+    'i2s', 'shortest cap alias wins');
+  // NON-canonical query (media tags reordered) must still resolve via
+  // canonicalisation.
+  assertEqual(registry.displayAliasForUrn('media:record;fmt=json'), 'json',
+    'non-canonical media query canonicalises');
+  // A real URN with no alias → null.
+  assertEqual(registry.displayAliasForUrn('media:enc=utf-8;ext=pdf'), null, 'no alias → null');
+  // A non-URN (no cap:/media: prefix) → null, never a throw.
+  assertEqual(registry.displayAliasForUrn('int2str'), null, 'non-URN → null');
+}
+
+// TEST1896: cachedCapAliases returns only CAP-targeted aliases as [name,
+// target] pairs — media aliases are excluded. Drives the notation editor's
+// registered-alias completions.
+function test1896_cachedCapAliasesFiltersToCapTargets() {
+  const registry = new FabricRegistryClient();
+  const capTarget = CapUrn.fromString('cap:coerce;in="media:integer;numeric";out="media:enc=utf-8"').toString();
+  registry.insertCachedAliasForTest(new StoredAlias('int2str', capTarget, 1));
+  registry.insertCachedAliasForTest(new StoredAlias('json', MediaUrn.fromString('media:fmt=json;record').toString(), 1));
+  const capAliases = registry.cachedCapAliases();
+  assertEqual(capAliases.length, 1, 'only the cap alias is returned');
+  assertEqual(capAliases[0][0], 'int2str', 'pair name');
+  assertEqual(capAliases[0][1], capTarget, 'pair target');
+}
+
+// TEST1196: toMachineNotationAliased references an aliased cap DIRECTLY in the
+// wiring by its display alias (shortest, then alphabetical) with NO header, and
+// keeps the synthetic `edge_N` token + header for a cap that has no alias.
+function test1196_aliasedSerializationUsesAliasAndDropsHeader() {
+  const registry = new FabricRegistryClient();
+  const m = Machine.fromString(
+    '[extract cap:in="media:ext=pdf";extract;out="media:enc=utf-8;ext=txt"]' +
+    '[embed cap:in="media:enc=utf-8;ext=txt";embed;out="media:embedding-vector;enc=utf-8;record"]' +
+    '[doc -> extract -> text]' +
+    '[text -> embed -> vectors]'
+  );
+  // Canonical target strings for the two caps, exactly as the serializer keys.
+  const extractTarget = m.edges().find(e => e.capUrn.toString().includes('extract')).capUrn.toString();
+  // Two aliases on the extract cap; "ex" is shorter than "extract-pdf".
+  registry.insertCachedAliasForTest(new StoredAlias('extract-pdf', extractTarget, 1));
+  registry.insertCachedAliasForTest(new StoredAlias('ex', extractTarget, 1));
+  // No alias for the embed cap → it must stay a raw URN with a header.
+
+  const aliased = m.toMachineNotationAliased(registry, 'bracketed');
+
+  // The extract cap is aliased: referenced directly in the wiring by its
+  // SHORTER alias `ex`, with NO header, and its URN must not appear.
+  assert(aliased.includes('-> ex ->'),
+    `extract cap must be referenced by shortest alias 'ex', got: ${aliased}`);
+  assert(!aliased.includes('extract;out'),
+    `the aliased extract cap URN must not appear, got: ${aliased}`);
+  // The longer alias must not be chosen.
+  assert(!aliased.includes('extract-pdf'),
+    `the longer alias must not be used, got: ${aliased}`);
+  // The un-aliased embed cap keeps its synthetic header binding `edge_N` to the
+  // canonical embed URN.
+  assert(/\[edge_\d+ cap:.*embed/.test(aliased),
+    `the un-aliased embed cap must keep its header URN, got: ${aliased}`);
+
+  // An un-aliased machine (empty registry) is byte-identical to the canonical
+  // formatted form — the aliased path adds nothing when no alias exists.
+  const empty = new FabricRegistryClient();
+  assertEqual(
+    m.toMachineNotationAliased(empty, 'bracketed'),
+    m.toMachineNotationFormatted('bracketed'),
+    'no aliases → identical to canonical bracketed form');
+}
+
 // ============================================================================
 // Test runner
 // ============================================================================
@@ -6849,6 +6951,12 @@ async function runTests() {
   runTest('TEST1882: classify_alias_target_by_prefix',      test1882_classifyAliasTargetByPrefix);
   runTest('TEST1887: manifest_serde_round_trips_aliases',   test1887_manifestSerdeRoundTripsAliases);
 
+  console.log('\n--- URN→alias display + aliased serialization (test1894–test1896, test1196) ---');
+  runTest('TEST1894: select_display_alias_ordering',         test1894_selectDisplayAliasOrdering);
+  runTest('TEST1895: display_alias_for_urn',                 test1895_displayAliasForUrn);
+  runTest('TEST1896: cached_cap_aliases_filters_to_cap',     test1896_cachedCapAliasesFiltersToCapTargets);
+  runTest('TEST1196: aliased_serialization_uses_alias',      test1196_aliasedSerializationUsesAliasAndDropsHeader);
+
   // Summary
   console.log(`\n${passCount + failCount} tests: ${passCount} passed, ${failCount} failed`);
   if (failCount > 0) {

package/package.json

@@ -40,5 +40,5 @@
     "pretest": "npm run build:parser",
     "test": "node capdag.test.js"
   },
-  "version": "1.219.594"
+  "version": "1.222.603"
 }