@dszp/netsapiens-lib 0.1.8 → 0.3.0

package/src/principal.selftest.ts

@@ -0,0 +1,118 @@
+/**
+ * Principal + policy engine proof, driven by two ns_t claim sets that mirror the shapes the real
+ * platform emits: a reseller acting as self (no mask), and a domain user being impersonated by a
+ * reseller (`mask_chain` set). Identities are fictional — the SHAPE is what's under test.
+ *
+ * The masked case is the interesting one: `sub`/`domain`/`user_scope` describe the MASKED user, while
+ * `mask_chain` carries the real operator behind the mask. Getting that backwards is the bug this
+ * fixture exists to catch.
+ *
+ * Run: `pnpm test:principal`.
+ */
+import { extractContext } from './jwt.js';
+import { toPrincipal, isResellerScope, isAdminScope } from './principal.js';
+import { can, isAllowed, type FeaturePolicies } from './policy.js';
+
+// Claim sets shaped exactly like the platform's, with fictional identities.
+const RESELLER_SELF = {
+  aud: 'ns', iss: 'manage.example.com', sub: 'admin@0000.12345.service',
+  domain: '0000.12345.service', territory: '12345.service', user: 'admin',
+  user_email: 'alex@acme42.example', user_scope: 'Reseller', displayName: 'Alex Reseller',
+  mask_chain: null,
+};
+const RESELLER_MASKED = {
+  aud: 'ns', iss: 'manage.example.com', sub: '100@acme',
+  domain: 'acme', territory: '12345.service', user: '100',
+  user_email: 'jordan@acme.example', user_scope: 'Office Manager', displayName: 'Jordan Manager',
+  mask_chain: 'operator@0000.12345.service',
+};
+
+const self = toPrincipal(extractContext(RESELLER_SELF as Record<string, unknown>));
+const masked = toPrincipal(extractContext(RESELLER_MASKED as Record<string, unknown>));
+
+let pass = 0, fail = 0;
+const check = (name: string, cond: boolean) => { cond ? (pass++, console.log('  ok   ' + name)) : (fail++, console.log('  FAIL ' + name)); };
+
+// ---- normalization ----
+check('self: not masking', self.masking === false && self.operator === null);
+check('self: reseller scope + id', self.scope === 'Reseller' && self.id === 'admin@0000.12345.service');
+check('self: domain', self.domain === '0000.12345.service');
+check('masked: masking flag', masked.masking === true);
+check('masked: effective is the masked user (acme/100/Office Manager)',
+  masked.domain === 'acme' && masked.user === '100' && masked.scope === 'Office Manager' && masked.id === '100@acme');
+check('masked: operator is the real reseller', masked.operator?.id === 'operator@0000.12345.service');
+check('masked: identity fields surfaced', masked.email === 'jordan@acme.example' && masked.displayName === 'Jordan Manager');
+
+// ---- scope helpers ----
+check('isResellerScope(self)', isResellerScope(self.scope) === true);
+check('isResellerScope(masked effective) is FALSE (scope reads Office Manager while masked)', isResellerScope(masked.scope) === false);
+check('isAdminScope(masked) true (Office Manager)', isAdminScope(masked.scope) === true);
+check('isResellerScope case-insensitive', isResellerScope('reseller') && isResellerScope('SUPER USER'));
+
+// ---- policy cases ----
+check('all resellers: self yes, masked no', isAllowed(self, [{ scopes: ['Reseller'] }]) && !isAllowed(masked, [{ scopes: ['Reseller'] }]));
+check('my reseller only: self yes',
+  isAllowed(self, [{ scopes: ['Reseller'], users: ['admin@0000.12345.service'] }]));
+check('my reseller only: a different reseller no',
+  !isAllowed({ ...self, id: 'someoneelse@0000.12345.service' }, [{ scopes: ['Reseller'], users: ['admin@0000.12345.service'] }]));
+check('office managers: masked yes, self no', isAllowed(masked, [{ scopes: ['Office Manager'] }]) && !isAllowed(self, [{ scopes: ['Office Manager'] }]));
+check('all users in acme: masked yes, self no', isAllowed(masked, [{ domains: ['acme'] }]) && !isAllowed(self, [{ domains: ['acme'] }]));
+check('domains with scope filter', isAllowed(masked, [{ domains: ['acme'], scopes: ['Office Manager', 'Basic User'] }]));
+check('specific users: masked yes', isAllowed(masked, [{ users: ['100@acme'] }]));
+check('operator gate (only when my reseller masked-in): masked yes, self no',
+  isAllowed(masked, [{ operators: ['operator@0000.12345.service'] }]) && !isAllowed(self, [{ operators: ['operator@0000.12345.service'] }]));
+check('masking:false rule: self yes, masked no', isAllowed(self, [{ masking: false }]) && !isAllowed(masked, [{ masking: false }]));
+check("domain '*' wildcard matches any", isAllowed(self, [{ domains: ['*'] }]) && isAllowed(masked, [{ domains: ['*'] }]));
+check('ANY-rule semantics (union of two rules)',
+  isAllowed(masked, [{ scopes: ['Reseller'] }, { domains: ['acme'] }]));
+check('empty policy denies', !isAllowed(self, []));
+check('conditionless rule does NOT match (no accidental allow-all)', !isAllowed(self, [{}]) && !isAllowed(self, [{ description: 'todo' }]));
+
+// ---- notUsers: the one negative condition ----
+const otherReseller = { ...self, id: 'other@0000.12345.service' };
+check('notUsers denies a principal the positive fields admit',
+  isAllowed(self, [{ scopes: ['Reseller'] }]) &&
+  !isAllowed(self, [{ scopes: ['Reseller'], notUsers: ['admin@0000.12345.service'] }]));
+check('notUsers leaves everyone else at that scope alone',
+  isAllowed(otherReseller, [{ scopes: ['Reseller'], notUsers: ['admin@0000.12345.service'] }]));
+check('notUsers is case-insensitive, like every other list',
+  !isAllowed(self, [{ scopes: ['Reseller'], notUsers: ['ADMIN@0000.12345.SERVICE'] }]));
+check('a negation-only rule never matches (no allow-all-but)',
+  !isAllowed(self, [{ notUsers: ['nobody@example.com'] }]) &&
+  !isAllowed(masked, [{ notUsers: ['nobody@example.com'] }]));
+// The deny narrows THE RULE IT SITS ON, not the policy — rules still OR. A caller that compiles a
+// "deny this account" intent into a policy must therefore put the negation on EVERY rule it emits;
+// leaving one rule bare re-admits the account through it. Asserted here so the property is pinned at
+// the engine rather than only in whichever consumer got the distribution right.
+// The one asymmetry in this engine: a grant follows the role being performed, a denial follows the
+// person. `masked` is 100@acme with operator@0000.12345.service behind the mask.
+check('notUsers denies the OPERATOR behind a mask, not only the account being acted as',
+  isAllowed(masked, [{ scopes: ['Office Manager'] }]) &&
+  !isAllowed(masked, [{ scopes: ['Office Manager'], notUsers: ['operator@0000.12345.service'] }]));
+check('notUsers still denies the effective identity while masked',
+  !isAllowed(masked, [{ scopes: ['Office Manager'], notUsers: ['100@acme'] }]));
+check('a mask by someone NOT denied is unaffected',
+  isAllowed(masked, [{ scopes: ['Office Manager'], notUsers: ['someoneelse@0000.12345.service'] }]));
+// Denying the operator must not leak into the unmasked case: `self` IS operator@… acting as themselves,
+// with no mask, so the deny bites through p.id — but a principal with no operator must never throw or
+// match on a missing field.
+check('an unmasked principal with no operator is judged on its own id alone',
+  isAllowed({ ...self, id: 'other@0000.12345.service' }, [{ scopes: ['Reseller'], notUsers: ['operator@0000.12345.service'] }]));
+check('notUsers is per-rule: a bare sibling rule still admits the denied account',
+  isAllowed(self, [
+    { scopes: ['Reseller'], notUsers: ['admin@0000.12345.service'] },
+    { users: ['admin@0000.12345.service'] },
+  ]));
+
+// ---- feature registry (fail-closed) ----
+const FEATURES: FeaturePolicies = {
+  'callflow.view': [{ scopes: ['Reseller'] }, { operators: ['operator@0000.12345.service'] }], // resellers, or my masked previews
+  'admin.publish': [{ scopes: ['Reseller', 'Super User'] }],
+};
+check('feature callflow.view: self(reseller) yes', can(self, 'callflow.view', FEATURES));
+check('feature callflow.view: masked-by-my-reseller yes (via operator rule)', can(masked, 'callflow.view', FEATURES));
+check('feature admin.publish: masked office-manager no', !can(masked, 'admin.publish', FEATURES));
+check('unknown feature denies (fail closed)', !can(self, 'does.not.exist', FEATURES));
+
+console.log(`\nprincipal.selftest: ${pass} passed, ${fail} failed`);
+if (fail > 0) process.exit(1);

package/src/principal.ts

@@ -0,0 +1,101 @@
+/**
+ * Normalize an ns_t JWT's claims into a `Principal` — the identity + role the portal authorizes
+ * against. Handles NetSapiens **masking** (impersonation): when a reseller/admin is masked-in as a
+ * domain user, the token's `domain`/`user`/`scope`/`sub` describe the MASKED user, while `mask_chain`
+ * names the real operator. `Principal` keeps both, plus a `masking` flag.
+ *
+ * Two things the caller must keep straight (see policy.ts):
+ *  - **Auth scope** (what data is reachable) follows the EFFECTIVE identity: a masked token is
+ *    NS-scoped to the masked user's domain; only an un-masked reseller/super-user reads cross-domain.
+ *  - **Role gating** may consider the OPERATOR (mask_chain) too — e.g. "allow my reseller while
+ *    developing" — since the effective scope reads "Office Manager" while masked.
+ *
+ * Portable (no Node). Pure functions.
+ */
+import type { JwtContext } from './jwt.js';
+
+/** Known NetSapiens user scopes (the string is open — unknown scopes pass through as-is). */
+export type Scope =
+  | 'Super User'
+  | 'Reseller'
+  | 'Office Manager'
+  | 'Site Manager'
+  | 'Call Center Supervisor'
+  | 'Call Center Agent'
+  | 'Basic User'
+  | (string & {});
+
+/** The real operator behind a mask (parsed from `mask_chain`). */
+export interface Operator {
+  /** `user@domain` (verbatim mask_chain, lowercased id below). */
+  raw: string;
+  user: string;
+  domain: string;
+  /** Lowercased `user@domain` for comparisons. */
+  id: string;
+}
+
+export interface Principal {
+  /** Effective domain — the masked user's when masking; the token is NS-scoped to it. */
+  domain: string;
+  /** Effective user / extension. */
+  user: string;
+  /** Effective identity `user@domain`, lowercased (from sub, or user+domain). */
+  id: string;
+  /** Effective user_scope (the masked user's scope when masking). */
+  scope: string;
+  email?: string;
+  displayName?: string;
+  territory?: string;
+  /** True when a mask is in effect (mask_chain present). */
+  masking: boolean;
+  /** The real operator behind the mask, or null when not masking. */
+  operator: Operator | null;
+}
+
+const lc = (s: string | undefined) => (s ?? '').trim().toLowerCase();
+
+/** Scopes that can read/act across the whole reseller/fleet (cross-domain). */
+const RESELLER_SCOPES = new Set(['reseller', 'super user', 'superuser', 'super-user']);
+/** Scopes with domain-admin authority (a superset that includes reseller-level). */
+const ADMIN_SCOPES = new Set([...RESELLER_SCOPES, 'office manager', 'site manager', 'call center supervisor']);
+
+/** Reseller / super-user — the only scopes that legitimately read cross-domain. */
+export function isResellerScope(scope: string | undefined): boolean {
+  return RESELLER_SCOPES.has(lc(scope));
+}
+/** Domain-admin-or-higher (office manager / site manager / supervisor / reseller / super user). */
+export function isAdminScope(scope: string | undefined): boolean {
+  return ADMIN_SCOPES.has(lc(scope));
+}
+
+/** Parse a `mask_chain` value ("user@domain") into an Operator, or null if empty/malformed. */
+export function parseOperator(maskChain: string | undefined): Operator | null {
+  const raw = (maskChain ?? '').trim();
+  if (!raw || !raw.includes('@')) return null;
+  const at = raw.lastIndexOf('@');
+  const user = raw.slice(0, at);
+  const domain = raw.slice(at + 1);
+  if (!user || !domain) return null;
+  return { raw, user, domain, id: `${user}@${domain}`.toLowerCase() };
+}
+
+/** Build a Principal from decoded ns_t context (a JwtContext / JwtVerdict — both carry the claims). */
+export function toPrincipal(ctx: JwtContext): Principal {
+  const domain = (ctx.domain ?? '').trim();
+  const user = (ctx.user ?? '').trim();
+  const sub = (ctx.sub ?? '').trim();
+  const id = (sub.includes('@') ? sub : user && domain ? `${user}@${domain}` : sub || user).toLowerCase();
+  const operator = parseOperator(ctx.maskChain);
+  return {
+    domain,
+    user,
+    id,
+    scope: (ctx.scope ?? '').trim(),
+    ...(ctx.email ? { email: ctx.email } : {}),
+    ...(ctx.displayName ? { displayName: ctx.displayName } : {}),
+    ...(ctx.territory ? { territory: ctx.territory } : {}),
+    masking: operator != null,
+    operator,
+  };
+}

package/src/raster.selftest.ts

@@ -0,0 +1,42 @@
+/**
+ * Proof for the browser PNG rasterizer's portable pieces. The size resolver is pure and unit-tested
+ * here; the full Image→canvas→PNG path is browser-only (validated via agent-browser, see the plan).
+ * Run: `pnpm test:raster`.
+ */
+import { resolveSvgSize, rasterizerScript } from './raster.js';
+
+let pass = 0, fail = 0;
+const check = (name: string, cond: boolean) => { cond ? (pass++, console.log('  ok   ' + name)) : (fail++, console.log('  FAIL ' + name)); };
+const size = (s: string) => resolveSvgSize(s);
+
+// ---- resolveSvgSize ----
+check('explicit px width/height win', (() => { const r = size('<svg width="800" height="600" viewBox="0 0 10 10"></svg>'); return r.width === 800 && r.height === 600; })());
+check('percentage width falls back to viewBox', (() => { const r = size('<svg width="100%" viewBox="0 0 812 640"></svg>'); return r.width === 812 && r.height === 640; })());
+check('viewBox only', (() => { const r = size('<svg viewBox="0 0 400 300"></svg>'); return r.width === 400 && r.height === 300; })());
+check('unit suffix stripped', (() => { const r = size('<svg width="120px" height="90px"></svg>'); return r.width === 120 && r.height === 90; })());
+check('comma-separated viewBox', (() => { const r = size('<svg viewBox="0,0,50,40"></svg>'); return r.width === 50 && r.height === 40; })());
+check('nothing → default 800x600', (() => { const r = size('<svg></svg>'); return r.width === 800 && r.height === 600; })());
+
+// ---- rasterizerScript: must be valid JS + its emitted size logic must actually work ----
+const src = rasterizerScript();
+check('rasterizerScript returns non-empty string', typeof src === 'string' && src.length > 200);
+check('defines svgToPngBlob', /function\s+svgToPngBlob\s*\(/.test(src));
+check('emits PNG via toBlob', src.includes('toBlob') && src.includes('image/png'));
+check('honors scale + background', src.includes('scale') && src.includes('background'));
+check('clamps to 8192', src.includes('8192'));
+check('emitted script is syntactically valid JS', (() => { try { new Function(src + '\nreturn typeof svgToPngBlob === "function";')(); return true; } catch { return false; } })());
+
+// Execute the EMITTED __svgSize (pure string logic, no DOM) — this catches regex-escaping bugs in
+// the generated code that the string-`includes` smoke checks above cannot. Mirrors resolveSvgSize.
+const emittedSvgSize = new Function(src + '\nreturn __svgSize;')() as (s: string) => { width: number; height: number };
+check('emitted __svgSize: viewBox-only splits on whitespace', (() => { const r = emittedSvgSize('<svg width="100%" viewBox="0 0 812 640"></svg>'); return r.width === 812 && r.height === 640; })());
+check('emitted __svgSize: comma-separated viewBox', (() => { const r = emittedSvgSize('<svg viewBox="0,0,50,40"></svg>'); return r.width === 50 && r.height === 40; })());
+check('emitted __svgSize: explicit px wins', (() => { const r = emittedSvgSize('<svg width="640" height="480" viewBox="0 0 10 10"></svg>'); return r.width === 640 && r.height === 480; })());
+check('emitted __svgSize matches resolveSvgSize on a Mermaid-shaped SVG', (() => {
+  const svg = '<svg id="m1" width="100%" viewBox="0 0 917 523" style="max-width: 917px;"></svg>';
+  const a = resolveSvgSize(svg), b = emittedSvgSize(svg);
+  return a.width === b.width && a.height === b.height && a.width === 917 && a.height === 523;
+})());
+
+console.log(`\nraster.selftest: ${pass} passed, ${fail} failed`);
+if (fail > 0) process.exit(1);

package/src/raster.ts

@@ -0,0 +1,79 @@
+/**
+ * Browser PNG rasterizer for call-flow diagrams — Node-free, Web-APIs-only. The library never holds
+ * an SVG (Mermaid renders it client-side), so this is a BROWSER helper: `resolveSvgSize` is a pure,
+ * testable size reader, and `rasterizerScript()` returns injectable JS defining `svgToPngBlob`.
+ * A host page (dia today; the lib's gallery HTML later) injects the script and calls the global.
+ */
+
+/** Intrinsic pixel size of an SVG string: explicit px width/height, else viewBox, else a default. */
+export function resolveSvgSize(svgString: string): { width: number; height: number } {
+  const DEFAULT = { width: 800, height: 600 };
+  const attr = (name: string): string | undefined => {
+    const m = new RegExp(`\\b${name}\\s*=\\s*["']([^"']*)["']`).exec(svgString);
+    return m ? m[1] : undefined;
+  };
+  const px = (s: string | undefined): number | null => {
+    if (!s || s.includes('%')) return null; // reject "100%" etc.
+    const n = parseFloat(s);                 // "120px" → 120
+    return Number.isFinite(n) && n > 0 ? n : null;
+  };
+  const w = px(attr('width'));
+  const h = px(attr('height'));
+  if (w && h) return { width: w, height: h };
+  const vb = attr('viewBox');
+  if (vb) {
+    const p = vb.trim().split(/[\s,]+/).map(Number);
+    if (p.length === 4 && p[2] > 0 && p[3] > 0) return { width: w ?? p[2], height: h ?? p[3] };
+  }
+  return { width: w ?? DEFAULT.width, height: h ?? DEFAULT.height };
+}
+
+/**
+ * Injectable browser JS (a function declaration) defining `svgToPngBlob(svgEl, { scale, background })`.
+ * A host injects this string into an inline <script> (no bundler needed) and calls the function.
+ * Rasterizes a LIVE, already-rendered <svg>: clone → force explicit px size (from the same algorithm
+ * as resolveSvgSize) → data-URL into an Image → draw onto a scaled canvas (optional opaque background)
+ * → PNG Blob. Scale is clamped so the larger dimension stays ≤ 8192px (browser canvas caps). CSP-safe
+ * (no eval/new Function; uses a data: image URL — ensure any host CSP allows `img-src data:`).
+ */
+export function rasterizerScript(): string {
+  return `
+// size reader mirroring resolveSvgSize (viewBox is authoritative for Mermaid). Top-level so it is
+// unit-testable outside a browser (see raster.selftest.ts) — the DOM path below is browser-only.
+function __svgSize(str) {
+  function attr(name){ var m = new RegExp('\\\\b'+name+'\\\\s*=\\\\s*["\\']([^"\\']*)["\\']').exec(str); return m ? m[1] : undefined; }
+  function px(s){ if(!s || s.indexOf('%')>=0) return null; var n=parseFloat(s); return (isFinite(n)&&n>0)?n:null; }
+  var w=px(attr('width')), h=px(attr('height'));
+  if(w&&h) return {width:w,height:h};
+  var vb=attr('viewBox');
+  if(vb){ var p=vb.trim().split(new RegExp('[\\\\s,]+')).map(Number); if(p.length===4&&p[2]>0&&p[3]>0) return {width:(w||p[2]),height:(h||p[3])}; }
+  return {width:(w||800),height:(h||600)};
+}
+async function svgToPngBlob(svg, opts) {
+  opts = opts || {};
+  var scale = opts.scale || 2;
+  var background = (opts.background == null) ? null : opts.background;
+  var clone = svg.cloneNode(true);
+  if(!clone.getAttribute('xmlns')) clone.setAttribute('xmlns','http://www.w3.org/2000/svg');
+  var size = __svgSize(new XMLSerializer().serializeToString(clone));
+  var W = size.width, H = size.height;
+  clone.setAttribute('width', W);
+  clone.setAttribute('height', H);
+  var str = new XMLSerializer().serializeToString(clone);
+  // --- clamp effective scale to the canvas cap ---
+  var eff = scale, MAX = 8192, big = Math.max(W, H);
+  if (big * eff > MAX) eff = MAX / big;
+  // --- SVG → Image → canvas → PNG ---
+  var url = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(str);
+  var img = new Image();
+  await new Promise(function(res, rej){ img.onload = res; img.onerror = function(){ rej(new Error('SVG failed to load for rasterization')); }; img.src = url; });
+  var canvas = document.createElement('canvas');
+  canvas.width = Math.max(1, Math.round(W * eff));
+  canvas.height = Math.max(1, Math.round(H * eff));
+  var ctx = canvas.getContext('2d');
+  if (background) { ctx.fillStyle = background; ctx.fillRect(0, 0, canvas.width, canvas.height); }
+  ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+  return await new Promise(function(res, rej){ canvas.toBlob(function(b){ b ? res(b) : rej(new Error('canvas.toBlob returned null')); }, 'image/png'); });
+}
+`.trim();
+}

package/src/resolver.selftest.ts

@@ -0,0 +1,225 @@
+/**
+ * Cascade tier + queue-priority rendering proof. Run: `pnpm test:resolver`.
+ *
+ * Tiers group by RING ORDER (ordinal-order, or the manifest write-key
+ * callqueue-agent-dispatch-order-ordinal) — the real Linear Cascade rounds, NOT the
+ * cross-queue priority. Queue priority (lower = higher) is shown once when the queue
+ * shares one non-default value, per-agent when it varies, and hidden at the default (0).
+ */
+import { resolveFlow } from './resolver.js';
+import type { Snapshot, FlowGraph, NodeKind } from './model.js';
+
+let pass = 0,
+  fail = 0;
+const check = (name: string, cond: boolean) => {
+  cond ? (pass++, console.log('  ok   ' + name)) : (fail++, console.log('  FAIL ' + name));
+};
+
+function snap(agents: Record<string, unknown>[]): Snapshot {
+  return {
+    meta: { domain: 'testco.12345.service' },
+    callqueues: [{ callqueue: '9100', description: 'open', 'callqueue-dispatch-type': 'Linear Cascade' }],
+    agentsByQueue: { '9100': agents },
+    users: [
+      { user: '100', 'name-first-name': 'Debbi', 'name-last-name': 'Smith' },
+      { user: '103', 'name-first-name': 'Emily', 'name-last-name': 'Laugle' },
+      { user: '102', 'name-first-name': 'Elizabeth', 'name-last-name': 'Ross' },
+    ],
+  };
+}
+const linesOf = (g: FlowGraph, kind: NodeKind) => (g.nodes.find((n) => n.kind === kind)?.lines ?? []).join('\n');
+
+// ---- ring-order tiers + uniform non-default priority shown once ----
+{
+  const g = resolveFlow(
+    snap([
+      { 'callqueue-agent-id': 'sip:100@x', 'ordinal-order': 1, 'callqueue-agent-dispatch-queue-priority-ordinal': 3 },
+      { 'callqueue-agent-id': 'sip:103@x', 'ordinal-order': 1, 'callqueue-agent-dispatch-queue-priority-ordinal': 3 },
+      { 'callqueue-agent-id': 'sip:102@x', 'ordinal-order': 2, 'callqueue-agent-dispatch-queue-priority-ordinal': 3 },
+    ]),
+    { kind: 'queue', ref: '9100' },
+  );
+  const a = linesOf(g, 'agents');
+  check('tier by ring order: Tier 1 present', a.includes('Tier 1:'));
+  check('tier by ring order: Tier 2 present', a.includes('Tier 2:'));
+  check('round 1 = Debbi + Emily', /Tier 1:[\s\S]*Debbi[\s\S]*Emily[\s\S]*Tier 2:/.test(a));
+  check('round 2 = Elizabeth', /Tier 2:[\s\S]*Elizabeth/.test(a));
+  const q = linesOf(g, 'queue');
+  check('uniform 2+ priority → compact badge once at queue (P3️⃣)', q.includes('P3️⃣'));
+  check('no verbose "priority 3" wording', !/priority 3\b/.test(q));
+  check('priority NOT repeated per agent when uniform', !a.includes('P3️⃣'));
+}
+
+// ---- concise priority badge: nothing for 0 (blank) / 1 (baseline); P<keycap> for 2+ ----
+{
+  const g = resolveFlow(
+    snap([
+      { 'callqueue-agent-id': 'sip:100@x', 'ordinal-order': 1, 'callqueue-agent-dispatch-queue-priority-ordinal': 1 }, // baseline
+      { 'callqueue-agent-id': 'sip:103@x', 'ordinal-order': 1, 'callqueue-agent-dispatch-queue-priority-ordinal': 0 }, // blank
+      { 'callqueue-agent-id': 'sip:102@x', 'ordinal-order': 1, 'callqueue-agent-dispatch-queue-priority-ordinal': 2 }, // set → P2️⃣
+    ]),
+    { kind: 'queue', ref: '9100' },
+  );
+  const a = linesOf(g, 'agents');
+  check('concise: no Tier header (ring order uniform)', !a.includes('Tier 1:'));
+  check('concise: priority 2 shows P2️⃣ once', (a.match(/P2️⃣/g) ?? []).length === 1);
+  check('concise: baseline priority 1 shows no badge', !a.includes('P1️⃣'));
+  check('concise: blank priority 0 shows no badge', !a.includes('P0️⃣'));
+  check('concise: no verbose "priority" word on the roster', !/·\s*priority\b/.test(a));
+}
+
+// ---- manifest-preview write-key fallback still tiers ----
+{
+  const g = resolveFlow(
+    snap([
+      { 'callqueue-agent-id': 'sip:100@x', 'callqueue-agent-dispatch-order-ordinal': 1 },
+      { 'callqueue-agent-id': 'sip:102@x', 'callqueue-agent-dispatch-order-ordinal': 2 },
+    ]),
+    { kind: 'queue', ref: '9100' },
+  );
+  check('write-key fallback tiers (manifest preview)', linesOf(g, 'agents').includes('Tier 2:'));
+}
+
+// ---- all-default priority (0) → hidden ----
+{
+  const g = resolveFlow(
+    snap([
+      { 'callqueue-agent-id': 'sip:100@x', 'ordinal-order': 1 },
+      { 'callqueue-agent-id': 'sip:102@x', 'ordinal-order': 2 },
+    ]),
+    { kind: 'queue', ref: '9100' },
+  );
+  check('default (0) priority hidden', !/queue priority/.test(linesOf(g, 'queue')));
+}
+
+// ---- unanswered disposition: "Stay in queue" is drawn explicitly, not silently dropped ----
+// forward-no-answer disabled/empty = portal "If unanswered → Stay in queue"; forward-on-busy → vmail.
+{
+  const base: Snapshot = {
+    meta: { domain: 'testco.12345.service' },
+    callqueues: [{ callqueue: '9102', description: 'office', 'callqueue-dispatch-type': 'Linear Cascade' }],
+    agentsByQueue: { '9102': [{ 'callqueue-agent-id': 'sip:100@x', 'ordinal-order': 1 }] },
+    users: [{ user: '100', 'name-first-name': 'Debbi', 'name-last-name': 'Smith' }],
+  };
+  const stay = resolveFlow(
+    {
+      ...base,
+      answerrulesByUser: {
+        '9102': [
+          {
+            'time-frame': '*',
+            enabled: 'yes',
+            'forward-no-answer': { parameters: [], enabled: 'no' }, // Stay in queue
+            'forward-on-busy': { parameters: ['vmail_500'], enabled: 'yes' },
+          },
+        ],
+      },
+    },
+    { kind: 'queue', ref: '9102' },
+  );
+  const stayEdge = stay.edges.find((e) => e.label === 'if unanswered · stays in queue');
+  check('stay-in-queue: explicit unanswered edge is drawn', !!stayEdge);
+  check('stay-in-queue: unanswered edge emanates from the agents node', !!stayEdge && stayEdge.from === 'agents_9102');
+  check('stay-in-queue: back-edge leaf points at the queue node', !!stayEdge && stayEdge.to.startsWith('ref_queue_9102'));
+  check('stay-in-queue: if-unavailable → voicemail still shown', stay.edges.some((e) => e.label === 'if unavailable' && stay.nodes.find((n) => n.id === e.to)?.kind === 'voicemail'));
+
+  // When forward-no-answer IS a real target, route there (no "stays in queue" leaf).
+  const toVm = resolveFlow(
+    {
+      ...base,
+      callqueues: [{ callqueue: '9101', description: 'tech', 'callqueue-dispatch-type': 'Linear Cascade' }],
+      agentsByQueue: { '9101': [{ 'callqueue-agent-id': 'sip:100@x', 'ordinal-order': 1 }] },
+      answerrulesByUser: {
+        '9101': [
+          {
+            'time-frame': '*',
+            enabled: 'yes',
+            'forward-no-answer': { parameters: ['vmail_500'], enabled: 'yes' },
+          },
+        ],
+      },
+    },
+    { kind: 'queue', ref: '9101' },
+  );
+  check('routed unanswered: no "stays in queue" leaf when a target is set', !toVm.edges.some((e) => e.label === 'if unanswered · stays in queue'));
+  check('routed unanswered: no answer / timeout edge present', toVm.edges.some((e) => e.label === 'no answer / timeout'));
+}
+
+// ---- AA "Add Tier": a keypress that opens a second-level menu ----
+// Shape (confirmed live): the tier's prompt id (900185) exists ONLY in the dialplan, as a sibling
+// `Prompt_900185.` rule family in the SAME AA dialplan. The /autoattendants detail nests the tier as
+// `option-5.auto-attendant` with no id, so the two join on the keypress digit. Fictional ids here.
+{
+  const aaSnap: Snapshot = {
+    meta: { domain: 'testco.12345.service' },
+    autoattendants: [{ user: '9000', 'attendant-name': 'aa_open', 'starting-prompt': 'Prompt_900001' }],
+    users: [{ user: '1043', 'name-first-name': 'Ada', 'name-last-name': 'Byron' }],
+    attendantDetails: {
+      '9000': {
+        'attendant-name': 'aa_open',
+        user: '9000',
+        'starting-prompt': 'Prompt_900001',
+        'time-frame': '*',
+        'auto-attendant': {
+          'option-2': { 'destination-application': 'to-user-residential', 'destination-user': '1043' },
+          'option-5': {
+            description: 'AA designer: press 5 for tier More options',
+            audio: { 'file-script-text': 'More options' },
+            'auto-attendant': {
+              'option-1': { 'destination-application': 'sip:start@directory', 'destination-user': '900186' },
+            },
+          },
+        },
+      },
+    },
+    attendantDialrulesByExt: {
+      '9000': [
+        { 'dial-rule-matching-to-uri': 'Prompt_900001.Case_1', 'dial-rule-application': 'Announce', 'dial-rule-translation-destination-user': '900013' },
+        { 'dial-rule-matching-to-uri': 'Announce_900013.Done', 'dial-rule-application': 'Prompt', 'dial-rule-translation-destination-user': '900001' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900001.Case_2', 'dial-rule-application': 'to-user-residential', 'dial-rule-translation-destination-user': '1043' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900001.Case_4', 'dial-rule-application': 'Announce', 'dial-rule-translation-destination-user': '900014' },
+        { 'dial-rule-matching-to-uri': 'Announce_900014.Done', 'dial-rule-application': 'hangup', 'dial-rule-translation-destination-user': '' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900001.Case_5', 'dial-rule-application': 'Prompt', 'dial-rule-translation-destination-user': '900185' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900001.Default', 'dial-rule-application': 'Prompt', 'dial-rule-translation-destination-user': '900001' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900185.Case_1', 'dial-rule-application': 'sip:start@directory', 'dial-rule-translation-destination-user': '900186' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900185.Case_9', 'dial-rule-application': 'Prompt', 'dial-rule-translation-destination-user': '900001' },
+        { 'dial-rule-matching-to-uri': 'Prompt_900185.Default', 'dial-rule-application': 'Prompt', 'dial-rule-translation-destination-user': '900185' },
+      ],
+    },
+  };
+  const g = resolveFlow(aaSnap, { kind: 'attendant', ref: '9000' });
+  const sub = g.nodes.find((n) => n.id === 'aa_9000_p900185');
+
+  check('tier: press 5 is a submenu node, not a "Play prompt" leaf', !!sub && sub.kind === 'attendant');
+  check('tier: no dead-end Play prompt for the tier id', !g.nodes.some((n) => n.id === 'aaprompt_9000_900185'));
+  check('tier: submenu is labelled with its keypress', !!sub && sub.label === '🔀 Submenu (press 5)');
+  check('tier: submenu carries its own menu-prompt script', !!sub && sub.sub === '“More options”');
+  check('tier: menu edge "press 5" lands on the submenu', g.edges.some((e) => e.label === 'press 5' && e.to === 'aa_9000_p900185'));
+  check(
+    'tier: the tier\'s own options render below it',
+    g.edges.some((e) => e.from === 'aa_9000_p900185' && e.label === 'press 1' && e.to === 'directory'),
+  );
+  check(
+    'tier: the tier\'s no-key default repeats ITS greeting, not the top menu\'s',
+    g.edges.some((e) => e.from === 'aa_9000_p900185' && e.label === 'no key / timeout' && e.to === 'aarepeat_9000_900185'),
+  );
+  check(
+    'tier: a key back to the parent prompt draws a loops-back leaf, not infinite recursion',
+    g.edges.some((e) => e.from === 'aa_9000_p900185' && e.kind === 'ref' && e.label === 'press 9'),
+  );
+  check('tier: top-level keys still resolve', g.edges.some((e) => e.label === 'press 2' && e.to === 'user_1043'));
+
+  // A played message is never a dead end: `Announce_<id>.Done` says where the call goes next.
+  check(
+    'announce: message returning to its menu reuses the shared Repeat greeting node',
+    g.edges.some((e) => e.from === 'aaannounce_9000_900013' && e.label === 'then' && e.to === 'aarepeat_9000_900001'),
+  );
+  check(
+    'announce: a non-menu .Done target routes normally (hang up)',
+    g.edges.some((e) => e.from === 'aaannounce_9000_900014' && e.label === 'then' && g.nodes.find((n) => n.id === e.to)?.kind === 'hangup'),
+  );
+  check('announce: no message node is left without an outgoing edge', ['aaannounce_9000_900013', 'aaannounce_9000_900014'].every((id) => g.edges.some((e) => e.from === id)));
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+if (fail) throw new Error(`${fail} check(s) failed`);